Components

useAgUiAgent

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

Example

Interactive, and the same on the components page. Try the keyboard below on it.

Installation

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

import { useAgUiAgent } from '@dgesteves/agent-ui-kit/ag-ui';
// Once per app (with Tailwind v4: @import '@dgesteves/agent-ui-kit/tailwind.css'; in your CSS)
import '@dgesteves/agent-ui-kit/styles.css';

npx shadcn@latest add @agent-ui-kit/ag-ui
npm i @ag-ui/client

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

The styles are once per app; Getting started has the Tailwind v4 and plain CSS options.

Usage

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

Generated from the types the package ships, so it matches the version you install.

useAgUiAgent

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

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

useAgUiAgent(agent: AgUiAgentLike): UseAgUiAgentResult

Parameter: AgUiAgentLike

messagesrequired: readonly AgUiMessage[]
subscriberequired: (subscriber: AgUiSubscriber) => { unsubscribe(): void; }
runAgentrequired: (parameters?: { resume?: AgUiResumeEntry[]; }) => Promise<unknown>
pendingInterrupts: readonly AgUiInterrupt[]
abortRun: () => void

Returns: UseAgUiAgentResult

messagesrequired: UIMessage[]
The conversation as AI SDK messages: pass each to AgentMessage.
statusrequired: ChatStatus
'error' | 'submitted' | 'streaming' | 'ready'
useChat-style status, for deriveAgentState and AgentStatus.
errorrequired: AgUiRunState['error']
usagerequired: RunUsage
Token usage summed over the runs seen, for RunMeter.
steprequired: string
The step in progress, e.g. a LangGraph node.
interruptsrequired: AgUiInterrupt[]
Open interrupts. Those bound to a tool call show as approval cards; answer the rest with resolve.
respondrequired: (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.
resolverequired: (entry: AgUiResumeEntry) => Promise<void>
Answer any interrupt with your own payload (match its responseSchema).
stoprequired: () => void
Abort the run in progress.

AgUiInterrupt

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

idrequired: string
reasonrequired: string
message: string
toolCallId: string
responseSchema: Record<string, unknown>

AgUiApprovalResponse

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

idrequired: string
approvedrequired: boolean
reason: string

AgUiResumeEntry

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

interruptIdrequired: string
statusrequired: '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.