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 theclient_credentials grant:
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.0SendMessage 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.
"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:
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.
Related
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.