Agent Status

Pro

Three small ways to show where an agent is: a mark that turns into a check, a dot that pulses while it works, and a badge with the status in words.

  • Read 50 invoices from the inbox1m 12s
  • Match 47 invoices to purchase orders2m 40s
  • Approve the new IBAN for Northwind4m 05s
  • Draft payment run for Friday0m 38s
  • Sync totals to the ledger0m 09s
  • Email suppliers about late invoices0m 00s

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add agent-status

Usage#

Pass the agent's status and each part picks its own colour, pulse and words from one table, so a mark, a dot and a badge for the same agent always agree.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Have a license? Unlock it here

Anatomy#

import {  AgentStatusMark,  AgentStatusDot,  AgentStatusBadge,  useAgentStatusLabel,} from "@/components/ui/agent-status"import { agentStatuses, agentStatusMeta, type AgentStatus } from "@/lib/agent"

Mark#

The mark for a step in a run. It stays a dot while the agent is live and becomes a check, a warning or a stop sign once it settles.

Running
Needs you
Idle
Done
Failed
Cancelled

Live status#

The dot and the glyph share one spot, so a change blurs one out as the other comes in. Step through a run to see it.

Idle

Dot#

The dot alone, for a tab, an avatar corner or a dense table. Only working and waiting move.

Running
Needs you
Idle
Done
Failed
Cancelled

Dot sizes#

Three sizes, from beside a line of small text to a header.

xs
sm
md

Badge#

The status in words. Only the two that need a person take colour: waiting and failed.

RunningNeeds youIdleDoneFailedCancelled

Badge options#

Every badge prop passes through: two sizes, a leading dot, a pulse, and your own words in place of the label.

Needs youNeeds youNeeds youRunningLedger offline

In an agent list#

The mascot carries who the agent is and the badge carries where it is. Leave the mascot's own status off here, so the state is said once.

  • Capture

    Reading 50 invoices from the inbox

    Running
  • Guard

    Approve the new IBAN for Northwind

    Needs you
  • Ledger

    Could not reach the ERP

    Failed
  • Digest

    Next run tomorrow at 08:00

    Idle

API reference#

Every part accepts className, merged last.

AgentStatusMark

A 14px mark for a step or a row. Live statuses show a dot; done, failed and cancelled swap it for a glyph in place. Hidden from screen readers, so pair it with a label. Forwards all native <span> props except children.

PropTypeDefaultDescription
status*"working" | "waiting" | "idle" | "done" | "failed" | "cancelled"-The status to show. A change crossfades between the dot and the glyph.
Data attributeDescription
data-slotagent-status-mark.
data-statusThe status passed.

AgentStatusDot

A Dot with its tone and pulse picked from the status. Forwards every Dot prop except tone and pulse.

PropTypeDefaultDescription
status*"working" | "waiting" | "idle" | "done" | "failed" | "cancelled"-Working pings in green, waiting blinks in amber, failed is red, the rest are neutral.
size"xs" | "sm" | "md""sm"6, 8 or 10px.
shape"round" | "square""round"Circle or soft square.
ringbooleanfalseA faint inner ring, for a dot over a photo or a coloured fill.
Data attributeDescription
data-statusThe status passed.

AgentStatusBadge

A Badge with the status in words. Forwards every Badge prop.

PropTypeDefaultDescription
status*"working" | "waiting" | "idle" | "done" | "failed" | "cancelled"-Picks the label and the colour: warning for waiting, destructive for failed, neutral for the rest.
variantBadgeProps["variant"]-Overrides the colour the status would pick.
size"sm" | "md""md"Badge height.
dotbooleanfalseA leading dot in the badge colour.
pulsebooleanfalsePulses the leading dot.
childrenReact.ReactNode-Replaces the status label, e.g. a reason for the failure.
Data attributeDescription
data-statusThe status passed.

useAgentStatusLabel

useAgentStatusLabel(status, override?) returns the status in words from the nearest LabelsProvider, so text beside a mark or a dot matches the badge. Returns override when you pass one.

agentStatusMeta

From @/lib/agent. For each status: tone, pulse, badge, loud (it needs a person) and settled (it has finished). Every part above reads it.

agentStatuses

From @/lib/agent. Every status in order, for filters and pickers. agentStatusOrder sorts the loud ones first.

FAQ#

The mark for steps in a run, the dot where space is tight, and the badge where the status needs to be read in words.