---
title: "Agent Response Formatting: Markdown, Rich Cards, and Structured Output for Chat UIs"
description: "Design effective agent response formatting using Markdown rendering, rich card components, interactive elements, tables, code blocks, and responsive layouts for chat interfaces."
canonical: https://callsphere.ai/blog/agent-response-formatting-markdown-rich-cards-structured-output-chat-uis
category: "Learn Agentic AI"
tags: ["Response Formatting", "Markdown", "Rich Cards", "Chat UI", "AI Agents"]
author: "CallSphere Team"
published: 2026-03-17T00:00:00.000Z
updated: 2026-05-06T16:38:42.397Z
---

# Agent Response Formatting: Markdown, Rich Cards, and Structured Output for Chat UIs

> Design effective agent response formatting using Markdown rendering, rich card components, interactive elements, tables, code blocks, and responsive layouts for chat interfaces.

## Plain Text Is Not Enough

An AI agent that returns walls of unformatted text is like a website without CSS — the information might be there, but users struggle to parse it. Response formatting transforms raw agent output into scannable, actionable, and visually clear communication.

Modern chat UIs support rich formatting: Markdown rendering, structured cards, interactive buttons, collapsible sections, and embedded media. The challenge is deciding which format to use for which type of content — and building a rendering pipeline that handles them all gracefully.

## Markdown as the Default Format

Markdown is the universal language of chat formatting. Most chat frameworks render it natively, and LLMs generate it well:

```mermaid
flowchart LR
    INPUT(["User intent"])
    PARSE["Parse plus
classify"]
    PLAN["Plan and tool
selection"]
    AGENT["Agent loop
LLM plus tools"]
    GUARD{"Guardrails
and policy"}
    EXEC["Execute and
verify result"]
    OBS[("Trace and metrics")]
    OUT(["Outcome plus
next action"])
    INPUT --> PARSE --> PLAN --> AGENT --> GUARD
    GUARD -->|Pass| EXEC --> OUT
    GUARD -->|Fail| AGENT
    AGENT --> OBS
    style AGENT fill:#4f46e5,stroke:#4338ca,color:#fff
    style GUARD fill:#f59e0b,stroke:#d97706,color:#1f2937
    style OBS fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style OUT fill:#059669,stroke:#047857,color:#fff
```

```python
def format_product_comparison(products: list[dict]) -> str:
    """Generate a Markdown-formatted comparison table."""
    if not products:
        return "No products found to compare."

    # Build header
    headers = ["Feature"] + [p["name"] for p in products]
    header_row = "| " + " | ".join(headers) + " |"
    separator = "| " + " | ".join(["---"] * len(headers)) + " |"

    # Build data rows
    features = ["Price", "Rating", "Battery Life", "Weight"]
    rows = []
    for feature in features:
        key = feature.lower().replace(" ", "_")
        row_data = [feature] + [str(p.get(key, "N/A")) for p in products]
        rows.append("| " + " | ".join(row_data) + " |")

    table = "\n".join([header_row, separator] + rows)
    return f"## Product Comparison\n\n{table}"
```

This produces clean Markdown tables that render nicely in any chat UI with Markdown support:

```markdown
## Product Comparison

| Feature      | Model A   | Model B   |
| ---          | ---       | ---       |
| Price        | $299      | $349      |
| Rating       | 4.5/5     | 4.7/5     |
| Battery Life | 8 hours   | 12 hours  |
| Weight       | 1.2 kg    | 1.0 kg    |
```

## Structured Card Components

For structured data like order summaries, product listings, or status updates, cards provide a cleaner experience than Markdown:

```typescript
interface CardComponent {
  type: "order_card" | "product_card" | "status_card" | "action_card";
  data: Record;
}

interface OrderCard extends CardComponent {
  type: "order_card";
  data: {
    orderId: string;
    status: "processing" | "shipped" | "delivered" | "returned";
    items: { name: string; quantity: number; price: number }[];
    total: number;
    estimatedDelivery: string | null;
    trackingUrl: string | null;
    actions: { label: string; action: string }[];
  };
}

// Example card data
const orderCard: OrderCard = {
  type: "order_card",
  data: {
    orderId: "ORD-7821",
    status: "shipped",
    items: [
      { name: "Wireless Mouse", quantity: 1, price: 29.99 },
      { name: "USB-C Hub", quantity: 1, price: 49.99 },
    ],
    total: 79.98,
    estimatedDelivery: "2026-03-20",
    trackingUrl: "https://tracking.example.com/926129",
    actions: [
      { label: "Track Package", action: "track_order:ORD-7821" },
      { label: "Start Return", action: "return_order:ORD-7821" },
    ],
  },
};
```

## Building a Response Rendering Pipeline

Agent responses often mix plain text, Markdown, and structured cards. Build a pipeline that handles all formats:

