Chat · 流式对话 API

索引：backend/real-agent-web/src/main/java/com/ai/agent/real/web/controller/agent/VoloAIAgentController.java

VOLO AI 主对话通道，采用单端点 POST SSE 协议，对齐 OpenAI / Anthropic / Vercel AI SDK 行业主流形态。

端点全集

Method	Path	用途
`POST`	`/api/agent/chat/volo-ai/{sessionId}/intent`	主意图入口（流式 SSE，唯一对话通道）
`POST`	`/api/agent/chat/volo-ai/{sessionId}/stop`	停止生成
`POST`	`/api/agent/chat/volo-ai/resume`	恢复执行（Human-in-the-loop）
`POST`	`/api/agent/chat/volo-ai/{sessionId}/append-message`	流中追加上下文（G1 协议）
`POST`	`/api/agent/chat/volo-ai/interaction-response/{interactionId}`	交互响应（规范路径）
`POST`	`/api/agent/chat/volo-ai/interaction_response`	交互响应（旧路径兼容）
`POST`	`/api/agent/chat/volo-ai/tool-approval/{toolCallId}`	工具审批
`POST`	`/api/agent/chat/volo-ai/tool-result/{toolCallId}`	工具结果回执（协议占位）
`GET`	`/api/agent/chat/volo-ai/{sessionId}/messages`	获取会话历史消息
`GET`	`/api/agent/chat/volo-ai/commands`	列出可见命令清单

1 · 提交意图（主对话入口）

http

POST /api/agent/chat/volo-ai/{sessionId}/intent
Authorization: Bearer $VOLO_API_KEY
Content-Type: application/json
Accept: text/event-stream

请求体 · `ChatRequest`

json

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "userMessage": "你好",
  "parentTurnId": null,
  "executionMode": "AUTO",
  "attachments": []
}

字段	类型	必填	说明
`sessionId`	UUID	否	路径已带；若 body 不带则从路径回填
`userMessage`	string	是	用户文本
`parentTurnId`	UUID \| null	否	接续的父 turn ID，首条为 null
`executionMode`	enum	否	`FAST` / `MAX` / `AUTO`（默认 AUTO）
`attachments`	array	否	多模态附件（图片/文档/视频）

ExecutionMode 三档

档位	行为	适用
`FAST`	单轮策略，无工具循环	简单问答、快速响应
`MAX`	多轮策略 + 工具自循环 + 思考链	复杂任务、研究、代码生成
`AUTO`	`AutoClassifier` 根据用户意图自动路由	默认推荐

[TODO: REACT / THOUGHT / SIMPLE / THINKING 等中间档位已合并为三档，向后兼容映射在 ExecutionMode.from() 中处理]

响应 · SSE 流

返回 text/event-stream，每条事件按 SSE 协议序列化。

2 · 停止生成

用户点击「停止生成」按钮时调用。

http

POST /api/agent/chat/volo-ai/{sessionId}/stop

json

{
  "code": 200,
  "message": "success.stopped"
}

若无运行中 turn 返回 404 agent.error.noRunningTask。

3 · 流中追加上下文（G1 协议）

在 streaming 期间向运行中的 turn 追加内容。不打断当前流，下一轮 prompt 自动带上追加内容。

http

POST /api/agent/chat/volo-ai/{sessionId}/append-message
Content-Type: application/json

{
  "appendedText": "顺便再帮我加一个夜间模式"
}

仅 MAX 多轮策略生效

FAST 单轮策略追加无意义，返回 409。

4 · 恢复执行（Human-in-the-loop）

当 Agent 触发 INTERACTION 事件（如缺信息、需用户确认）时，调用此端点带入用户响应：

http

POST /api/agent/chat/volo-ai/resume?turnId={turnId}
Content-Type: application/json
Accept: text/event-stream

{
  "turnId": "uuid-...",
  "response": "选择 B 方案"
}

返回 SSE 流，从挂起点续跑。

5 · 工具审批

Agent 调用敏感工具时，前端弹审批弹窗，用户操作后回传：

http

POST /api/agent/chat/volo-ai/tool-approval/{toolCallId}
Content-Type: application/json

{
  "approved": true,
  "reason": "用户已确认",
  "turnId": "uuid-..."
}

json

{
  "code": 200,
  "data": {
    "accepted": true,
    "toolCallId": "...",
    "timestamp": "2026-05-14T10:30:00+08:00"
  }
}

6 · 获取历史消息

http

GET /api/agent/chat/volo-ai/{sessionId}/messages
GET /api/agent/chat/volo-ai/{sessionId}/messages?since=2026-05-13T00:00:00+08:00

