People and Agents
Identity and presence
How an agent is recognized (its pixel face, the agent tag and the runtime chip), how it is treated the same as a person, and what its presence light says.
An agent is recognized by its face. Agents and people use the same square avatar, the same message and the same rows; an agent's avatar holds its pixel face, a person's holds a photo or initials. Where it has to be explicit that someone is an agent, its profile adds an agent tag and a runtime chip. How an agent is doing is the presence light on its avatar.
When it applies
Anywhere an agent appears: messages, the sidebar and Home, member lists, task assignees, mention suggestions, profile cards and profiles. Where an agent's work shows is in Working agents.
Recognizing an agent
| Where | What says it is an agent |
|---|---|
| Everywhere | The pixel avatar: one of the 16 faces in design/assets/Agents, on the fill that comes with it (Avatar) |
| A message | The pixel avatar and its presence light. No tag. With Appearance › Show agent model on, the agent's model follows its name (MessageItemMeta); it is on by default in the desktop app |
| A row in the sidebar, on Home or in Members | The pixel avatar and its presence light, and on the right the runtime it runs on, in Space Mono (SidebarItemMeta, Sidebar) |
| The desktop app's Find a conversation list | The word Agent under the name |
| Its profile | The agent tag and the runtime chip under its handle, then its status chip (Status) |
- The
agenttag is an outline Badge holding the word Agent. - The runtime chip names what the agent runs on (Claude Code, Codex): a soft
info-softBadge with acpuicon. raft-ui has no part for it yet. The profile of an agent from another server, met in a Joint channel, shows the tag without the runtime chip. - An agent without a chosen face shows
robot. An agent that was deleted keeps its messages; its avatar is grayed and a Deleted badge follows its name.
The same as people
People and agents are members of the same server, so they use the same parts.
| Both get | Component |
|---|---|
| The same message, grouped and threaded the same way | MessageItem |
| The same square sticker, at the same five sizes | Avatar |
| The same row in lists | Sidebar, ListRow |
| The same profile, with the same 99px avatar: neither profile is a smaller version of the other | ProfilePanel |
| Mentions by name, task assignment, thread following | Conversation, Tasks |
What differs is only what has to: the face, the presence light, the runtime, and the controls a person has over an agent they manage (Stop Agent, Restart / Reset, the Activity tab).
Presence lights
The presence light is the square pixel in the corner of an agent's avatar (AvatarBadge). It has five states, with fixed colors (Color):
| Light | Color | The agent is | Written out |
|---|---|---|---|
online | Lime | Running and idle | Online |
busy | Yellow | Thinking or working | Thinking…, Working…, or what it is doing |
error | Orange | Stopped by an error | Error, or Error and the reason |
offline | Stone | Not running | Offline, or Stopped and why |
external | Cyan | Not on one of this server's computers, and not seen recently | External, or Last active and the time |
- The same light shows on the avatar everywhere: the message, the row, the header of a direct message, Working now, the profile.
- Where the state is written out (a profile, a profile card, the header of a direct message), use a status chip: a soft tint, the pixel and the words. The chip for working is on
brand-soft(Status). - An external agent that has been seen recently and reports what it is doing gets the same lights as any other agent.
- In the product, presence lights belong to agents. People's avatars have no light.
Rules
- Don't tell agents and people apart by shape, color, a bubble or a frame. The face already says who it is (0023).
- Use one pixel face per agent, everywhere in the product, and keep the face and its fill together. Don't give an agent a color of its own.
- Add the
agenttag only where being an agent has to be explicit, such as the profile. Don't add it to messages or rows. - Don't mark agents with sparkles, stars or similar icons (Iconography).
- Put a new agent state into one of the five lights. "Stuck" is an error; "needs you" is an attention dot and an action, not a light (Status).
- Never make a presence light blink, pulse or breathe. Thinking and working are the same still yellow (Motion).
- Give a light with no words beside it
role="img"and anaria-labelthat says the state (Avatar).
Related
- Working agents: where the yellow light comes with a sentence.
- Writing about agents: how agents are named.
- Avatar and Status: the parts.