跳到主要内容

ACP 协议

基于 cloudbase-agent 模板（Managed Runtime）创建的 Agent 使用 ACP 协议通信：请求为 JSON-RPC 2.0，响应为 SSE 事件流。在控制台「接入 & 调试」页看到端点以 /acp 结尾的，就是这类 Agent。

端点​

POST https://{envId}.api.tcloudbasegateway.com/v1/aibot/bots/{agentId}/acp

同一 Agent 的 /send-message 路径接受相同的 ACP 请求。这是为小程序基础库等只能请求固定路径的客户端保留的别名，请求体中混入 SDK 自动附带的 botId 字段不影响解析。

请求头：

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

发送消息​

请求体为 JSON-RPC 2.0，方法为 session/prompt：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": {
    "prompt": [
      { "type": "text", "text": "你好" }
    ]
  }
}
参数类型必填说明
jsonrpcstring是固定 "2.0"
idnumber是请求编号，最终的 result 帧携带相同 id
methodstring是发送消息为 session/prompt
params.promptarray是内容块列表，文本块为 { "type": "text", "text": "..." }
params.sessionIdstring否会话 ID，不传则服务端新建会话

响应事件流​

响应为 SSE，每帧是一条 JSON-RPC 消息：过程事件是 session/update 通知，最后一帧是携带请求 id 的 result，流以 data: [DONE] 结束。

data: {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"d589adcd-...","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"用户在"}}}}

data: {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"d589adcd-...","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"你好！"}}}}

data: {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"d589adcd-...","update":{"sessionUpdate":"agent_phase","phase":"idle","timestamp":1785404449741}}}

data: {"jsonrpc":"2.0","id":1,"result":{"stopReason":"end_turn"}}

data: [DONE]

update.sessionUpdate 的事件类型：

类型说明
agent_message_chunk正文增量，content.text 即回复文本
agent_thought_chunk思考过程增量，可按需展示或忽略
agent_phase运行阶段变化
usage_update用量信息

客户端应忽略未识别的事件类型，保证向前兼容。

请求体不是合法 JSON-RPC 时返回 HTTP 400：

{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Invalid JSON-RPC 2.0 request"}}

多轮会话​

响应事件中的 params.sessionId 即会话 ID。下一轮请求把它放进 params.sessionId，即可延续上下文：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/prompt",
  "params": {
    "sessionId": "d589adcd-ccf5-418d-a606-2e7092fe0ee4",
    "prompt": [ { "type": "text", "text": "我们刚才聊到哪了？" } ]
  }
}

cURL 示例​

curl 'https://{envId}.api.tcloudbasegateway.com/v1/aibot/bots/{agentId}/acp' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"jsonrpc":"2.0","id":1,"method":"session/prompt","params":{"prompt":[{"type":"text","text":"你好"}]}}'

相关文档​