# useAgUi

Wires an AG-UI agent to Candor: messages for <Thread>/<Message>, props for <Composer>, and the interrupts waiting on a person. The same shape as useClaudeAgent and useCandorChat, so screens work with any of them.

const { messages, composer, approvals, respond } = useAgUi({ url: "/api/agent", agent }) <Thread footer={<Composer {...composer} />}>{messages.map((m) => <Message key={m.id} message={m} />)}</Thread>

A run that ends on an interrupt shows it in `approvals`. `respond` records the answer, and once every open interrupt has one, starts the next run with `resume`: approved → `{ status: "resolved", payload: { approved: true } }`, denied → `{ status: "cancelled", payload: { approved: false, reason } }`. Mentions are sent as structured `forwardedProps.references`, not pasted into the text.

- Registry name: `use-ag-ui` (`@candor/use-ag-ui`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/use-ag-ui

## Install

```bash
npx candor-ui add use-ag-ui
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/use-ag-ui`.
It brings in: ag-ui, chat, composer.
npm packages: @ag-ui/client@^1.0.3.

## Functions

### useAgUi

```ts
useAgUi(options: UseAgUiOptions)
```

Wires an AG-UI agent to Candor: messages for <Thread>/<Message>, props for <Composer>, and the interrupts waiting on a person. The same shape as useClaudeAgent and useCandorChat, so screens work with any of them.

const { messages, composer, approvals, respond } = useAgUi({ url: "/api/agent", agent }) <Thread footer={<Composer {...composer} />}>{messages.map((m) => <Message key={m.id} message={m} />)}</Thread>

A run that ends on an interrupt shows it in `approvals`. `respond` records the answer, and once every open interrupt has one, starts the next run with `resume`: approved → `{ status: "resolved", payload: { approved: true } }`, denied → `{ status: "cancelled", payload: { approved: false, reason } }`. Mentions are sent as structured `forwardedProps.references`, not pasted into the text.

## Types

### UseAgUiOptions

```ts
Omit<FromAgUiOptions, "running" | "now"> & { /** Your AG-UI endpoint (LangGraph, Mastra, CrewAI, Google ADK, Pydantic AI…). It receives a RunAgentInput and streams events back. */ url: string headers?: Record<string, string> | undefined /** Replaces the global fetch, e.g. to add auth or to play a script in tests and demos. */ fetch?: typeof fetch | undefined /** Continue an existing thread instead
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.