# AgentTrace

AgentTrace is a controlled disclosure for observable agent operations and their current result.

Use AgentTrace for observable searches, tools, files, and checks. Never expose private reasoning. Keep the plain collapsed summary useful.

<h2 id="purpose">Purpose</h2>

Use AgentTrace for searches, tool calls, files, checks, and other observable work. Do not expose hidden reasoning, private chain-of-thought, or unsupported explanations of model behavior.

<h2 id="anatomy">Summary and items</h2>

Keep `summary` useful while the trace is closed. It should report the current result, count, duration, or next blocked step. Do not require expansion to understand whether work succeeded.

Give the trace and every item a stable ID. Supply visible `statusLabel` text for each state. Descriptions can report an operation and its evidence, but must not imitate internal reasoning.

Control disclosure through `open` and `onOpenChange`. Preserve failed and blocked items until the user retries or starts a new run.

<h2 id="announcements">Announcements</h2>

Pass a non-empty `announcement` for one completed status transition. AgentTrace keeps an empty live region mounted when no message is present. An empty message announces nothing. Do not announce each streamed token or repeat the same status from a parent live region.

<h2 id="tokens">Tokens and style hooks</h2>

AgentTrace uses status, text, mono type, border, spacing, and motion tokens. Its detail disclosure uses the plain core Collapsible presentation. The trace rail appears only inside expanded details.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `announcement` | `string` | prop | No | `undefined` | Message for the owned live region. An empty value keeps the region mounted without announcing. |
| `emptyMessage` | `string` | prop | No | `undefined` | No additional description. |
| `items` | `readonly AgentTraceItem[]` | prop | Yes | - | No additional description. |
| `onOpenChange` | `(open: boolean) => void` | callback | No | `undefined` | No additional description. |
| `open` | `boolean` | binding | No | `false` | No additional description. |
| `status` | `AgentStatus` | prop | Yes | - | No additional description. |
| `statusLabel` | `string` | prop | Yes | - | No additional description. |
| `summary` | `string` | prop | Yes | - | No additional description. |
| `title` | `string` | prop | Yes | - | No additional description. |
| `traceId` | `string` | prop | Yes | - | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.
- [ApprovalRequest](/docs/components/approval-request): Explicit approve-or-reject workflow with consequences, optional editing, and separate decision submission.