发送消息

Agent 对话接口，仅支持 SSE 流式响应。通过 Server-Sent Events 实时推送对话过程中的各类事件（消息分片、工具调用、思考过程、沙盒状态等）。

同时支持恢复中断执行（HITL），通过 action 字段区分普通对话和恢复中断。

接口路径：POST /v1/openapi/chat/send-messages

INFO

此接口为 Agent 类型应用的对话接口。

请求头

参数名	必填	说明
Content-Type	是	`application/json`
Authorization	是	鉴权凭证，格式 `Bearer sk_xxx`

请求参数

普通对话（action 为空或 "chat"）

json

{
    "app_id": "",            // 必填-应用ID
    "user_id": "",           // 必填-用户标识
    "username": "",          // 用户名称（可选，用于记录展示）
    "conversation_id": "",   // 会话ID，为空时创建新会话，后续对话传入此ID可续接同一会话
    "query": "",             // 必填-用户输入的问题
    "files": [               // 用户上传的多模态附件（可选），目前仅支持 image 类型，URL 须为公网可直接访问的完整地址
        {"type": "image", "url": "https://example.com/a.png"}
    ],
    "input": {},             // 变量参数，key 使用 variable_name，value 须符合变量 schema
    "response_mode": "",     // 响应模式：仅支持 streaming（流式），传入 blocking 无效
    "with_tts": false,       // 是否开启语音播报（仅 streaming 模式生效），开启后额外推送 tts_message 事件
    "tts_format": "",        // 语音格式：pcm（默认）/mp3/wav
    "select_model_id": ""    // 自由模式（loose_status）下指定的模型ID，非自由模式忽略
}

参数名	类型	必填	说明
app_id	string(uuid)	是	应用 ID
user_id	string	是	业务方用户标识
username	string	否	用户名称，用于记录展示
conversation_id	string(uuid)	否	会话 ID，为空时创建新会话
query	string	是	用户输入的问题
files	array	否	多模态附件列表，每项含 `type` 与 `url`（公网可访问完整 URL）。`type` 目前仅支持 `image`，非法类型或空 URL 会被过滤
input	object	否	变量参数，key 使用应用变量的 `variable_name`，value 须符合对应 `schema`
response_mode	string	否	仅支持 `streaming`，传入 `blocking` 无效
with_tts	bool	否	是否开启语音播报，仅 `streaming` 生效，默认 `false`
tts_format	string	否	语音格式 `pcm`（默认）/ `mp3` / `wav`
select_model_id	string(uuid)	否	自由模式下指定模型 ID，非自由模式忽略

变量输入

可通过应用详情获取已发布变量定义。input 不提交显示名称、控件或默认值状态；必填、默认值与加密掩码的处理规则见变量协议。

恢复中断（action = "resume"）

收到 interrupt 事件后，通过此方式提交人工响应，恢复 Agent 执行。

json

{
    "app_id": "",                    // 必填-应用ID
    "user_id": "",                   // 必填-用户标识（必须与原始会话的用户一致）
    "conversation_id": "",           // 必填-会话ID
    "action": "resume",              // 必填-指定为恢复中断
    "checkpoint_id": "",             // 必填-检查点ID（来自 interrupt 事件的 checkpoint_id）
    "responses": {                   // 必填-响应数据（Map 结构）
         // key: interrupt 事件中每个中断点的 interrupt_id
         // value: 对应中断类型的响应数据（见下方格式说明）
        "agent:app-id/tool:human_input": {"choice": "staging"}
    },
    "response_mode": "",             // 仅支持 streaming（流式），传入 blocking 无效
    "with_tts": false,               // 是否开启语音播报（仅 streaming 生效）
    "tts_format": "",                // 语音格式：pcm（默认）/mp3/wav
    "select_model_id": ""            // 自由模式下指定的模型ID
}

各中断类型的 responses 值格式：

