---
title: "Agent UX Kit"
description: "Composer, chat history, model picker, context chips, approvals, run recovery, progress, and notifications."
---
# Agent UX Kit
The Agent UX Kit packages the surfaces that make an app's agent feel trustworthy
and inspectable: composer, model picker, context chips, approvals, progress,
run recovery, and the runs tray.
Ask the agent
Draft the Q3 summary email.
Here is a draft. I will need approval before sending.
Message the agent...
Q3 ForecastGPT-5
"
}
/>
## Pieces {#pieces}
| Piece | Purpose |
| --------------------------------- | ---------------------------------------------------------------------------------- |
| `` / `` | Complete agent surfaces for sidebars, pages, and dialogs. |
| `` | Standard rich composer with attachments, references, pasted text, and voice hooks. |
| Model picker | Standard model/provider choice in agent settings or composer chrome. |
| Context chips | Visible route, resource, file, and selection context sent to the agent. |
| Human approvals | Confirmation gates for sensitive or irreversible operations. |
| `` | User-visible background run progress and recovery. |
| Run recovery | Hydrates dropped/stale foreground and background runs back into the UI. |
## Chat History {#chat-history}
@agent-native/toolkit/chat-history exports ChatHistoryList, ChatHistoryRail, and useChatHistoryRailController. The list supports selection, search, pinning, rename/delete actions, loading/error/empty states, and custom row actions. The rail adds a New chat action and a show more/less control.
Launch planThe app loads and saves this conversation."
}
/>
The app supplies chat items, the active id, labels, and callbacks. These Toolkit components do not query, authorize, persist, or route conversations. Keep those responsibilities in the app or framework adapter; use the lower-level controller when the app needs a different rail view.
## Wiring The Header {#wiring}
`PromptComposer` and `RunsTray` are the two pieces most apps wire by hand
outside the default sidebar: a standalone composer that posts into agent chat,
plus a header trigger showing live run progress.
Toolkit owns the portable Tiptap and composer UI implementation, while
`@agent-native/toolkit/app/chat/composer` is the framework-wired wrapper used by
Agent-Native apps. Import `@agent-native/toolkit/composer` directly only for
portable bare UI, and wrap it in `ComposerRuntimeAdaptersProvider` with the
framework service adapters it needs.
```tsx
import {
AgentToggleButton,
sendToAgentChat,
} from "@agent-native/core/client/agent-chat";
import { PromptComposer } from "@agent-native/toolkit/app/chat/composer";
import { RunsTray } from "@agent-native/toolkit/app/progress";
export function AgentDock() {
return (
);
}
```
`RunsTray` polls `/_agent-native/runs` and hides itself when idle, so it is safe
to mount unconditionally next to `AgentToggleButton`. Use the full
`` instead of a bare `` when you want the whole
chat surface, not just the input — see [Drop-in Agent](/docs/drop-in-agent).
## UX Standard {#ux-standard}
- Show what context the agent will use before the user sends.
- Model and key setup should link to the Settings Kit.
- Long-running work belongs in the runs tray, not as a frozen composer spinner.
- Approval prompts should name the action, data, and risk before proceeding.
- Recovered runs should be visible and explain what happened.
## What's next
- [**Using Your Agent**](/docs/using-your-agent) — the end-user model/composer
experience this kit implements.
- [**Human Approval**](/docs/actions-access-control#needs-approval) — the approval-gate contract
behind approval prompts.
- [**Progress**](/docs/progress) — the run data `` polls and renders.
- [**Native Chat UI**](/docs/native-chat-ui) — build a custom chat surface on
the same runtime as ``.