Invoke API 参考

智能体开发服务平台（AgentWorks）的智能体调用、调用任务管理和文件上传使用智能体实例的 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/v2/UploadMedia	multipart 文件上传
GET	/files/{id}?exp={expiration}&sig={signature}	使用上传响应返回的限时签名 URL 读取文件

注意

上传文件时，请使用本版本公开支持的 /api/v2/UploadMedia。如果控制台的 API 调用 ＞ 接入文档 显示 /api/agents/Upload，仍按本页地址集成。

管理智能体模板、智能体实例和能力的控制台 API 不属于本页的 Invoke API 范围。dbg_ 和 agt_ Token 不能用于创建、绑定或删除沙箱，Invoke 请求也没有选择沙箱的字段，因此不能通过 Invoke API 为每段会话或每个调用任务动态准备 AgentWorks 沙箱。参见选择沙箱隔离范围。

鉴权

Authorization: Bearer agt_xxxxxxxxxxxxxxxx

可用 Token：

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

wst_ 只用于 WebSocket 接入。

文件下载不使用 Bearer Token。请直接使用上传响应返回的完整签名 URL，并保留其中的 exp 和 sig 参数。

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 互斥。

继续会话或响应中断时，请始终在 JSON 请求体中发送 session_id。当前公共接口未支持以 X-Session-Id 请求头代替该字段，也未规定请求头与请求体同时出现时的优先级。

首次请求省略 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。

tool_calls 和 tool_call_results 都可能包含多项，并汇总本次调用任务中的工具事件。调用方应按相同的 id 关联调用与结果。需要判断调用是否来自同一轮模型响应或是否同时执行时，请结合 Trace 中的模型事件和发生时间核对。

SSE chunk

每个 SSE data: 行包含：

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

status 是用于界面进度展示的尽力而为事件，包含单调递增的 seq、事件来源 source、阶段 phase、JSON 字符串 details、毫秒时间戳 timestamp 和可选 context_key。seq 和 timestamp 在 Protocol Buffers 中是 int64，SSE 的 JSON 数据会把它们编码为十进制字符串；客户端应按字符串或 BigInt 处理，不要先转换为 JavaScript Number。客户端可以按 seq 排序和去重，也可以完全忽略该事件。事件可能缺失、重复或因来源不同而使用不同的 details 结构；请以 done 或调用任务终止状态判断运行结束，以 Trace 进行审计，并由客户端另行保存重连恢复所需的状态。

{
  "type": "status",
  "status": {
    "seq": "12",
    "source": "loop_telemetry",
    "phase": "start",
    "details": "{\"iteration\":1,\"phase\":\"start\"}",
    "timestamp": "1784685600123"
  }
}

该示例展示一种可能返回的循环进度。读取 details 时，请按字段名处理，不依赖字段顺序。

done 包含：

• session_id
• reason
• 可选 error_message

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

中断响应

{
  "interrupt_id": "interrupt-001",
  "action": "APPROVE",
  "response_data": ""
}

status 为 interrupted 时，pending_interrupt 表示待处理中断。正常情况下，一次 interrupt_response 使用一个 interrupt_id；恢复后如果再次返回 interrupted，继续处理新返回的中断。

注意

当前公共 Invoke 接口一次提交一个中断响应。如果一个 pending_interrupt 中同时出现多个 tool_calls，请保存原始负载、session_id 和调用任务状态，保持调用暂停并联系平台支持。生产审批流程应让需要人工处理的工具按顺序出现。公共接口的审批动作使用 APPROVE 或 REJECT；内部 EDIT 行为不属于公开动作。

动作：

• APPROVE
• REJECT
• RESPOND
• ERROR

不要在请求中依赖 additional_tool_rule。当前公共处理器不会应用该字段；需要长期自动处理的规则应在智能体模板的 工具权限 中配置并完成回归测试。

调用任务状态（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 只清除当前调用任务及其待处理中断，会话历史继续保留。该接口使用相同请求体，成功时返回空对象；随后使用同一个 session_id 调用 GetMissionState 会返回 not_found。重复重置不会产生额外效果。

文件上传

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

响应：

{
  "data": [
    {
      "id": "md_xxxxxxxxxxxxxxxx",
      "filename": "contract.pdf",
      "mime": "application/pdf",
      "url": "https://example.com/files/md_xxxxxxxxxxxxxxxx?exp=1783656000&sig=xxxxxxxx",
      "expire_at": "1783656000000000000"
    }
  ]
}

expire_at 同样按 Unix 纳秒字符串处理。把 url 视为不透明的完整 URL：不要自行拼接、删除或修改查询参数，也不要把完整 URL 写入日志。URL 过期后应重新上传文件。

错误信封

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 类错误，调用方应按幂等策略重试并告警。