Files

T

qzl ed86bfe9ae docs: 更新 Agent 协议文档与部署配置

- 更新 Agent API 端点文档
- 更新 SSE 事件与输入输出文档
- 新增 deploy/.env.prod.example 配置模板

2026-03-16 16:11:40 +08:00

2.6 KiB

Raw Blame History

前后端数据流通指南（Agent Chat）

本文档仅描述当前后端实现的 runs/events/history 数据流，不定义视觉细节。

1) 总体流程

客户端 POST /api/v1/agent/runs 提交 RunAgentInput
后端返回 202 + taskId/threadId/runId/created
客户端 GET /api/v1/agent/runs/{threadId}/events 订阅 SSE
后端输出 AG-UI 事件（如 RUN_STARTED、TOOL_CALL_RESULT、TEXT_MESSAGE_END）
客户端按需 GET /api/v1/agent/history 拉取历史快照（按天）

2) `/runs` 请求与响应

请求

Body: RunAgentInput
user message 可为纯文本，也可为文本+binary（图片 URL）

响应

{
  "taskId": "...",
  "threadId": "...",
  "runId": "...",
  "created": true
}

created 语义：是否在本次请求中创建了新会话。

3) `/runs/{threadId}/events` 事件流

SSE 形式

id: <stream-id>
event: <EVENT_TYPE>
data: <json>

事件类型

以 docs/protocols/agent/sse-events.md 为准。当前重点是：

运行生命周期：RUN_STARTED / RUN_FINISHED / RUN_ERROR
阶段：STEP_STARTED / STEP_FINISHED
工具：TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END / TOOL_CALL_RESULT
文本完成：TEXT_MESSAGE_END

文本流策略

当前后端不提供 token 级 TEXT_MESSAGE_CONTENT 增量流作为主路径；而是在 worker 完成后通过 TEXT_MESSAGE_END 一次性携带完整语义结果。

4) `/history` 快照

GET /api/v1/agent/history 返回 HistorySnapshotResponse：

{
  "scope": "history_day",
  "threadId": "...",
  "day": "2026-03-16",
  "hasMore": false,
  "messages": []
}

说明：

这是普通 JSON 响应，不是 SSE 事件包装。
messages 已按 seq 升序组织。
before 采用 YYYY-MM-DD，语义是向更早日期翻页。

5) events 与 history 的一致性机制

5.1 语义来源一致

两条链路都来自同一运行时输出（worker/tool output）及其持久化元数据。

5.2 UI 编译器一致

两条链路都使用后端 ui_compiler.compile(...) 将 ui_hints 编译为可渲染结构：

events：在 runtime 发送事件前编译，字段名为 ui_schema
history：在历史转换时编译，字段名为 ui_schema

5.3 当前命名差异（实现现状）

两条链路字段命名已统一：

events: ui_schema（snake_case）
history: ui_schema（snake_case）

6) 推荐消费顺序（面向客户端重构）

先以 /history 获取首屏快照
再接入 /events 处理后续增量
以 runId + messageId/toolCallId 做去重与合并
统一消费 ui_schema

2.6 KiB Raw Blame History Unescape Escape