中断类型	说明	responses 值字段	示例
`confirm`（确认）	请求用户确认或拒绝某个操作	`{"confirm": true/false}`	`{"confirm": true}`
`text_input`（文本输入）	请求用户输入一段文本信息	`{"text": "用户输入"}`	`{"text": "192.168.1.100"}`
`choice`（选项选择）	请求用户从预设选项中选择	单选：`{"choice": "value"}`；多选：`{"choices": ["v1","v2"]}`	`{"choice": "staging"}`
`form_input`（表单输入）	请求用户填写结构化表单数据	`{"form_data": {"field": "value"}}`	`{"form_data": {"host": "db.example.com", "port": 3306}}`
`content_review`（内容审核）	请求用户审核内容，可直接确认或编辑后提交	`{"confirm": true}` 或 `{"edited_content": "修改后内容"}`	`{"edited_content": "修改后的文本"}`
`tool_approval`（工具审批）	请求用户审批是否允许执行某个工具调用	`{"confirm": true/false}`	`{"confirm": true}`

恢复成功后返回新的 SSE 流，继续输出后续事件。恢复执行后的后续对话需将 action 设置为空或 "chat"，不可继续使用 "resume"。

断连重连（action = "reconnect"）

SSE 连接中途断开后，通过此方式重新订阅同一任务的事件流，服务端会从 last_event_id 之后的事件开始重放，不会重新执行 Agent。

json

{
    "app_id": "",            // 必填-应用ID
    "user_id": "",           // 必填-用户标识
    "action": "reconnect",   // 必填-指定为断连重连
    "task_id": "",           // 必填-要重连的任务ID（来自 start 事件的 task_id）
    "last_event_id": ""      // 可选-备选方式：不支持自定义请求头时传入，首选 Last-Event-ID 请求头
}

参数名	类型	必填	说明
app_id	string(uuid)	是	应用 ID
user_id	string	是	业务方用户标识
action	string	是	固定填 `reconnect`
task_id	string(uuid)	是	要重连的任务 ID，来自原 `start` 事件的 `task_id` 字段
last_event_id	string	否	备选方式：客户端最后收到的事件序号（uint64 字符串），用于不支持自定义请求头的场景；首选 `Last-Event-ID` 请求头，两者同时存在时请求头优先

推荐：通过请求头传递最后收到的事件序号（标准 SSE 重连方式）：

text

Last-Event-ID: 42

INFO

reconnect 仅支持 streaming 模式。若任务不存在或事件流已过期，服务端返回错误，客户端应改为调用历史消息接口拉取最终结果。

流式模式响应（streaming）

当 response_mode=streaming（或未传）时，接口返回 SSE 事件流。

SSE 响应头

text

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no

事件流格式

每条 SSE 事件由 event 和 data 两行组成：

text

event: {事件类型}
data: {JSON数据}

data 为 JSON 对象，所有事件均包含以下公共字段：

字段	类型	说明
event	string	事件类型名称
id	string(uuid)	事件唯一ID
conversation_id	string(uuid)	会话ID
message_id	string(uuid)	消息ID
task_id	string(uuid)	任务ID
timestamp	int64	事件时间戳（Unix秒）

执行生命周期事件

start — 执行开始

收到此事件后，SSE 连接开始每 5 秒自动发送 ping 心跳事件，直到连接结束。

若请求时 conversation_id 为空（创建新会话），start 事件的 data.conversation_id 会返回系统自动创建的会话 ID，后续对话传入此 ID 即可续接同一会话。

json

{
    "event": "start",
    "id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
    "conversation_id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
    "message_id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
    "task_id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
    "timestamp": 1777018922,
    "data": {
        "conversation_id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
        "app_id": ""
    }
}

completed — 执行完成

json

{
    "event": "completed",
    "id": "...",
    "conversation_id": "...",
    "message_id": "...",
    "task_id": "...",
    "timestamp": 1777018922,
    "data": {
        "content": "完整的回复内容",
        "finish_reason": "stop"
    }
}

failed — 执行失败

json

{
    "event": "failed",
    "id": "...",
    "conversation_id": "...",
    "message_id": "...",
    "task_id": "...",
    "timestamp": 1777018922,
    "data": {
        "error": "错误描述"
    }
}

cancelled — 执行取消

json

