Overview
AgentStat is a React component that shows what your LLM agents are doing right now: each agent's token rate, progress and status over time, a health score, and opt-in detection of stalls, runaway output and status thrashing.
It draws on one canvas, weighs about 17 KB min+gzip, and depends on nothing but React.
What you see
- A line per agent for token rate, progress, or both on two axes. By default (
metric="auto") the chart plots progress once every visible agent reports it, and token rate otherwise. - A live tip at the right edge for agents that are reporting. An agent that stops reporting keeps its line where its data ends.
- A legend to show or hide agents. It stays on one row; agents that don't fit move into a "+N" menu. Hidden agents are still monitored.
- A panel with each agent's rate, health and status. On charts under 560 × 340 px it steps aside so the data stays readable.
- Inspection of any sample by hover or keyboard: its age, rate, progress and the status it had at that moment.
- Anomaly markers (opt-in): ▲ for a warning, ◆ for critical, with the agent's name and the numbers that triggered it.
Without windowSeconds, the chart shows the last 10 seconds of data. Set it (for example 60 or 900) for a longer wall-clock window; long windows are downsampled to the canvas width without losing peaks.
What it doesn't make up
- Progress is unknown until an agent reports it. An agent that never sends progress gets no 0% line; it reads "–" when inspected.
- Hallucination risk comes only from your signal. Telemetry can't detect hallucinations, so
hallucinationRiskisnullunless you pass a confidence score or report thehallucinatingstatus. - No invented history. An agent starts from the state you declare, not from fabricated samples, and nothing is extrapolated past its last one.
- Anomaly detection is measured. The detectors are scored against labelled scenarios, including sets written by reviewers who never saw the tuning. See how it's measured.
How data gets in
- Event streams: forward what your agent emits (
start,tokens, tool calls,finish). AgentStat derives the token rate, time to first token and status. This is the recommended path. - Integrations: adapters that produce those events for the Vercel AI SDK, LangChain and LangGraph, OpenTelemetry and AG-UI, plus Server-Sent Events from a server.
- Samples: if you already compute rates, report them with
updateAgent. See samples.
What's in the package
| Entry | Contents |
|---|---|
@dan-build/agentstat | AgentStat, event streams, useAgentTelemetry and four small components, detectAnomalies. Client-only. |
/ai-sdk | Vercel AI SDK v5–v7 adapter. |
/langchain | LangChain.js and LangGraph.js adapter. |
/otel | OpenTelemetry span processor for GenAI spans. |
/ag-ui | AG-UI protocol adapter. |
/sse | Serve a stream over Server-Sent Events, and connect to it from the browser. |
The other entries are paths under the package, for example @dan-build/agentstat/sse. The adapter entries have no dependencies (not even on the framework they adapt), weigh 0.5–2.5 KB each, and run on the server as well as in the browser.
Built in
- Themes: light, dark, or
system. Text clears WCAG AA contrast, and the default palette stays at least 3:1 against both backgrounds. - Keyboard: ← → step through samples, ↑ ↓ switch agent, Space pauses.
- Screen readers: the chart describes every visible agent, and anomalies are announced as they start and end.
- Not color alone: status and severity always come with text, an icon or a marker shape.
- Reduced motion: with
prefers-reduced-motion, values snap instead of easing.