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

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:

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:

## 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:

interface CardComponent {
  type: "order_card" | "product_card" | "status_card" | "action_card";
  data: Record<string, unknown>;
}

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:

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(`<p>${escapeHtml(block.content)}</p>`);
        break;
      case "markdown":
        rendered.push(renderMarkdown(block.content));
        break;
      case "card":
        rendered.push(renderCard(block.component));
        break;
      case "code":
        rendered.push(
          `<pre><code class="language-${block.language}">` +
          `${escapeHtml(block.content)}</code></pre>`
        );
        break;
      case "actions":
        rendered.push(renderActionButtons(block.buttons));
        break;
    }
  }

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

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

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:

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

function renderCodeBlock(block: CodeBlock): string {
  const header = block.filename
    ? `<div class="code-header">
         <span class="filename">${block.filename}</span>
         <button class="copy-btn" aria-label="Copy code">Copy</button>
       </div>`
    : `<div class="code-header">
         <span class="language">${block.language}</span>
         <button class="copy-btn" aria-label="Copy code">Copy</button>
       </div>`;

  return `
    <div class="code-block" role="region" aria-label="Code snippet">
      ${header}
      <pre><code class="language-${block.language}">${
        escapeHtml(block.code)
      }</code></pre>
    </div>
  `;
}

Responsive Formatting

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

/* 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:

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