Agent Status
ProThe state of one agent run as a pill: queued, running, waiting for you, done, failed or cancelled, with the time it has been there.
Playground
Installation
Agent Status comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import { AgentStatus } from "@wunderui/react"Then use it:
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 for
- Run Timeline for the steps of a run, each with its own status and duration
- Usage Meter for spend against a budget
- Badge for a static label that is not the state of a run
Counter
A live run counts up from its start. A finished run with an end time shows its fixed duration, and without an end time it shows the time since the start and keeps counting.
Size
Use the small pill in dense rows, where the row already carries the context.
Label
Keep the status and change the word only when a more precise one helps. The pill never wraps.
Paused
A paused run shows a pause icon and no live counter. Pass since with endedAt (the moment of the pause) to show how long it ran before it was held.
Behavior and motion
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
The figure marks a running pill with a counter. A pill without a start time has no counter and no number 4.
- 1data-slot="agent-status"
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.
- 2
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.
- 3
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.
- 4Optional
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
- 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.
- Do
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.
- Do
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.
- Do
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.
- Do
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
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 is a plain component, so the table lists every prop.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| status required | "cancelled" | "paused" | "running" | "done" | "idle" | "failed" | "waiting" | — | The state of the run: , , , , , or . Picks the tint, the icon and the default word. is a held run: a static pause icon and no live counter. |
| since | Date | string | number | — | When the run entered this status, or when it started when you also pass . A , an ISO string or a timestamp in milliseconds. Starts the counter. |
| endedAt | Date | string | number | — | When a finished run ended. With the pill shows the fixed duration . Ignored while the status is or . |
| label | string | — | Replaces the default word of the status, for example . A string, kept on one line. |
| showElapsed | boolean | true | by default. Set to hide the counter even when is set, for a row that already carries a timestamp. |
| size | "sm" | "default" | "default" | (12 px text, 14 px icon) or (11 px text, 12 px icon) for dense rows. |
| className | string | — | Extra classes for the pill, for example a margin. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("agent-status")The full library index for assistants is at /llms.txt.
Related components
- Done420 tok$0.01640ms
Input
status: overdue, age: 30+ daysOutput
14 invoices, $42,860 in total - Done3,420 tok$0.042.1s
Input
14 invoice idsOutput
14 contacts, all with an email address - Running2,310 tok
Input
template: invoice-overdue-30 - Pending
Input
to: 14 recipients - PendingLog the result
AI & Agents5 stylesProRun TimelineEvery step of a run in order, with duration, tokens and expandable input/output.Send 14 payment reminders
Medium riskEmails the contact on every invoice more than 30 days overdue. Sent emails cannot be recalled.
2 min agoPOST /email/bulk to: 14 recipients template: invoice-overdue-30 dry_run: false
AI & Agents5 stylesProApproval CardThe human-in-the-loop gate: what the agent wants to do, how risky it is, approve or reject.