AG-UI
AG-UI is a standard event protocol for agent chat UIs. The engine speaks it, so frontends like CopilotKit and assistant-ui connect to an agent directly.
Endpoint
Each agent is served at an AG-UI run endpoint:
POST /api/client/ag-ui/agents/{agent_id}/runIt takes a RunAgentInput and returns the AG-UI event stream over SSE. A
companion .../connect replays the conversation as a snapshot for a client that
is catching up.
Input
RunAgentInput carries the turn.
| Field | Meaning |
|---|---|
threadId | The session. |
runId | The turn id. |
messages | The client's conversation view. |
resume | Interrupt answers. |
tools, context, state, forwardedProps | Contributed by the frontend. |
resume entries are applied first, then a non-empty messages view submits a
turn. Sending both in one input is the steer-away move: the resume clears a
pending interrupt while the view branches the conversation elsewhere.
Events
The stream is AG-UI events: RUN_STARTED and RUN_FINISHED around the turn,
TEXT_MESSAGE_* for assistant text, REASONING_* for thinking, TOOL_CALL_*
for tool calls and results, and MESSAGES_SNAPSHOT for the active branch.
RUN_FINISHED carries an interrupt outcome when the agent paused.
Frontend tools and context
tools, context, and state from RunAgentInput become the decision's
client context. Frontend tools
are declared handler: "client" and run in the browser; a call to one ends the
run so the browser can execute it, then the client resubmits with the result.
Examples
node-hono-copilotkit and node-hono-assistant-ui point the frontend at the
same endpoint:
${url}/api/client/ag-ui/agents/${agentId}/runEach declares a worker tool and a browser tool, showing both sides in one UI.
Next
- Conversations: the thread and tree behind a run.
- Client-side tools: the browser tools AG-UI carries.
- Interrupts: the resume path a run drives.