# useAgUiAgent

> An AG-UI agent’s run as AI SDK messages, status, usage and approvals, for the same components.

Source: https://agent-ui-kit-demo.vercel.app/docs/components/use-ag-ui-agent

## Installation

From npm:

```bash
npm i @dgesteves/agent-ui-kit ai @ag-ui/client
```

```tsx
import { useAgUiAgent } from '@dgesteves/agent-ui-kit/ag-ui';
import '@dgesteves/agent-ui-kit/styles.css'; // once per app, or @import '@dgesteves/agent-ui-kit/tailwind.css' with Tailwind v4
```

Or as source, with the shadcn CLI:

```bash
npx shadcn@latest add @agent-ui-kit/ag-ui
```

```tsx
import { useAgUiAgent } from '@/components/agent-ui/use-ag-ui-agent';
```

## Usage

```tsx
const agent = new HttpAgent({ url: '/api/agent' }); // once, outside the component

function AgentRun() {
  const { messages, status, usage, step, respond } = useAgUiAgent(agent);
  const last = messages.findLast((m) => m.role === 'assistant');
  const { state, detail } = deriveAgentState({ status, message: last });
  return (
    <>
      <AgentStatus state={state} detail={step ?? detail} />
      {last && <AgentMessage message={last} onToolApproval={respond} />}
      <RunMeter usage={usage} />
    </>
  );
}
```

## API reference

### useAgUiAgent

Render an AG-UI agent with these components: its messages as AI SDK parts, run status, usage,
and tool-call interrupts as approvals.

```tsx
const agent = useMemo(() => new HttpAgent({ url: '/api/agent' }), []);
const { messages, status, respond } = useAgUiAgent(agent);
```

```ts
useAgUiAgent(agent: AgUiAgentLike): UseAgUiAgentResult
```

Parameter, `AgUiAgentLike`:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `messages` (required) | `readonly AgUiMessage[]` |  |  |
| `subscribe` (required) | `(subscriber: AgUiSubscriber) => { unsubscribe(): void; }` |  |  |
| `runAgent` (required) | `(parameters?: { resume?: AgUiResumeEntry[]; }) => Promise<unknown>` |  |  |
| `pendingInterrupts` | `readonly AgUiInterrupt[]` |  |  |
| `abortRun` | `() => void` |  |  |

Returns `UseAgUiAgentResult`:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `messages` (required) | `UIMessage[]` |  | The conversation as AI SDK messages: pass each to `AgentMessage`. |
| `status` (required) | `ChatStatus` ('streaming' \| 'error' \| 'submitted' \| 'ready') |  | `useChat`-style status, for `deriveAgentState` and `AgentStatus`. |
| `error` (required) | `AgUiRunState['error']` |  |  |
| `usage` (required) | `RunUsage` |  | Token usage summed over the runs seen, for `RunMeter`. |
| `step` (required) | `string` |  | The step in progress, e.g. a LangGraph node. |
| `interrupts` (required) | `AgUiInterrupt[]` |  | Open interrupts. Those bound to a tool call show as approval cards; answer the rest with `resolve`. |
| `respond` (required) | `(response: AgUiApprovalResponse) => Promise<void>` |  | Answer a tool-call interrupt. Pass it as `AgentMessage`'s `onToolApproval`. The agent resumes once every open interrupt has an answer, since AG-UI resumes them all in one run. |
| `resolve` (required) | `(entry: AgUiResumeEntry) => Promise<void>` |  | Answer any interrupt with your own payload (match its `responseSchema`). |
| `stop` (required) | `() => void` |  | Abort the run in progress. |

### AgUiInterrupt

A pause for human input (AG-UI `Interrupt`). `toolCallId` binds it to a tool call to approve.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `reason` (required) | `string` |  |  |
| `message` | `string` |  |  |
| `toolCallId` | `string` |  |  |
| `responseSchema` | `Record<string, unknown>` |  |  |

### AgUiApprovalResponse

A tool approval, as `ToolApprovalCard` and `AgentMessage`'s `onToolApproval` give it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `approved` (required) | `boolean` |  |  |
| `reason` | `string` |  |  |

### AgUiResumeEntry

An answer to an interrupt, sent in `RunAgentInput.resume` (AG-UI `ResumeEntry`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `interruptId` (required) | `string` |  |  |
| `status` (required) | `'resolved' \| 'cancelled'` |  |  |
| `payload` | `unknown` |  |  |

## Accessibility

- A hook with no markup of its own: the components it feeds carry the behavior on their pages.
- A tool-call interrupt becomes an approval card with the same keyboard and announcements as an AI SDK approval.