# AgentStatus

> The run’s state in one pill, announced to screen readers.

Source: https://agent-ui-kit-demo.vercel.app/docs/components/agent-status

## Installation

From npm:

```bash
npm i @dgesteves/agent-ui-kit ai
```

```tsx
import { AgentStatus, deriveAgentState } from '@dgesteves/agent-ui-kit';
import '@dgesteves/agent-ui-kit/styles.css'; // once per app, or @import '@dgesteves/agent-ui-kit/tailwind.css' with Tailwind v4
```

Or as source, with the shadcn CLI:

```bash
npx shadcn@latest add @agent-ui-kit/agent-status
```

```tsx
import { AgentStatus } from '@/components/agent-ui/agent-status';
import { deriveAgentState } from '@/components/agent-ui/lib/ai';
```

## Usage

```tsx
const last = messages.findLast((m) => m.role === 'assistant');
// Waiting on a person (an approval, a client-side tool) wins over "working".
const { state, detail } = deriveAgentState({ status, message: last, pendingClientTools: ['review_changes'] });

<AgentStatus state={state} detail={detail} />
```

## API reference

### AgentStatus

A compact, live status pill for an agent run. State changes are announced
through a polite live region (assertive for errors and approval requests),
debounced so rapid transitions do not flood screen readers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` (required) | `AgentState` ('awaiting-approval' \| 'error' \| 'idle' \| 'thinking' \| 'working' \| 'done') |  |  |
| `label` | `string` |  | Overrides the default label for the state. |
| `detail` | `string` |  | Secondary detail, e.g. the tool being run. |
| `startedAt` | `number` |  | Epoch ms when the run started. Shows a live elapsed timer while active. |
| `elapsedMs` | `number` |  | Fixed elapsed time to show (e.g. the final run duration). Takes precedence over `startedAt`. |
| `announce` | `boolean` | `true` | Announce state changes to assistive tech. |
| `size` | `'sm' \| 'md'` | `'md'` |  |

Other props go to the root `<div>`: `className`, `id`, `aria-*`, `data-*` and event handlers.

### AgentState

```ts
type AgentState = 'awaiting-approval' | 'error' | 'idle' | 'thinking' | 'working' | 'done';
```

## Accessibility

- Changes are announced through a live region, debounced by 350 ms so quick flips aren’t read one by one. Approvals and errors are assertive; everything else is polite.
- Render one `AgentStatus` per run with `announce` on; pass `announce={false}` to any copy, or the state is read twice.
- Each state has an icon and a word. The thinking shimmer and the spinner run only without `prefers-reduced-motion`.

## Theming

Slots (`data-slot`): `agent-status`.

- `data-state` on `agent-status`: 'awaiting-approval' | 'error' | 'idle' | 'thinking' | 'working' | 'done'

Tokens it uses: `--aui-accent`, `--aui-accent-fg`, `--aui-border`, `--aui-fg`, `--aui-fg-muted`, `--aui-fg-subtle`, `--aui-font-mono`, `--aui-font-sans`, `--aui-hot`, `--aui-hot-fg`, `--aui-surface`. See https://agent-ui-kit-demo.vercel.app/docs/getting-started#theming.