{
    "event": "cancelled",
    "id": "...",
    "conversation_id": "...",
    "message_id": "...",
    "task_id": "...",
    "timestamp": 1777018922
}

流式输出事件

chunk — 消息分片

逐字/逐句推送 AI 回复内容。

json

{
    "event": "chunk",
    "id": "...",
    "conversation_id": "...",
    "message_id": "...",
    "task_id": "...",
    "timestamp": 1777018922,
    "data": {
        "content": "你"
    }
}

Sub-Agent 运行期间，data 中会额外携带 agent_id（当前子智能体ID）、parent_agent_id（父智能体ID）、root_agent_id（主智能体ID）字段。所有事件在 Sub-Agent 运行期间均可能携带这三个字段，用于区分事件来源。

json

{
    "event": "chunk",
    "data": {
        "content": "你",
        "agent_id": "sub-agent-001",
        "parent_agent_id": "root-agent-001",
        "root_agent_id": "root-agent-001"
    }
}

thinking — 深度思考消息

json

{
    "event": "thinking",
    "data": {
        "content": "让我思考一下这个问题..."
    }
}

thinking_start / thinking_end — 深度思考开始/结束

json

{
    "event": "thinking_start",
    "id": "...",
    "conversation_id": "...",
    "message_id": "...",
    "task_id": "...",
    "timestamp": 1777018922
}

message — 完整消息

json

{
    "event": "message",
    "data": {
        "content": "完整的回复内容"
    }
}

工具调用事件

tool.start — 工具开始调用

json

{
    "event": "tool.start",
    "data": {
        "tool_call": {
            "id": "",
            "tool_id": "",
            "tool_name": "web_search",
            "arguments": {},
            "status": "running",
            "created_at": "2025-04-22T22:22:34Z"
        },
        "tool_label": "网页搜索"
    }
}

文件操作工具示例：

json

{
    "event": "tool.start",
    "data": {
        "tool_call": {
            "id": "",
            "tool_id": "",
            "tool_name": "write_file",
            "arguments": {"path": "src/main.py", "content": "print('hello')"},
            "status": "running",
            "created_at": "2025-04-22T22:22:34Z"
        },
        "tool_label": "写入文件"
    }
}

tool.result — 工具执行结果

json

{
    "event": "tool.result",
    "data": {
        "tool_result": {
            "id": "",
            "tool_call_id": "",
            "tool_name": "web_search",
            "tool_arguments": "{}",
            "result": "搜索结果内容",
            "duration": 0,
            "llm_duration": 0,
            "tool_duration": 0,
            "prompt_tokens": 0,
            "completion_tokens": 0,
            "total_tokens": 0,
            "created_at": "2025-04-22T22:22:34Z"
        },
        "tool_label": "网页搜索",
        "files": []
    }
}

files 字段

当工具为文件操作类工具时，files 字段会包含本次操作涉及的文件信息列表。每个文件对象含 name（文件名）和 path（对象存储链接地址）。

支持的文件操作工具：read_file、read_file_lines、write_file、edit_file、edit_file_by_line、list_directory、search_files、delete_file、rename、copy、read_pdf、create_pdf、read_excel、write_excel、read_word、write_word、get_skill_file。

rename 和 copy 工具会返回源文件和目标文件两个文件对象。

文件操作工具示例：

json

{
    "event": "tool.result",
    "data": {
        "tool_result": {
            "tool_name": "write_file",
            "tool_arguments": "{\"path\":\"src/main.py\",\"content\":\"print('hello')\"}",
            "result": "File written successfully",
            "duration": 120
        },
        "tool_label": "写入文件",
        "files": [
            {"name": "main.py", "path": "https://storage.example.com/workspaces/user_12345/src/main.py"}
        ]
    }
}

tool.call — 工具调用

json

{
    "event": "tool.call",
    "data": {
        "tool_call": {
            "id": "",
            "tool_id": "",
            "tool_name": "web_search",
            "arguments": {},
            "status": "pending",
            "created_at": "2025-04-22T22:22:34Z"
        }
    }
}

tool.error — 工具执行错误

json

