跳到主要内容

cURL 调用

使用 cURL 可以快速测试 Agent 接口。

先确认你的 Agent 使用的协议

Agent 的通信协议由创建时的模板决定：控制台「接入 & 调试」页端点以 /acp 结尾的（cloudbase-agent 模板），使用 ACP 协议；自建 HTTP Agent 使用 AG-UI 协议。下文示例按协议分节。

前置条件​

  • 已创建 Agent
  • 已获取 API Key（在云开发控制台「设置」→「API 密钥」中创建）

获取 Agent API 地址​

  1. 进入 云开发控制台
  2. 选择「AI Agent」→ 选择对应的 Agent
  3. 在 Agent 详情页查看「API 地址」

API 地址格式（路径后缀由 Agent 协议决定，控制台展示的为准）：

https://{envId}.api.tcloudbasegateway.com/v1/aibot/bots/{agentId}/acp            # ACP 协议（cloudbase-agent 模板）
https://{envId}.api.tcloudbasegateway.com/v1/aibot/bots/{agentId}/send-message   # AG-UI 协议（自建 HTTP Agent）

调用 ACP 协议 Agent（cloudbase-agent 模板）​

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":"你好"}]}}'

响应示例（agent_message_chunk 为正文增量，详见 ACP 协议）：

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

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

data: [DONE]

调用 AG-UI 协议 Agent（自建 HTTP Agent）​

发送消息​

curl 'https://{envId}.api.tcloudbasegateway.com/v1/aibot/bots/{agentId}/send-message' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Accept: text/event-stream' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "threadId": "thread-001",
    "runId": "run-001",
    "messages": [
      { "id": "msg-1", "role": "user", "content": "你好" }
    ],
    "tools": [],
    "context": [],
    "state": {}
  }'

响应示例​

data: {"type":"RUN_STARTED","threadId":"thread-xxx","runId":"run-xxx"}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-1"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-1","delta":"你好"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-1","delta":"！"}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-1"}

data: {"type":"RUN_FINISHED"}

请求参数​

参数类型必填说明
threadIdstring否会话 ID，用于多轮对话
runIdstring否运行 ID
messagesarray是消息列表，包含 id、role、content
toolsarray否客户端工具列表
contextarray否上下文信息
stateobject否自定义状态数据

相关文档​