Agent Presence

Usage

"use client";

import { AgentPresence } from "@/components/ui/agent-presence";

export function AgentBar({ run }: { run: AgentRun }) {
  return (
    <AgentPresence
      state={run.state}
      label={run.tool ? `Searching ${run.tool}` : undefined}
      form="line"
      size="sm"
      onCancel={run.abort}
    />
  );
}

Features

• Motion means the machine is busy. Stillness means it's your turn. Machine states animate; hand-off states stop dead and sit brighter. It's learnable in about three interactions, after which nobody reads the label to know whether they're needed.
• Rotation speed is the state — 24s per revolution when queued, 4s when working. The same object communicates urgency through tempo, which is what lets states morph into each other rather than cut between separate animations.
• The vocabulary is taken, not invented — every state maps to a real protocol event. See the mapping below.
• Reduced motion loses nothing. Each state holds a visually distinct static configuration, so the grammar still works with every keyframe disabled.

Variants

The machine's turn — these move

Your turn — these hold perfectly still

The inversion: every other library pulses the thing that wants attention. Here the thing that wants attention is the only thing not moving.

Terminal states

Figure and mark

The agent, drawn. Each state takes an Agent Figure pose, and the poses for your turn hold still. mark is the head alone, for inline use.

Orb (deprecated)

form="orb" still renders, so existing screens keep working, but it will be removed in a later drop. A glowing sphere reads as a mind rather than as work. For hero surfaces, empty states and agent panels, use Agent Figure, which draws the agent and shows what it's doing.

Line

For status bars, table rows, and anywhere the agent is a footnote rather than the subject.

Mapping from your agent stack

The state vocabulary is deliberately protocol-shaped, so adopting it is a mapping rather than a rewrite. The component itself takes no AI dependency — you own the stream, you map its events to a state.

A minimal AI SDK adapter is about this long:

function toAgentState(status: string, parts: UIMessagePart[]): AgentState {
  if (status === "submitted") return "queued";
  const last = parts.at(-1);
  if (last?.type === "reasoning") return "thinking";
  if (last?.type?.startsWith("tool-")) return "working";
  if (status === "streaming") return "streaming";
  if (status === "error") return "failed";
  return "done";
}

Examples

Naming the tool matters — working alone is a spinner with extra steps:

<AgentPresence state="working" label={`Reading ${file.name}`} onCancel={run.abort} />

Indicator only, where the surrounding UI already says what's happening. The label is still announced to screen readers:

<AgentPresence state="thinking" form="line" size="sm" hideLabel />

Props

Accessibility

• The label is the real signal, in an aria-live="polite" region. The indicator is aria-hidden and supplementary — never the only way state is communicated.
• Hand-off states are distinguished by weight and colour token as well as stillness, so the grammar doesn't depend on perceiving motion.
• Stop is a real keyboard-reachable <button> with its hit area extended to ~44px while staying visually compact.
• Under prefers-reduced-motion every keyframe is disabled and each state still holds a distinct static configuration — the same information without the movement.

When not to use

The reasoning text is Reasoning Stream. Per-artifact generation progress is Generation Placeholder. The post-result action strip is AI Action Toolbar. This component says what the agent is doing — not what it produced, or what you can do about it.