{
    "event": "tool.error",
    "data": {
        "tool_call_id": "",
        "tool_name": "web_search",
        "error": "工具执行失败"
    }
}

Token 统计事件

token.usage — Token 用量

json

{
    "event": "token.usage",
    "data": {
        "usage": {
            "prompt_tokens": 0,
            "completion_tokens": 0,
            "total_tokens": 0,
            "first_token_duration": 0,
            "duration": 0
        }
    }
}

语音播报事件（TTS）

当请求 with_tts=true 且为 streaming 模式时，服务端在推送文本 chunk 的同时，按句合成语音并推送 tts_message 事件。

tts_message — 语音音频分片

json

{
    "event": "tts_message",
    "id": "...",
    "conversation_id": "...",
    "message_id": "...",
    "task_id": "...",
    "timestamp": 1777018922,
    "data": {
        "segment_index": 0,
        "audio": "<base64音频>",
        "is_segment_end": false,
        "format": "pcm"
    }
}

字段	类型	说明
segment_index	int	句序号，从 0 开始
audio	string	base64 编码的音频数据，句末收尾片为空串
is_segment_end	bool	是否为当前句的最后一片
format	string	音频格式：`pcm` / `mp3` / `wav`

TIP

pcm 格式恒为 24000Hz / 16bit / 单声道（不额外携带 sample_rate）。一句语音可能拆分为多片，按 segment_index 归并、is_segment_end=true 标记句末。

人工介入事件（HITL）

HITL（Human-in-the-Loop）流程中，human_input 工具的事件顺序如下：

中断前：Agent 调用 human_input 工具时，先触发 tool.start 事件（status: running），表示工具开始执行
中断：随即触发 interrupt 事件，SSE 连接随后断开，客户端保存 checkpoint_id 等待用户操作
恢复：客户端通过新请求（action: "resume"）提交人工响应，建立新的 SSE 连接
恢复后：新 SSE 流中首先触发 tool.result 事件，携带人工输入的结果，之后继续正常的事件流

text

[原始 SSE 流]
tool.start (human_input, status: running)
    ↓
interrupt (携带 checkpoint_id 和 interrupts)
    ↓  ← SSE 连接断开

[客户端发起 resume 请求，建立新 SSE 流]
tool.result (human_input, 携带人工输入结果)
    ↓
chunk / completed ...

WARNING

human_input 的 tool.start 和 tool.result 分属两个独立的 SSE 连接——tool.start 出现在原始流中，tool.result 出现在 resume 后的新流中。

tool.result 中的 result 字段为用户实际输入内容。confirm 类型时，result 为 Agent 配置的 true_label/false_label 文案（如"同意"/"拒绝"），未配置时回退为"用户确认：是"/"用户确认：否"。

interrupt — 中断等待人工输入

Agent 执行过程中需要人工介入时触发。支持多种中断类型，可同时包含多个中断点。

json

{
    "event": "interrupt",
    "data": {
        "checkpoint_id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
        "interrupts": [
            {
                "interrupt_id": "agent:app-id/tool:human_input",
                "payload": {
                    "type": "choice",
                    "title": "选择部署环境",
                    "description": "请选择要部署到哪个环境",
                    "options": [
                        {"value": "staging", "label": "Staging 环境"},
                        {"value": "production", "label": "Production 环境"}
                    ],
                    "required": true
                }
            }
        ]
    }
}

中断类型（type）说明：

类型	说明	payload 关键字段
`confirm`	请求用户确认或拒绝某个操作	`title`, `description`, `true_label`, `false_label`
`text_input`	请求用户输入一段文本信息	`title`, `description`, `placeholder`
`choice`	请求用户从预设选项中选择一个	`title`, `options: [{value, label}]`, `multiple`
`form_input`	请求用户填写结构化表单数据	`title`, `schema: {field: {type, label, required, ...}}`
`content_review`	请求用户审核内容，可直接确认或编辑后提交	`title`, `content`, `content_type`
`tool_approval`	请求用户审批是否允许执行某个工具调用	`tool_call: {name, arguments}`, `true_label`, `false_label`

payload 完整字段：

