# Agent Avatar

Who is talking in a multi-agent chat: tint colour, name and role.

- Category: AI & Agents
- Page: https://wunderui.com/components/agent-avatar
- Tier: Core and Pro

## Install

Agent Avatar ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { AgentAvatar, AgentAvatarSize, AgentAvatarStatus } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { AgentAvatar } from "@wunderui/react"

export function Speaker() {
  return <AgentAvatar name="Planner" role="Breaks the task into steps" initials="PL" color="indigo" status="working" />
}
```

Expected result: You should see a 28 px indigo circle with PL and a small pulsing indigo dot on its top right, and next to it Planner in medium weight with Breaks the task into steps in grey underneath.

## When to use

### Use Agent Avatar for

- Saying which agent wrote a message in a thread that has more than one
- The header of a run or a card that belongs to one agent: tint, name and role
- A roster of the agents of a run, with Agent Status next to each

### Use something else

- [Avatar](https://wunderui.com/components/avatar) for a person, a single assistant, or any avatar that needs an image or a presence dot
- [Agent Status](https://wunderui.com/components/agent-status) for what an agent is doing right now, in words, with the step and the time
- [Handoff Divider](https://wunderui.com/components/handoff-divider) for the moment one agent passes the conversation to another

## Behavior

What the avatar does with its content, its size, assistive technology and motion.

- **Content:** Name and role can be any content, initials are a string, and the colour is one of ten Avatar tints (indigo by default). Nothing is derived from the name.
- **Size:** Three sizes: small (24 px circle, 12 px name, 11 px role), medium (28, 13, 12, the default) and large (36, 14, 12). For bigger or an image, use the Avatar itself.
- **Wrapping:** Name and role wrap inside their column and break anywhere when a word has no space. The circle never shrinks, so put the avatar in a column of the width you want.
- **Status:** The indicator is a signal, not a report: it does not say which step, how long or why. Add Agent Status next to the avatar for that, so the state is a word and an icon too.
- **Assistive technology:** A screen reader reads initials, name, the state if set, then the role. Tint and dot are not announced, so keep the name in the message text and announce status changes in a status line.
- **Keyboard:** Not interactive and not in the tab order. Wrap it in your own link or button when a click should open the agent.
- **Motion:** Only the working indicator moves: it pulses in opacity in an endless loop.
- **Reduced motion:** With reduced motion on, the working dot stands still as solid indigo. The state is still spoken after the name.

## Anatomy

- `AgentAvatar`: An inline row that takes the width of its content, or of the column you put it in. It is a plain span: no role, no tab stop, no live region.
- `Avatar`: The library Avatar in 24, 28 (default) or 36 px: a circle in a mode-aware tint with matching letters. It never shows an image and has no border.
- `Initials`: Two letters in the circle, 12 px medium. You pass them in; they are not derived from the name.
- `Status indicator`: With a status: an 8 px dot on the top right corner. Idle is a hollow ring, working a pulsing indigo dot, failed a red dot; screen readers hear the state after the name.
- `Name`: The name in medium weight, 12 to 14 px by size. It wraps and breaks anywhere without spaces, so a long id cannot push the row wider.
- `Role`: The role in smaller secondary text under the name. Without a role the line is gone and the name sits centred beside the circle.

## Best practices

### When to use

- Use it to say which agent speaks in a multi-agent chat: tint, name and role. For one assistant or a person a plain Avatar is enough; mark a change of speaker with a Handoff Divider.

### Do

- Give each agent its own colour and keep it for the whole conversation. Name and role say the same in words, so the tint is never the only signal.
- Add a short role such as Reviewer or Checks the result, so people know what the agent is responsible for. Drop it in a long thread where roles are known.
- Pass the two-letter initials yourself. The avatar shows them as given and does not derive them from the name.
- Use the status for a quick signal of who is busy, and add Agent Status when people need the step, the time or the reason. A dot alone says little.
- Announce a status change in a status line near the thread. The indicator and spoken state update, but a screen reader does not announce the change.

### Don't

- Don't reuse a tint for two agents in one conversation. Name and role always render, but people scan the tint first.
- Don't build a person's message header from it. It stands for an agent; use an Avatar with a name for a person so the two are easy to tell apart.
- Don't use failed for an agent that merely returned nothing, and don't leave working on after the run ended. The dot is only as true as the state you pass.

## API reference

### AgentAvatar

| Prop | Type | Default | Description |
|---|---|---|---|
| initials* | string |  | The letters inside the circle, as given. Two letters fit; the string is not shortened or derived from `name`. Required. |
| name* | React.ReactNode |  | The agent's name, in medium weight next to the circle. A node, so it can be styled. Required. |
| className | string |  | Extra classes for the row, for example `self-start` in a column or a `max-w-*` to set the width the text wraps at. |
| color | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" \| "grey" | "indigo" | The tint of the circle: `indigo` (default), `blue`, `purple`, `pink`, `red`, `orange`, `yellow`, `green`, `alternative` or `grey`. |
| ring | boolean | false | A 2 px ring in the page colour, so avatars that overlap in a stack stay apart. |
| role | React.ReactNode |  | What the agent is responsible for, in 12 px secondary text under the name. A node. Leave it out to draw the name alone. |
| showName | boolean | true | `false` shows the avatar alone. The name and role stay in the page for screen readers. |
| size | "lg" \| "sm" \| "md" | "md" | `sm` (24 px), `md` (28 px, default) or `lg` (36 px). The name and the role scale with it. |
| status | "idle" \| "failed" \| "working" |  | `idle`, `working` or `failed`: the indicator on the top right of the circle. The state is also spoken after the name. Omit it for no indicator. |

## Examples

### Colour: the ten tints of the Avatar

### Size: small 24 px, medium 28 px, large 36 px

### Status: no indicator, idle, working, failed

### Content: name and role, name only, long text, an agent id

### Avatar only, ringed in a stack

## In context

### Multi-agent thread: every message starts with who sent it

A person gets a plain grey Avatar and each agent an AgentAvatar in its own tint. Switch the header between name and role and name only.

### Run roster: the avatar says who, AgentStatus says what it is doing

The dot says only idle, working or failed. AgentStatus beside it carries the full state with a word, an icon and the time, so it reads the same without colour, and you can pick a state to try it.

## For AI agents

`get_component("agent-avatar")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
