AG-UI Protocol

The AG-UI adapter translates Awaken’s AgentEvent stream into the AG-UI (CopilotKit) event format. This enables CopilotKit frontends to drive Awaken agents with no custom adapter code.

Endpoint

POST /v1/ag-ui/run

Request Body

{
  "threadId": "optional-thread-id",
  "agentId": "optional-agent-id",
  "messages": [{ "role": "user", "content": "Hello" }],
  "context": {}
}

Field	Type	Required	Description
`messages`	`AgUiMessage[]`	yes	Chat messages with `role` and `content` strings.
`threadId`	`string`	no	Existing thread. Omit to create a new thread.
`agentId`	`string`	no	Target agent. Uses the default agent when omitted.
`context`	`object`	no	CopilotKit context forwarding (reserved).

Response

SSE stream (text/event-stream). Each frame is a JSON-encoded AG-UI Event.

Auxiliary Routes

Route	Method	Description
`/v1/ag-ui/run`	POST	Start a run and stream AG-UI events.
`/v1/ag-ui/threads/:thread_id/runs`	POST	Start a thread-scoped run.
`/v1/ag-ui/agents/:agent_id/runs`	POST	Start an agent-scoped run.
`/v1/ag-ui/threads/:thread_id/interrupt`	POST	Interrupt the thread and supersede queued work.
`/v1/ag-ui/threads/:thread_id/replay`	GET	Replay durable protocol frames for a thread.
`/v1/ag-ui/threads/:id/messages`	GET	Retrieve thread message history.

Replay requires a configured ProtocolReplayLog. It accepts ?cursor= or Last-Event-ID, plus ?limit= (default 100, max 500), and returns SSE frames with the protocol replay cursor as the SSE id. Missing replay storage returns 503; malformed cursors return 400; expired cursors return 410 Gone.

Event Mapping

The AgUiEncoder is a stateful transcoder that manages text message and step lifecycles.

AgentEvent	AG-UI Event(s)
`RunStart`	`RUN_STARTED`
`TextDelta`	`TEXT_MESSAGE_START` (if not open) + `TEXT_MESSAGE_CONTENT`
`ReasoningDelta`	`REASONING_MESSAGE_START` (if not open) + `REASONING_MESSAGE_CONTENT`
`ToolCallStart`	Close text/reasoning, `STEP_STARTED`, `TOOL_CALL_START`
`ToolCallDelta`	`TOOL_CALL_ARGS`
`ToolCallDone`	`TOOL_CALL_END`, `STEP_FINISHED`
`StateSnapshot`	`STATE_SNAPSHOT`
`StateDelta`	`STATE_DELTA`
`RunFinish` (success)	Close text/reasoning, `RUN_FINISHED`
`RunFinish` (error)	Close text/reasoning, `RUN_ERROR`

AG-UI Event Types

Events use an uppercase type discriminant:

RUN_STARTED / RUN_FINISHED / RUN_ERROR — run lifecycle
TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END — assistant text
REASONING_MESSAGE_START / REASONING_MESSAGE_CONTENT / REASONING_MESSAGE_END — reasoning trace
STEP_STARTED / STEP_FINISHED — step boundaries (wrapping tool calls)
TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END — tool call lifecycle
STATE_SNAPSHOT / STATE_DELTA — shared state synchronization
MESSAGES_SNAPSHOT — full thread message history

All events carry a BaseEvent with optional timestamp and rawEvent fields.

Roles

AG-UI messages use lowercase role strings: system, user, assistant, tool.

Text Message Lifecycle

First TextDelta emits TEXT_MESSAGE_START followed by TEXT_MESSAGE_CONTENT.
Subsequent deltas emit only TEXT_MESSAGE_CONTENT.
A ToolCallStart or RunFinish closes the open message with TEXT_MESSAGE_END.

Reasoning messages follow the same pattern with REASONING_MESSAGE_* events.

Events — full AgentEvent enum
Integrate CopilotKit (AG-UI) — frontend integration guide