文档中心

Appearance

控制台

通过 API 调用智能体 ​

控制台中的 API 调用 通过 /api/agents/Invoke 调用智能体实例。Invoke API 使用实例对应的 Token 鉴权，支持同步响应、SSE 流式响应、会话、中断、调用任务状态和文件输入。

需要从一个可运行样例理解两次请求如何完成用户工具中断时，参见构建可调用业务系统的工单助手。需要在同一个助手中组合知识检索和工单查询时，参见构建知识与工单协同的服务台助手。

开启 API 调用 ​

智能体实例 API 调用页面中的调用状态、Token 管理、HTTP 和 SSE 调用地址
  1. 打开目标智能体实例。
  2. 选择 API 调用。
  3. 在 API 调用状态 中开启开关。
  4. 生成 临时调试 Token，或选择 创建正式 Token。

关闭开关后，该智能体实例的临时调试 Token 和正式 Token 都不能调用 Invoke API，并且该实例已有的所有 Agent API Token 都会变为停用状态。重新开启 API 调用状态 不会自动重新启用这些 Token；请在 凭证管理 中启用原 Token 或创建替代 Token，再完成一次真实调用测试。

发送非流式请求 ​

使用部署提供的控制台域名作为 {base_url}：

language-bash
curl -X POST "{base_url}/api/agents/Invoke" \
  -H "Authorization: Bearer {agent_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "概括本周工单的主要问题",
    "stream": false
  }'

成功响应包含聚合结果：

language-json
{
  "thinking": "",
  "content": "本周工单主要集中在账号登录和权限配置。",
  "session_id": "b02d0b5b-5083-4e25-ae98-b21538bf1515",
  "status": "completed",
  "tool_calls": [],
  "tool_call_results": []
}

收到 session_id 后，根据业务对话选择后续请求方式：

  • 继续这段对话：保存并复用返回的 session_id。
  • 开始一段新对话：下一次请求不发送 session_id，由平台返回新的 ID。

调用方应把 session_id 与自己的用户或业务对话关联，不要让不同用户复用同一个 ID。完整生命周期参见管理 API 会话、调用任务和中断。

注意

新会话不会获得新沙箱

session_id 只标识对话上下文。省略原 session_id 开始新会话，不会创建、切换或清空智能体实例关联的沙箱。Invoke 请求也不能指定沙箱；需要按会话或调用任务隔离执行环境时，参见选择沙箱隔离范围。

接收 SSE 流式响应 ​

把 stream 设为 true：

language-bash
curl -N -X POST "{base_url}/api/agents/Invoke" \
  -H "Authorization: Bearer {agent_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "逐步分析这个故障",
    "stream": true
  }'

每个 data: 行是一个 JSON chunk，其 type 为：

  • thinking
  • content
  • tool_call
  • tool_call_result
  • interrupt
  • status
  • done

status 是可选的进度提示。客户端可以按其中的 seq 排序和去重，也可以忽略；不要用 status.phase 判断调用成功或失败。客户端必须收到 type: "done" 才把流视为正常结束。done.reason 为 completed、interrupted、error，服务重启时也可能返回 server_restart。

继续已有会话 ​

language-bash
curl -X POST "{base_url}/api/agents/Invoke" \
  -H "Authorization: Bearer {agent_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "b02d0b5b-5083-4e25-ae98-b21538bf1515",
    "prompt": "只列出权限配置相关问题",
    "stream": false
  }'

同一个 session_id 同时只能有一个活动流。并发调用会返回业务冲突错误。参见管理 API 会话、调用任务和中断。

为启用记忆的多用户调用设置隔离 ​

session_id 用于继续一段会话，不会把同一个记忆库按最终用户分开。通过同一个智能体实例服务多个业务用户，并且连接一个现有记忆库时，应把其中的长期记忆视为这些调用方共享的数据。

需要保存用户私有信息时，请按业务隔离范围使用不同的智能体模板、智能体实例和记忆库，或者由调用方业务系统保存长期用户记忆。资源分开后，使用两个测试用户写入相互冲突的事实，再分别新建会话确认双方不能检索对方的事实。完成验证前，不要写入个人信息或业务敏感数据。测试步骤参见验证多个调用方的记忆范围。

正确处理业务错误 ​

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

language-json
{
  "code": "api.409",
  "http_status_code": 409,
  "success_response": false,
  "data": {
    "reason": "stream_in_progress",
    "message": "..."
  }
}

客户端不能只检查 HTTP 状态码。还要检查 success_response、http_status_code 和 data.reason。可处理的业务状态包括 400、401、403、404、409、429、500 和 503。

使用正确的 Token ​

  • dbg_：控制台签发的临时调试 Token，仅在页面显示的有效期内使用。
  • agt_：正式 Token，在 凭证管理 中归类为 Agent API Token。
  • wst_：WebSocket 渠道 Token，不能用于 API 调用。

参见管理 API 调用和 WebSocket Token。