Invoke API 参考

Invoke API 使用智能体实例的 dbg_ 或 agt_ Bearer Token。所有 JSON 字段使用 snake_case。

一次 Invoke API 运行在接口操作名中称为 Mission。本文将其称为“调用任务”；端点名称和错误值仍保留接口中的原文。

端点

Invoke API 提供智能体调用、任务状态管理和调用文件上传端点。

方法	路径	用途
POST	/api/agents/Invoke	新建会话、继续会话或响应中断
POST	/api/agents/GetMissionState	查询调用任务状态
POST	/api/agents/ResetMissionState	幂等重置调用任务
POST	/api/agents/Upload	multipart 文件上传
GET	/api/media/{id}	读取仍在有效期内的上传文件

管理智能体模板、智能体实例和能力的控制台 API 不属于本页的 Invoke API 范围。

鉴权

Authorization: Bearer agt_xxxxxxxxxxxxxxxx

可用 Token：

• dbg_：临时调试。
• agt_：正式调用。

wst_ 只用于 WebSocket 接入。

Invoke 请求

请求字段根据新建会话、继续会话或响应中断三种模式组合使用。

字段	类型	必填	说明
prompt	string	按模式	用户输入
files	string	否	上传接口返回的 URL
stream	boolean	否	true 返回 SSE
session_id	string UUID	否	继续已有会话；省略时开始新会话
interrupt_response	object	按模式	响应待处理中断

三种合法模式：

模式	字段
新会话	prompt
继续会话	session_id + prompt
响应中断	session_id + interrupt_response

prompt 与 interrupt_response 互斥。

首次请求省略 session_id，响应会返回新 ID。后续请求复用该 ID 可继续同一段对话；不再复用时，调用方可以开始新会话。Invoke API 不提供会话列表、读取、删除或可配置的会话过期时间，调用方需要保存会话与业务用户或业务对话的对应关系，并主动规定何时停止复用。停止复用只结束业务应用对这段对话的继续使用，不表示历史已经删除。完整生命周期参见管理 API 会话、调用任务和中断。

非流式响应

非流式调用在一个响应中返回聚合内容、会话状态、工具事件和中断信息。

字段	类型	说明
thinking	string	聚合的思考文本
content	string	聚合的最终文本
session_id	string	会话 ID
status	string	completed、interrupted 或 error
tool_calls	array	工具调用
tool_call_results	array	工具结果
pending_interrupt	object	中断详情
error_message	string	调用任务错误

工具调用包含 id、name 和 JSON 字符串 arguments。工具结果包含 id、result 和 status。

SSE chunk

每个 SSE data: 行包含：

type	对应字段
thinking	thinking.content
content	content.content
tool_call	tool_call
tool_call_result	tool_call_result
interrupt	interrupt
done	done

done 包含：

• session_id
• reason
• 可选 error_message

正常业务结果为 completed、interrupted 或 error。服务优雅重启时，活动流可能以 server_restart 结束。

中断响应

{
  "interrupt_id": "interrupt-001",
  "action": "APPROVE",
  "response_data": "",
  "additional_tool_rule": [
    {
      "tool_name": "get_order",
      "argument": "order_id",
      "pattern": "^SO-[0-9]+$"
    }
  ]
}

动作：

• APPROVE
• REJECT
• RESPOND
• ERROR

附加工具规则使用 RE2 兼容表达式。

调用任务状态（Mission）

GetMissionState 请求：

{
  "session_id": "b02d0b5b-5083-4e25-ae98-b21538bf1515"
}

响应状态为 active、interrupted、completed、error 或 not_found。completed 和 error 表示当前调用任务已经结束，interrupted 表示调用任务暂停并等待响应；这些状态不结束 API 会话。not_found 表示调用任务状态已经无法查询，不表示会话历史已删除。

时间字段 created_at 和 updated_at 是 Unix 纳秒；API 将 int64 时间字段编码为 JSON 字符串，JavaScript 客户端应按字符串或 BigInt 处理。

ResetMissionState 使用相同请求体，成功时返回空对象。重复重置不会产生额外效果。重置针对当前调用任务和待处理中断；该接口不是会话删除操作。

文件上传

请求使用 multipart/form-data，字段名为 file。一次请求可以重复该字段；允许的文件数量以目标部署限制为准。

响应：

{
  "data": [
    {
      "id": "md_xxxxxxxxxxxxxxxx",
      "filename": "contract.pdf",
      "mime": "application/pdf",
      "url": "https://example.com/api/media/md_xxxxxxxxxxxxxxxx",
      "expire_at": "1783656000000000000"
    }
  ]
}

expire_at 同样按 Unix 纳秒字符串处理。

错误信封

Invoke API 可能返回 HTTP 200，并在 JSON 信封中提供实际业务状态：

{
  "code": "auth.401",
  "http_status_code": 401,
  "success_response": false,
  "data": {
    "reason": "token_expired",
    "message": ""
  }
}

客户端处理顺序：

1. 读取响应 Content-Type。
2. 对 JSON 检查 success_response。
3. 使用 http_status_code 分类。
4. 使用 data.reason 决定恢复动作。
5. SSE 只有收到 done 才算正常结束。

常见 reason：

reason	处理
missing_token	添加正确 Bearer Token
temp_token_invalid	重新签发调试 Token
token_not_found	检查正式 Token
token_wrong_type	改用 API Token
token_disabled	启用或更换 Token
token_expired	轮换 Token
instance_not_found	检查绑定智能体实例
invoke_disabled	开启实例 API 调用
pending_interrupt	先响应中断
stream_in_progress	串行同一会话
mission not found	当前调用任务状态不可查询；核对业务结果后决定继续原会话或开始新会话
tenant_quota_exceeded	排队或降低活动调用任务数
server_draining	延迟后重试
server_restart	查询状态并按幂等策略恢复

服务暂时不可用时还可能返回 500 或 503 类错误，调用方应按幂等策略重试并告警。