# Agent Status

A pill showing what a run is doing right now, with a live elapsed counter.

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

## Install

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

## Import

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

## Minimal usage

Then use it:

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

export function RunState({ startedAt }: { startedAt: Date }) {
  return <AgentStatus status="running" since={startedAt} />
}
```

Expected result: You should see a small indigo pill with a turning loader and Running, 0s, counting up once a second. Switch the status to done with an end time and it shows a green check and the fixed duration.

## When to use

### Use Agent Status for

- The state of one agent run: queued, running, waiting for a person, done, failed or cancelled
- The time a run has been in that state, or how long it took
- A header, a row of a run list or a card of a dashboard

### Use something else

- [Run Timeline](https://wunderui.com/components/run-timeline) for the steps of a run, each with its own status and duration
- [Usage Meter](https://wunderui.com/components/usage-meter) for spend against a budget
- [Badge](https://wunderui.com/components/badge) for a static label that is not the state of a run

## Behavior

What the pill does with its clock, its label, assistive technology and motion.

- **Clock:** Running and waiting count up once a second. A finished run with start and end times shows a fixed duration; with only a start time it keeps counting, by the second under an hour, then by the minute.
- **Format:** Under a minute it reads 47s, under an hour 4m 07s, then 2h 14m. An invalid start time, or an end before the start, causes no error, and without a readable start there is no counter.
- **First paint:** A live counter is empty on the server and the first client render, then fills in, so the pill widens. A fixed duration renders at once.
- **Label:** The default word per status, or your own label as a string. The pill neither wraps nor shrinks, so keep a custom label short.
- **Assistive technology:** A screen reader reads the pill as its text, like Running, 2m 14s. It announces no change, and the counter is deliberately not a live region, or it would speak every second.
- **Failure and abort:** Failed is red and cancelled is grey, each with its own icon and word. Use cancelled when a person stopped the run and failed when it broke.
- **Motion:** Only the running icon moves: it turns. Nothing else animates, and a status change swaps tint, icon and word at once.
- **Reduced motion:** With reduced motion on, the loader stands still. The word Running and the counter, which still ticks, say what is going on.

## Anatomy

- `AgentStatus`: A pill with a 1 px border in 12 px medium text. Tint, icon and word follow the status; it is a plain span with no role and no live region.
- `Icon`: A 14 px Lucide icon (12 px in the small size) in the text colour. Running shows a loader that turns when motion is allowed; the icon is decorative and the word carries the state.
- `Label`: The status word (Idle, Running, Waiting for you, Done, Failed, Cancelled) or your own label. It never wraps; the pill takes the width of its text.
- `Counter`: A time such as 2m 14s in regular weight with tabular figures, shown when a start time is set. It appears after the first client render, so the server never prints a stale time.

## Best practices

### When to use

- Use it for the state of one run, with the time it has been in that state. For spend against a budget use Usage Meter; for the steps of a run use Run Timeline.

### Do

- Pass a start time for running and waiting; both tick every second. For a finished run pass an end time too, and the pill shows the fixed duration.
- Use waiting when a person has to act (Waiting for you) and idle for a queued run. A run blocked on an approval is waiting, not running.
- Say a change in a status line next to the pill, like Failed at step 3, nothing was sent. The pill is silent, and a colour or icon never carries the state alone.
- Pass a new start time when the status changes, so the counter shows how long the run has been in the new state. Keep the old one only if the counter means the whole run.
- Override the label only for a more precise word such as Needs approval or Retrying, and keep the status that matches the run so tint and icon stay right.

### Don't

- Don't build the pill from a Badge and a Spinner. It has one icon, one tint and one word per state, and its counter keeps running when a run stalls.
- Don't show failed or cancelled without saying what was already done. The pill says the run stopped, not what it left behind: add that sentence next to it.

## API reference

### AgentStatus

| Prop | Type | Default | Description |
|---|---|---|---|
| status* | "cancelled" \| "paused" \| "running" \| "done" \| "idle" \| "failed" \| "waiting" |  | The state of the run: `idle`, `running`, `waiting`, `paused`, `done`, `failed` or `cancelled`. Picks the tint, the icon and the default word. `paused` is a held run: a static pause icon and no live counter. |
| className | string |  | Extra classes for the pill, for example a margin. |
| endedAt | Date \| string \| number |  | When a finished run ended. With `since` the pill shows the fixed duration `endedAt − since`. Ignored while the status is `running` or `waiting`. |
| label | string |  | Replaces the default word of the status, for example `Needs approval`. A string, kept on one line. |
| showElapsed | boolean | true | `true` by default. Set `false` to hide the counter even when `since` is set, for a row that already carries a timestamp. |
| since | Date \| string \| number |  | When the run entered this status, or when it started when you also pass `endedAt`. A `Date`, an ISO string or a timestamp in milliseconds. Starts the counter. |
| size | "sm" \| "default" | "default" | `default` (12 px text, 14 px icon) or `sm` (11 px text, 12 px icon) for dense rows. |

## Examples

### Counter: live, the final duration, the time since the end, hidden

### Size: default and small

### Label: the word of the status or a more precise one

### Paused: a held run with a static icon

## In context

### Run header: the state decides the buttons and the sentence

Pick a state under the card, or press a button to move the run on. The status line under the buttons is a live region that says what happened, because the pill is silent.

### Run list: live rows count, finished rows are fixed

Five runs in the states a list shows at once. The running and waiting rows keep counting, and the finished rows show the duration between start and end and never change while you read them.

## For AI agents

`get_component("agent-status")`

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