Skip to main content

Calling with cURL

Use cURL to quickly test Agent interfaces.

Check which protocol your Agent uses

An Agent's communication protocol is determined by the template it was created from. If its endpoint on the console's "Integration & Debugging" page ends with /acp (the cloudbase-agent template), it uses the ACP protocol; self-hosted HTTP Agents use the AG-UI protocol. The examples below are grouped by protocol.

Prerequisites​

  • Agent created
  • API Key obtained (create at CloudBase Console → Settings → API Keys)

Get Agent API Address​

  1. Go to CloudBase Console
  2. Select "AI Agent" → Select the corresponding Agent
  3. View the "API Address" in the Agent details page

API address format (the path suffix depends on the Agent's protocol — always trust what the console shows):

https://{envId}.api.tcloudbasegateway.com/v1/aibot/bots/{agentId}/acp            # ACP protocol (cloudbase-agent template)
https://{envId}.api.tcloudbasegateway.com/v1/aibot/bots/{agentId}/send-message   # AG-UI protocol (self-hosted HTTP Agent)

Calling an ACP Protocol Agent (cloudbase-agent template)​

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

Response example (agent_message_chunk carries the reply text; see the ACP protocol for details):

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

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

data: [DONE]

Calling an AG-UI Protocol Agent (self-hosted HTTP Agent)​

Send Message​

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": "Hello" }
    ],
    "tools": [],
    "context": [],
    "state": {}
  }'

Response Example​

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":"Hello"}

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

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

data: {"type":"RUN_FINISHED"}

Request Parameters​

ParameterTypeRequiredDescription
threadIdstringNoSession ID for multi-turn conversations
runIdstringNoRun ID
messagesarrayYesMessage list containing id, role, content
toolsarrayNoClient tools list
contextarrayNoContext information
stateobjectNoCustom state data