字段	类型	说明
type	string	中断类型（见上表）
title	string	显示给用户的标题
description	string	详细描述（可选）
true_label	string	确认按钮文案（confirm/tool_approval），不设置时客户端使用默认文案
false_label	string	拒绝按钮文案（confirm/tool_approval），不设置时客户端使用默认文案
placeholder	string	输入框提示文字（text_input）
options	array	选项列表，每项含 `value` 和 `label`（choice）
multiple	bool	是否允许多选（choice），默认 false
schema	object	表单字段定义（form_input），每个字段含 `type`、`label`、`required`、`default_value`、`placeholder`、`options`
content	string	待审核内容（content_review）
content_type	string	内容格式（content_review）：`text`（默认）、`markdown`、`code`
tool_call	object	工具调用信息，含 `name` 和 `arguments`（tool_approval）
timeout	int	超时时间（秒），0 表示不超时
required	bool	是否必须响应

interrupt_id 是中断点的唯一标识，恢复时需要在请求的 responses 中以此为 key 提交对应的响应数据。

沙盒事件

事件名	说明
`sandbox.creating`	沙盒创建中
`sandbox.created`	沙盒创建成功，data 含 `sandbox_id`
`sandbox.create_failed`	沙盒创建失败，data 含 `error`
`sandbox.workspace_syncing`	工作空间同步中
`sandbox.workspace_synced`	工作空间同步完成
`sandbox.workspace_sync_failed`	工作空间同步失败，data 含 `error`
`sandbox.skill_loading`	Skill 加载中，data 含 `skill_count`
`sandbox.skill_loaded`	Skill 加载完成，data 含 `skill_count`
`sandbox.skill_load_failed`	Skill 加载失败，data 含 `error`

sandbox.skill_loading

json

{
    "event": "sandbox.skill_loading",
    "data": {
        "skill_count": 3
    }
}

sandbox.skill_loaded

json

{
    "event": "sandbox.skill_loaded",
    "data": {
        "skill_count": 3
    }
}

sandbox.skill_load_failed

json

{
    "event": "sandbox.skill_load_failed",
    "data": {
        "error": "skill加载失败描述"
    }
}

Sub-Agent 事件

Sub-Agent 运行期间会产生 sub_agent.started、sub_agent.completed、sub_agent.failed 三个生命周期事件。同时，其他事件（chunk、thinking、tool.start、tool.result、tool.error 等）会额外携带 agent_id、parent_agent_id、root_agent_id 字段（参见 chunk 事件处的说明）。

sub_agent.started — 子智能体开始

json

{
    "event": "sub_agent.started",
    "data": {
        "agent_id": "sub-agent-001",
        "name": "子智能体名称",
        "parent_agent_id": "root-agent-001",
        "root_agent_id": "root-agent-001",
        "task": "子智能体任务描述"
    }
}

sub_agent.completed — 子智能体完成

json

{
    "event": "sub_agent.completed",
    "data": {
        "agent_id": "sub-agent-001",
        "name": "子智能体名称",
        "parent_agent_id": "root-agent-001",
        "root_agent_id": "root-agent-001",
        "result": "执行结果",
        "usage": {
            "prompt_tokens": 0,
            "completion_tokens": 0,
            "total_tokens": 0,
            "first_token_duration": 0,
            "duration": 0
        }
    }
}

sub_agent.failed — 子智能体失败

json

{
    "event": "sub_agent.failed",
    "data": {
        "agent_id": "sub-agent-001",
        "name": "子智能体名称",
        "parent_agent_id": "root-agent-001",
        "root_agent_id": "root-agent-001",
        "error": "错误描述"
    }
}

心跳事件

ping — 心跳保活

收到 start 事件后，服务端每 5 秒自动发送一次 ping 事件，直到 SSE 连接结束。

text

event: ping
data: {"timestamp":1777018922}

典型事件流示例

简单对话

text

event: start
data: {"event":"start","id":"...","conversation_id":"...","message_id":"...","task_id":"...","timestamp":1777018922,"data":{"conversation_id":"...","app_id":""}}

event: ping
data: {"timestamp":1777018922}

