# Agent avatar

An agent's mark: its role glyph on a tile tinted with the role's hue.

- Registry name: `agent-avatar` (`@candor/agent-avatar`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/agent-avatar

## Install

```bash
npx candor-ui add agent-avatar
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/agent-avatar`.
It brings in: chat, locale, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import { AgentBadge, AgentRolesProvider } from "@/components/agent-avatar"
import { Rocket } from "lucide-react"

export default function Example() {
  return (
    <div className="flex flex-col gap-3">
      <AgentBadge agent={{ id: "a", name: "Support agent", role: "assistant" }} />
      <AgentBadge agent={{ id: "b", name: "Research agent", role: "researcher" }} />
      <AgentBadge agent={{ id: "c", name: "Code reviewer", role: "reviewer" }} />
      <AgentRolesProvider roles={{ launcher: { Icon: Rocket, noun: "Launcher", hue: "var(--chart-4)" } }}>
        <AgentBadge agent={{ id: "d", name: "Release agent", role: "launcher" }} />
      </AgentRolesProvider>
    </div>
  )
}
```

## <AgentAvatar>

Props:

- `agent: AgentIdentity`: Who the agent is: id, display name and role.
- `size?: "sm" | "md" | undefined` (default `"md"`): md for message headers, sm for lists and chips.
- `className?: string | undefined`

## <AgentBadge>

Avatar plus name, with the role spelled out for screen readers.

Props:

- `agent: AgentIdentity`: Who the agent is: id, display name and role.
- `size?: "sm" | "md" | undefined` (default `"md"`): md for message headers, sm for lists and chips.
- `className?: string | undefined`

## <AgentRolesProvider>

The app's agent roles; nested providers add to (and can override) the ones above.

Props:

- `roles: Record<string, AgentRoleInfo>`: Role ids mapped to an icon, a noun and a hue.
- `children: React.ReactNode`

## Functions

### useAgentRoles

```ts
useAgentRoles()
```

Look up a role's glyph, noun and hue; unknown roles read as "Assistant".

## Strings (`agentAvatar`)

The fixed words, English by default. Override any of them under `agentAvatar` in `<LocaleProvider strings={{ agentAvatar: { … } }}>`; the table is exported as `agentAvatarStrings`.

- `assistant`: Assistant
- `orchestrator`: Orchestrator
- `planner`: Planner
- `researcher`: Researcher
- `analyst`: Analyst
- `designer`: Designer
- `coder`: Coder
- `reviewer`: Reviewer
- `tester`: Tester
- `roleAgent`: , {noun} agent

## Types

### AgentRoleInfo

```ts
{ Icon: LucideIcon; noun: string; hue: string }
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.