cURL
向会话写入事件,触发智能体处理。
图片与视频进入模型多模态视觉通道;文件由平台物化到会话沙箱文件系统,模型通过工具按需读取。
匹配、去重、混合输入等规则见下文「工具审批」。
回应工具审批请求。
匹配与去重
两者都不是本次 POST 的同步 4xx,需经 SSE 事件流或
合法示例:
input 为事件数组(长度 1–50),每个事件按 type 取下表之一:
| type | role | 说明 |
|---|---|---|
message | user | 发送用户消息,触发智能体进入 running;content 支持文本、图片、视频、文件四类内容块,详见 content 内容块 |
interrupt | user | 中断当前轮,会话回到 idle;可选 session_thread_id 定向中断子线程 |
tool_approval_response | user | 回应工具审批;规则见下文「工具审批」 |
function_call_output | tool | 回填自托管函数执行结果 |
tool_call_output | tool | 回填自托管平台内置工具的执行结果 |
interrupt 与普通 message 可在同请求混发(语义:先结束当前审批批次再开始聊天)。
content 内容块
图片与视频进入模型多模态视觉通道;文件由平台物化到会话沙箱文件系统,模型通过工具按需读取。
| type | 载体字段 | 说明 |
|---|---|---|
text | text | 纯文本 |
image | image_url、file_id 或 image_data + media_type | 图片,进入模型视觉通道;file_id 经平台解引用为临时 URL,仅本轮渲染,不持久化;image_data 为 base64 数据,须带 media_type(如 image/png) |
video | video_url 或 file_id | 视频,进入模型视觉通道;file_id 同上 |
file | file_id + filename | 文件/文档,物化到沙箱,模型按需读取;filename 为文件名,用于沙箱路径与清单展示 |
各事件字段
message
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
role | string | 是 | user |
type | string | 是 | message |
content | array | 是 | 内容块数组,支持 text/image/video/file,详见 content 内容块 |
interrupt
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
role | string | 是 | user |
type | string | 是 | interrupt |
session_thread_id | string | 否 | 多 agent 时定向中断子线程 |
tool_approval_response
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
role | string | 是 | user |
type | string | 是 | tool_approval_response |
content | array | 是 | 恰好一个 data 块,含 batch_id、call_id、result(allow/deny),可选 deny_message |
function_call_output / tool_call_output
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
role | string | 是 | tool |
type | string | 是 | function_call_output 或 tool_call_output |
content | array | 是 | 单个 data 块,含 call_id、output(字符串) |
is_error | boolean | 否 | 执行失败/被中断时为 true |
session_thread_id | string | 否 | 路由到子 agent 线程 |
工具审批 tool_approval_response
回应工具审批请求。content 为单个 data 块,data 字段如下:
| 字段 | 必填 | 说明 |
|---|---|---|
batch_id | 是 | 对应 tool_approval_request 的批次 ID |
call_id | 是 | 待裁决的工具调用 ID |
result | 是 | allow 或 deny |
deny_message | 否 | 仅 deny 时作为工具输出回传给模型 |
batch_id+call_id共同标识一次审批(复合身份),均非空- 不能只按
call_id匹配,也不得按call_id做会话级去重——不同批次可合法复用同一call_id - 同一请求内多条
tool_approval_response必须属于同一batch_id
pending_call_ids 不变):
| 输入组合 | 结果 | 错误码 |
|---|---|---|
tool_approval_response + 普通 message | 后续以 pending_tool_approval_unresolved 事件/终态反馈 | — |
tool_approval_response + interrupt | 控制消息冲突被拒 | invalid_tool_approval |
GET /events 观察。interrupt 与普通 message 可在同请求混发(语义:先结束当前审批批次再开始聊天)。
范围:工具审批仅支持主智能体,不支持子智能体。
content 校验
content 恰好一个 data 块。反例(均应被拒):
| 示例 | 原因 |
|---|---|
content: [] | 空数组 |
content: [{}] | 缺 type 与 data |
content: [{"type":"data"}] | 缺 data |
data: {"batch_id":"","call_id":"call_xxx","result":"allow"} | 空 batch_id |
data: {"batch_id":"b","call_id":"","result":"allow"} | 空 call_id |
content: [{"type":"data","data":{"batch_id":"...","call_id":"...","result":"allow"}}],或 result 为 deny 且带 deny_message。