event: chunk
data: {"event":"chunk","id":"...","conversation_id":"...","message_id":"...","task_id":"...","timestamp":1777018922,"data":{"content":"你"}}

event: chunk
data: {"event":"chunk","id":"...","conversation_id":"...","message_id":"...","task_id":"...","timestamp":1777018922,"data":{"content":"好"}}

event: token.usage
data: {"event":"token.usage","id":"...","conversation_id":"...","message_id":"...","task_id":"...","timestamp":1777018922,"data":{"usage":{"prompt_tokens":10,"completion_tokens":2,"total_tokens":12,"first_token_duration":200,"duration":500}}}

event: completed
data: {"event":"completed","id":"...","conversation_id":"...","message_id":"...","task_id":"...","timestamp":1777018922,"data":{"content":"你好","finish_reason":"stop"}}

带工具调用的对话

text

event: start
data: {"event":"start",...}

event: tool.start
data: {"event":"tool.start",...,"data":{"tool_call":{"tool_name":"web_search","arguments":{"query":"天气"},"status":"running",...}}}

event: tool.result
data: {"event":"tool.result",...,"data":{"tool_result":{"tool_name":"web_search","result":"今天晴，25°C",...}}}

event: chunk
data: {"event":"chunk",...,"data":{"content":"根据查询结果，今天天气晴朗，气温25°C。"}}

event: completed
data: {"event":"completed",...,"data":{"content":"根据查询结果，今天天气晴朗，气温25°C。","finish_reason":"stop",...}}

发送消息 ​

请求头 ​

请求参数 ​

普通对话（action 为空或 "chat"） ​

恢复中断（action = "resume"） ​

断连重连（action = "reconnect"） ​

流式模式响应（streaming） ​

SSE 响应头 ​

事件流格式 ​

执行生命周期事件 ​

start — 执行开始 ​

completed — 执行完成 ​

failed — 执行失败 ​

cancelled — 执行取消 ​

流式输出事件 ​

chunk — 消息分片 ​

thinking — 深度思考消息 ​

thinking_start / thinking_end — 深度思考开始/结束 ​

message — 完整消息 ​

工具调用事件 ​

tool.start — 工具开始调用 ​

tool.result — 工具执行结果 ​

tool.call — 工具调用 ​

tool.error — 工具执行错误 ​

Token 统计事件 ​

token.usage — Token 用量 ​

语音播报事件（TTS） ​

tts_message — 语音音频分片 ​

人工介入事件（HITL） ​

interrupt — 中断等待人工输入 ​

沙盒事件 ​

sandbox.skill_loading ​

sandbox.skill_loaded ​

sandbox.skill_load_failed ​

Sub-Agent 事件 ​

sub_agent.started — 子智能体开始 ​

sub_agent.completed — 子智能体完成 ​

sub_agent.failed — 子智能体失败 ​

心跳事件 ​

ping — 心跳保活 ​

典型事件流示例 ​

简单对话 ​

带工具调用的对话 ​

发送消息

请求头

请求参数

普通对话（action 为空或 "chat"）

恢复中断（action = "resume"）

断连重连（action = "reconnect"）

流式模式响应（streaming）

SSE 响应头

事件流格式

执行生命周期事件

start — 执行开始

completed — 执行完成

failed — 执行失败

cancelled — 执行取消

流式输出事件

chunk — 消息分片

thinking — 深度思考消息

thinking_start / thinking_end — 深度思考开始/结束

message — 完整消息

工具调用事件

tool.start — 工具开始调用

tool.result — 工具执行结果

tool.call — 工具调用

tool.error — 工具执行错误

Token 统计事件

token.usage — Token 用量

语音播报事件（TTS）

tts_message — 语音音频分片

人工介入事件（HITL）

interrupt — 中断等待人工输入

沙盒事件

sandbox.skill_loading

sandbox.skill_loaded

sandbox.skill_load_failed

Sub-Agent 事件

sub_agent.started — 子智能体开始

sub_agent.completed — 子智能体完成

sub_agent.failed — 子智能体失败

心跳事件

ping — 心跳保活

典型事件流示例

简单对话

带工具调用的对话