```typescript
type ResponseBlock =
  | { type: "text"; content: string }
  | { type: "markdown"; content: string }
  | { type: "card"; component: CardComponent }
  | { type: "code"; language: string; content: string }
  | { type: "image"; url: string; alt: string }
  | { type: "actions"; buttons: { label: string; action: string }[] };

interface AgentResponse {
  blocks: ResponseBlock[];
}

function renderAgentResponse(response: AgentResponse): string {
  // In a real implementation this returns JSX or DOM elements.
  // Here we show the rendering logic as pseudocode.
  const rendered: string[] = [];

  for (const block of response.blocks) {
    switch (block.type) {
      case "text":
        rendered.push(`

${escapeHtml(block.content)}

`);
        break;
      case "markdown":
        rendered.push(renderMarkdown(block.content));
        break;
      case "card":
        rendered.push(renderCard(block.component));
        break;
      case "code":
        rendered.push(
          `

```
` +
          `${escapeHtml(block.content)}
```

`
        );
        break;
      case "actions":
        rendered.push(renderActionButtons(block.buttons));
        break;
    }
  }

  return rendered.join("\n");
}

function escapeHtml(text: string): string {
  return text
    .replace(/&/g, "&")
    .replace(//g, ">");
}

function renderMarkdown(md: string): string { return md; }
function renderCard(card: CardComponent): string { return ""; }
function renderActionButtons(buttons: { label: string; action: string }[]): string { return ""; }
```

## Handling Code in Agent Responses

For technical agents, code formatting is critical. Implement syntax highlighting and copy-to-clipboard:

```typescript
interface CodeBlock {
  language: string;
  code: string;
  filename?: string;
  highlightLines?: number[];
}

function renderCodeBlock(block: CodeBlock): string {
  const header = block.filename
    ? `
         ${block.filename}
         Copy
       `
    : `
         ${block.language}
         Copy
       `;

  return `

      ${header}

```
${
        escapeHtml(block.code)
      }
```

  `;
}
```

## Responsive Formatting

Agent responses must work across screen sizes. Cards that look great on desktop can be unusable on mobile:

```css
/* Chat message container */
.agent-message {
  max-width: 80%;
  margin: 0.5rem 0;
}

/* Card grid - single column on mobile, multi on desktop */
.card-grid {
  display: grid;
  grid-template-columns: 1fr;
  gap: 0.75rem;
}

@media (min-width: 768px) {
  .card-grid {
    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  }
}

/* Tables scroll horizontally on small screens */
.agent-message table {
  display: block;
  overflow-x: auto;
  white-space: nowrap;
  -webkit-overflow-scrolling: touch;
}

/* Code blocks get horizontal scroll */
.agent-message pre {
  overflow-x: auto;
  max-width: 100%;
  padding: 1rem;
  border-radius: 0.5rem;
  font-size: 0.875rem;
}

/* Action buttons stack on mobile */
.action-buttons {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}

.action-buttons button {
  flex: 1 1 auto;
  min-width: 120px;
}
```

## Choosing the Right Format

Use this decision framework to select the appropriate format for each response type:

```python
FORMAT_DECISION_MAP = {
    "simple_answer": "text",
    "list_of_items": "markdown_list",
    "comparison": "markdown_table",
    "status_update": "card",
    "step_by_step": "markdown_numbered_list",
    "code_example": "code_block",
    "multiple_options": "action_buttons",
    "data_summary": "card_with_chart",
    "long_explanation": "markdown_with_headings",
}
```

The rule of thumb: use plain text for one-liner answers, Markdown for structured text, cards for entity-level data, and action buttons when the user needs to choose a path forward.

## FAQ

### How do I handle Markdown rendering when the LLM generates inconsistent formatting?

Post-process the LLM output before rendering. Common fixes include normalizing heading levels (LLMs sometimes skip from h2 to h4), ensuring list items use consistent markers, and sanitizing raw HTML that might appear in the Markdown. Use a library like remark or markdown-it with strict sanitization rules. Also add Markdown formatting guidelines to your system prompt.

### Should I render agent responses as streaming Markdown or wait for the full response?

Stream with incremental rendering for a better perceived performance. However, you need to handle partial Markdown gracefully — a table that is still being generated looks broken mid-stream. Buffer block-level elements (tables, code fences, lists) until they are complete, and stream paragraph text character by character. Most Markdown streaming libraries like react-markdown handle this well.

### How do I make action buttons within agent messages work with the conversation flow?

When a user clicks an action button, inject the button's text as a user message into the conversation history: "Track Package for ORD-7821." This keeps the conversation transcript coherent and auditable. On the backend, send both the display text and a structured action payload so the agent can handle it programmatically without re-parsing natural language.

---

#ResponseFormatting #Markdown #RichCards #ChatUI #AIAgents #AgenticAI #LearnAI #AIEngineering

---

Source: https://callsphere.ai/blog/agent-response-formatting-markdown-rich-cards-structured-output-chat-uis