Skip to main content
The A2A API lets a system outside CloudThinker ask one agent a question over the Agent2Agent (A2A) protocol. The caller authenticates with the OAuth 2.0 client credentials grant, so no person has to log in. For every field, method and error code, see the A2A API Reference.

Prerequisites

  • The organization is on Scale or Enterprise. See Pricing.
  • You have the Developer or Admin workspace role. See Workspace users. If Add an outside caller is missing or greyed out, one of these two is the reason.
  • You know which agent should answer: CloudThinker itself or one of your custom agents. Each outside caller is tied to one agent in one workspace.

Add an outside caller

1

Open the sharing settings

Go to Agents settings, open the Sharing tab, and find Agents we share.
2

Add the caller

Click Add an outside caller. Enter a Name your team will recognize (for example “ServiceNow”), pick the Agent that answers, and optionally set a Monthly credit limit. Leave the limit empty for no limit.Under What it may do, keep or clear the three permissions. All are on by default. Ask lets the caller ask the agent and cancel its own tasks. Read tasks lets it read, list and follow its own tasks. Webhooks lets it set push URLs that receive its task updates.To let the caller sign in with private_key_jwt instead of the secret, paste an RS256 or ES256 public key in Public key (JWK, optional). Add it now: the caller’s row has no control to add or change the key later. Click Create client.
3

Copy the credentials

CloudThinker shows four values: Client ID, Client secret, Token URL and Agent URL. Copy the secret now. It’s shown once, and CloudThinker keeps only a hash of it. Store all four in the outside system’s secret store.
Every caller uses the same agent URL. The token decides which workspace and agent answer.

Get a token

POST to the token URL with HTTP Basic auth (client ID as the user, secret as the password) and the client_credentials grant:
The token is valid for 1 hour. Request a new one when it expires. To skip this step, send X-API-Key: <client ID>.<client secret> on each call instead; see Endpoints. For the token request options and errors, see Get a token.

Send a first message

POST a JSON-RPC 2.0 SendMessage request to the agent URL with the token as a Bearer token. Give each question a unique messageId. Resending the same messageId returns the first task instead of starting a new run, so retries are safe.
CloudThinker waits up to 110 seconds for the run to finish, then returns the task. To get it back at once, set "configuration": {"returnImmediately": true} in params. Keep the task’s id. If the task isn’t final yet, call GetTask with that id. An agent run can take minutes, so poll every 10 to 30 seconds:
Stop when status.state is TASK_STATE_COMPLETED, TASK_STATE_FAILED, TASK_STATE_REJECTED or TASK_STATE_CANCELED. On TASK_STATE_COMPLETED, the answer is the text in result.artifacts[].parts[]. To avoid polling, use SendStreamingMessage or SubscribeToTask, or set a push notification URL. See Task fields for every state. To ask a follow-up in the same conversation, send the task’s contextId as message.contextId.

What to expect

The agent answers questions but doesn’t make changes for an outside caller. The run uses the workspace System user, and the conversation shows “Asked by: <client name>” and marks it as an outside caller. Credits are charged to the workspace that owns the caller. By default, each caller runs at most 3 questions at once. See Errors for what a refused call returns, and what to do.

Rotate, pause or revoke

In Agents settings → Sharing → Agents we share, each caller’s row has three controls:
  • New secret: the old secret stops working at once. Tokens already issued keep working until they expire, up to 1 hour. Update the secret in the calling system right away.
  • The Let <name> ask switch: turned off, it pauses the caller, and new questions are refused with client_inactive. Turn it back on to resume.
  • Revoke: the secret, every token and any running questions stop. This can’t be undone.
Revoking a caller is permanent. To stop traffic without losing the caller, pause it instead.

A2A API Reference

Every endpoint, method, field, task state, error code and limit.

Public API

Read and act on workspace data with a scoped token.