跳转到内容
Awaken

AG-UI 协议

AG-UI 适配层会把 Awaken 的 AgentEvent 流转换成 AG-UI / CopilotKit 事件格式，使 CopilotKit 前端可以直接驱动 Awaken agent。

入口

Section titled “入口”
POST /v1/ag-ui/run

请求体

Section titled “请求体”
{
  "threadId": "optional-thread-id",
  "agentId": "optional-agent-id",
  "messages": [{ "role": "user", "content": "Hello" }],
  "context": {}
}
字段类型必填说明
messagesAgUiMessage[]是聊天消息，使用 role 和 content
threadIdstring否继续已有 thread
agentIdstring否指定目标 agent
contextobject否前端上下文透传

响应

Section titled “响应”

SSE 流（text/event-stream），每个 frame 是一个 JSON 编码的 AG-UI Event。

辅助路由

Section titled “辅助路由”
路由方法说明
/v1/ag-ui/runPOST启动 run 并流式返回 AG-UI events
/v1/ag-ui/threads/:thread_id/runsPOST在指定 thread 上启动 run
/v1/ag-ui/agents/:agent_id/runsPOST在指定 agent 上启动 run
/v1/ag-ui/threads/:thread_id/interruptPOST中断指定 thread
/v1/ag-ui/threads/:thread_id/replayGET回放指定 thread 的持久协议 frame
/v1/ag-ui/threads/:id/messagesGET读取 thread 消息历史

Replay 要求配置 ProtocolReplayLog。请求可带 ?cursor= 或 Last-Event-ID，以及 ?limit=（默认 100，最大 500）；响应是 SSE， 并使用 protocol replay cursor 作为 SSE id。未配置 replay 存储返回 503， 非法 cursor 返回 400，过期 cursor 返回 410 Gone。

事件映射

Section titled “事件映射”
AgentEventAG-UI Event
RunStartRUN_STARTED
TextDeltaTEXT_MESSAGE_START + TEXT_MESSAGE_CONTENT
ReasoningDeltaREASONING_MESSAGE_START + REASONING_MESSAGE_CONTENT
ToolCallStart关闭当前 text/reasoning，然后发 STEP_STARTED、TOOL_CALL_START
ToolCallDeltaTOOL_CALL_ARGS
ToolCallDoneTOOL_CALL_END、STEP_FINISHED
StateSnapshotSTATE_SNAPSHOT
StateDeltaSTATE_DELTA
RunFinishRUN_FINISHED 或 RUN_ERROR

AG-UI 事件类型

Section titled “AG-UI 事件类型”
  • RUN_STARTED / RUN_FINISHED / RUN_ERROR
  • TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END
  • REASONING_MESSAGE_START / REASONING_MESSAGE_CONTENT / REASONING_MESSAGE_END
  • STEP_STARTED / STEP_FINISHED
  • TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END
  • STATE_SNAPSHOT / STATE_DELTA
  • MESSAGES_SNAPSHOT

角色

Section titled “角色”

AG-UI 消息角色使用小写字符串：system、user、assistant、tool。

文本消息生命周期

Section titled “文本消息生命周期”
  1. 第一个 TextDelta 会发 TEXT_MESSAGE_START 和 TEXT_MESSAGE_CONTENT。
  2. 后续 delta 只追加 TEXT_MESSAGE_CONTENT。
  3. 遇到 ToolCallStart 或 RunFinish 时，当前消息会以 TEXT_MESSAGE_END 关闭。

reasoning 消息采用同样模式。

相关

Section titled “相关”