返回 List<ChatMessageVO>，按时间升序。

7 · 列出可用命令

http

GET /api/agent/chat/volo-ai/commands?triggerChar=%2F&query=h-

参数	说明
`triggerChar`	触发符（`/` 或 `#` 或 `@`）
`query`	命令名前缀过滤

返回 List<ChatCommandCompletionItem>，用于前端 autocomplete 下拉。

SSE 协议

事件帧结构

event: ASSISTANT_DELTA
data: {"type":"ASSISTANT_DELTA","traceInfo":{...},"content":"hello"}

event: COMPLETE
data: {"type":"COMPLETE","traceInfo":{...}}

每帧含两行：

event: SSE 事件名（= JSON 中的 type 字段）
data: 完整 AgentExecutionEvent JSON

EventType 枚举

后端 AgentExecutionEvent.java 定义 34+ EventType，按家族归类：

协议事件家族

EventType	含义
`PROGRESS`	Agent 思考进度提示
`ASSISTANT_DELTA`	LLM 流式 token
`ASSISTANT_END`	LLM 输出结束
`ERROR`	错误事件
`COMPLETE`	整个 turn 完成

Tool 事件家族

EventType	含义
`TOOL_START`	工具调用开始
`TOOL_DELTA`	工具流式输出（如终端流）
`TOOL_END`	工具调用结束

UI 事件家族（独立顶级渲染）

EventType	含义
`RENDER_UI`	渲染富 UI 组件（27 种 UIComponentType）
`INTERACTION`	需用户响应的交互事件
`WEB_SEARCH`	联网搜索结果
`WEB_FETCH`	网页抓取结果

Command 事件家族

EventType	含义
`COMMAND_START`	命令系统启动（`/skill` `#cmd` `@file`）
`COMMAND_RESULT`	命令结果
`COMMAND_END`	命令结束

SubAgent 事件家族（v2 登神战役）

EventType	含义
`SUBAGENT_DISPATCH`	调度子 Agent
`SUBAGENT_NOTIFY`	子 Agent 进度通知
`SUBAGENT_COMPLETE`	子 Agent 完成

[TODO: 完整 34 种 EventType 表见 docs/specs/VOLO_AI_PROTOCOL_SPEC.md，将补齐 cross-link]

Traceable 三件套

每个事件携带：

json

{
  "traceInfo": {
    "sessionId": "uuid-...",
    "turnId": "uuid-...",
    "parentTurnId": "uuid-..."
  }
}

前端按 turnId 挂载到 turnTree，按 parentTurnId 构建父子链。

错误兜底

若早期错误（如鉴权失败），后端合成 synthetic turnId，确保前端能挂入 turnTree 而非孤儿：

event: ERROR
data: {
  "type": "ERROR",
  "traceInfo": {
    "sessionId": "...",
    "turnId": "synthetic-uuid",
    "parentTurnId": null
  },
  "message": "Authentication failed: ..."
}

重试与断线重连

客户端实现建议

SSE 连接断开后：

记录最后收到的 turnId
调用 GET /{sessionId}/messages?since={lastTimestamp} 补齐 catch-up
不要重发原 intent（会重复消耗 credits）

Chat · 流式对话 API ​

端点全集 ​

1 · 提交意图（主对话入口） ​

请求体 · ChatRequest ​

ExecutionMode 三档 ​

响应 · SSE 流 ​

2 · 停止生成 ​

3 · 流中追加上下文（G1 协议） ​

4 · 恢复执行（Human-in-the-loop） ​

5 · 工具审批 ​

6 · 获取历史消息 ​

7 · 列出可用命令 ​

SSE 协议 ​

事件帧结构 ​

EventType 枚举 ​

协议事件家族 ​

Tool 事件家族 ​

UI 事件家族（独立顶级渲染） ​

Command 事件家族 ​

SubAgent 事件家族（v2 登神战役） ​

Traceable 三件套 ​

错误兜底 ​

重试与断线重连 ​

相关 ​

Chat · 流式对话 API

端点全集

1 · 提交意图（主对话入口）

请求体 · `ChatRequest`

ExecutionMode 三档

响应 · SSE 流

2 · 停止生成

3 · 流中追加上下文（G1 协议）

4 · 恢复执行（Human-in-the-loop）

5 · 工具审批

6 · 获取历史消息

7 · 列出可用命令

SSE 协议

事件帧结构

EventType 枚举

协议事件家族

Tool 事件家族

UI 事件家族（独立顶级渲染）

Command 事件家族

SubAgent 事件家族（v2 登神战役）

Traceable 三件套

错误兜底

重试与断线重连

相关