Format agent messages

Agents can use Markdown to format the text of messages that they send.

By default, Teams recognizes a basic subset of Markdown syntax and HTML markup. Most agent scenarios should enable extended Markdown mode to take advantage of additional formatting capabilities.

Default formatting features

By default, Teams recognizes the following markup syntax:

Extended Markdown mode

Extended Markdown mode supports additional CommonMark and GitHub Flavored Markdown features to enhance agent expressiveness and better support the output of modern large language models (LLMs). It also enables progressive rendering of formatting when streaming messages.

Extended Markdown mode is recommended for all messaging scenarios that aren't strictly dependent on the default formatting behavior. It's opt-in because it's not fully backwards compatible with the default formatting behavior, and does not support arbitrary HTML.

Enable extended Markdown mode

Extended Markdown mode is configured on a per-message basis. To enable it, set a message activity's textFormat property to extendedmarkdown before sending it.

var activity = new Activity
{
    Type = ActivityTypes.Message,
    Text = "### Sprint update\n\n- [x] Build completed\n- [ ] Deploy pending",
    TextFormat = "extendedmarkdown"
};

await app.Send(conversationId, activity);

const activity = 
  new MessageActivityInput("### Sprint update\n\n- [x] Build completed\n- [ ] Deploy pending")
    .withTextFormat('extendedmarkdown');

await app.send(conversationId, activity);

activity = Activity(
    type=ActivityTypes.message,
    text="### Sprint update\n\n- [x] Build completed\n- [ ] Deploy pending",
    text_format="extendedmarkdown"
)

await app.send(conversation_id, activity)

{
  "type": "message",
  "textFormat": "extendedmarkdown",
  "text": "### Sprint update\n\n- [x] Build completed\n- [ ] Deploy pending"
}

Extended Markdown mode features

In extended Markdown mode, Teams recognizes all of the Markdown features of the default formatting behavior, plus the following:

Fenced code blocks

Use triple backticks with a language identifier to display syntax-highlighted code in your agent messages.

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
```

Math equations

Use LaTeX/KaTeX syntax to render mathematical notation. Use single dollar signs for inline equations and double dollar signs for block equations.

Inline math: $E = mc^2$

Block math:

$$
\int_0^\infty f(x)dx
$$

Images

Use standard Markdown image syntax to render images in your agent messages.

![Build status](https://example.com/build-status.png)

Citations

Cite sources in your agent messages using [#] notation in the message text and providing citation details in the Activity entities array. For more information on how to add citations, see citations.

Tables

Use GitHub Flavored Markdown (GFM) table syntax to present structured data. Tables support column alignment using colons in the separator row.

| Feature | Status | Priority |
| :------ | :----: | -------: |
| Tables  |  Done  |     High |
| Math    |  Done  |     High |

In this example, the first column is left-aligned, the second is centered, and the third is right-aligned.

Task lists

Use task list syntax to display completed and pending items in your agent messages.

- [x] Checkout code
- [x] Install dependencies
- [x] Run unit tests
- [ ] Deploy to production

Adopt extended Markdown mode in existing agents

If you implemented your agent before extended Markdown mode was available, use the following guidance to update it:

• Remove any usage of HTML for message formatting, and use Markdown exclusively.
• Everywhere your implementation constructs or sends messages, adopt a pattern that allows specifying a textFormat. To enable progressive testing, specify the value markdown to temporarily retain the existing default behavior.
• As you transition messaging scenarios to use extended Markdown mode, test them with the latest Teams desktop, web, iOS, and Android clients.

Legacy formatting modes

Don't use the following legacy formatting modes in new development.

Message size limits

The agent message size limit is 100 KB. This is an approximate limit because it includes the message itself (text, image links, etc.), @-mentions, and reactions encoded as UTF-16. The 100 KB size limitation doesn't include base64 encoded images. During implementation, ensure that the size of the message itself is within 80 KB to guarantee successful message delivery.

If the agent message exceeds the size limit, the agent receives a 413 status code (RequestEntityTooLarge), which contains the error code MessageSizeTooBig.

Next steps

See also

• Build agents for Teams
• Adaptive Cards
• Format cards in Teams