Skip to main content

ACP Protocol

Agents created from the cloudbase-agent template (Managed Runtime) communicate over the ACP protocol: requests are JSON-RPC 2.0, and responses are an SSE event stream. In the console, an Agent whose endpoint on the "Integration & Debugging" page ends with /acp is one of these Agents.

Endpoint​

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

The same Agent also accepts identical ACP requests on /send-message. That path is an alias kept for clients such as the WeChat Mini Program base library, which can only request a fixed path. A botId field automatically added by those SDKs does not affect parsing.

Request headers:

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

Sending a message​

The request body is JSON-RPC 2.0 with the method session/prompt:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": {
    "prompt": [
      { "type": "text", "text": "Hello" }
    ]
  }
}
ParameterTypeRequiredDescription
jsonrpcstringYesAlways "2.0"
idnumberYesRequest ID; the final result frame carries the same ID
methodstringYessession/prompt for sending a message
params.promptarrayYesList of content blocks; a text block is { "type": "text", "text": "..." }
params.sessionIdstringNoSession ID. If omitted, the server creates a new session

Response event stream​

The response is SSE, and every frame is a JSON-RPC message: intermediate events are session/update notifications, the last message frame is a result carrying the request id, and the stream ends with data: [DONE].

data: {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"d589adcd-...","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The user is"}}}}

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

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]

Event types carried in update.sessionUpdate:

TypeDescription
agent_message_chunkReply text increment; the text is in content.text
agent_thought_chunkReasoning increment; display or ignore as needed
agent_phaseRun phase change
usage_updateToken usage information

Clients should ignore unrecognized event types to stay forward compatible.

When the request body is not valid JSON-RPC, the endpoint returns HTTP 400:

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

Multi-turn conversations​

params.sessionId in the response events is the session ID. Pass it back in params.sessionId on the next request to continue the conversation with context:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/prompt",
  "params": {
    "sessionId": "d589adcd-ccf5-418d-a606-2e7092fe0ee4",
    "prompt": [ { "type": "text", "text": "What were we just talking about?" } ]
  }
}

cURL example​

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