External Access (A2A)
Open a project's agent to AI agents outside AskRAI, which hand it work over the A2A protocol with an API key, an OAuth 2.0 client or a signed JWT, and, for the outside agent's developer, read its card, send a request, and read the answer, every refusal and the timing
An agent's External access tab opens it to AI agents outside AskRAI. An outside agent reads the agent's agent card, then hands it work with the A2A protocol, version 1.0 over JSON-RPC, authenticated as the agent's Method says: with one of your tenant's API keys, a short-lived token an OAuth 2.0 client obtains, or a JWT signed by a key you registered. AskRAI answers at once with a reference, and the work becomes a task in the agent's inbox, which its team works like any other.
The first sections are for the project Admin who opens the agent; from The addresses on, the page is for the developer of the outside agent that calls it. The example throughout is LumiCX, a voice agent that keeps a pay-TV customer who called to cancel, and then hands the customer's follow-up to a Retention Coordinator agent with the number they called from.
Opening an agent to outside agents
Open the Team tab, select the agent, and choose External access, the last of its Capabilities tabs. Changing anything on it needs Admin access to the project, because it lets callers outside AskRAI give the project work. Anyone else sees the tab read-only, with a line saying an Admin can change it.

Once access is on, the tab shows the two addresses the outside agent needs, and the keys it may call with.
Tick Accept requests from outside agents. The first time, Description for outside agents starts from the agent's own description, and every skill the agent has pinned is checked under Published skills.
Under Authentication, choose the Method, then add the credentials that may call, or create one there.
Under Expected input, add a field for each piece of data a caller sends.
Read the Agent card preview at the foot of the tab, then press Save external access. The badge beside Agent-to-agent access reads Live.
Give the outside agent's developer the Agent card URL and the key's secret over a secure channel, and send them to this page.
Save external access stays disabled, with the reason beside it, until the agent has a description for outside agents and at least one key. A project that is Archived cannot be opened. To close the agent again, untick Accept requests from outside agents and save: its card is no longer served, every request to it is refused as one to an address that names no agent, and what you set on the tab stays saved for the next time you open it.
Agent-to-agent access
- Endpoint and Agent card URL, each with a copy button: the agent's addresses.
- Description for outside agents, up to 1,000 characters: the card's description, which tells an outside agent what this agent does and when to send it work. It is kept apart from the agent's own description, which is written for its team.
Authentication
Method says how callers prove who they are, and the card says it to them. Each method takes its own kind of credential, at most 20 listed:
| Method | Callers send | You list |
|---|---|---|
| API key (Bearer) | one of the listed keys, as a Bearer token | API keys: credentials with Channel A2A, and those with Channel API that are not Personal Tokens |
| OAuth 2.0 (client credentials) | a token that lasts 15 minutes, which an OAuth client obtains from the Token URL shown under Method | OAuth clients |
| Signed bearer token (JWT) | a JWT they sign with their own private key | Signing keys: the public halves of their keys, which you register |
Changing the method removes the listed credentials of the other kinds, and changes the card, so tell your callers before you save it.
- Searching lists your tenant's active credentials of the method's kind. It needs View credentials.
- Create key, Create client or Register key opens the Create Credential dialog for that kind on Channel
A2A, then lists the new credential on the agent, as Programmable Access does. It needs Manage credentials. A key's secret, or an OAuth client's Client ID and Client secret, are shown once. A signing key asks for the Issuer and Audience its tokens carry and its Public key, and then shows its Key ID, which the caller puts in every token. AnA2Acredential calls only the agents that list it, and nothing else on the API. - Each listed credential shows its state. A key works only while its Channel's interface is on in the Interfaces panel, so turn on A2A there before you hand out an
A2Akey; until then the key readsInterface off. A key revoked, expired or deleted after it was listed stays listed, marked, and is refused.
Everything else that holds a key back holds an OAuth client or a signing key back here too: its IP allowlist, its expiry, its group, and its request budgets. Revoking or deleting one stops it at once, tokens it already obtained included, and rotating an OAuth client's secret ends its tokens. A key's group decides which knowledge packs and guardrails answer its queries; what governs the work an A2A request starts is the receiving agent's own guardrails and policies, on its beats.
Allowed callers
Marked Coming soon: choosing which registered outside agents may call. Until then, any caller holding a listed key may.
Published skills
What callers can ask for: a checklist of the skills the agent has pinned on its Skills & Tools tab, with Select all and Select none. An unchecked skill stays private to the project. The card shows each published skill as the agent's pinned version reads it, so an edit not yet published changes no card, and a skill unpinned from the agent leaves the card at once.
Expected input
The fields of the data a caller sends, at most 20. Each has a Name (lowercase letters, digits and underscores, starting with a letter, unique on the agent), a Type (string, number, integer, boolean, object or array), Required, a Description and an Example. A request missing a required field, or holding a declared field of another type, is refused before it becomes a task. Fields the caller sends that you did not declare reach the agent with the rest.

The examples you give make up the example request on the agent's card.
The Retention Coordinator expects what LumiCX sends:
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
phone_number | string | Yes | The number the customer called from, in E.164 with the leading + | +13105550142 |
language | string | No | The language of the call: es, en or pt | en |
retention_offer | object | No | The discount applied on the call | {"percent": 25, "months": 6} |
customer_id | string | No | The customer's id, when the call found the customer by it | DTV-C-7731904 |
Beneath the fields, What callers get back shows, read-only, the acknowledgement every accepted request is answered with.
How outside tasks run
Approve each task before it starts holds each request's task until someone on the project approves it: see Approving each request. It is ticked when you first turn access on, and unticked on an agent opened before it existed.
Stream progress to the caller: the agent's card offers SendStreamingMessage and SubscribeToTask, and a caller receives each task's result once the agent marks it done. Off, a caller follows a request's status through GetTask alone, and the result stays in the project. See Following a request.
Requests per minute, Cost cap per task ($) and Max open requests: the agent's limits on outside requests, opened on what was saved or on their defaults. See Limiting what outside agents ask of an agent.
When the agent needs more input: who answers the agent's question about a request, The agent's manager answers (the default) or The calling agent answers. Only a caller following its request over a stream can answer; any other request's question goes to the manager. See When the agent needs more input.
Marked Coming soon, shown disabled: notifying the caller when a task changes.
Agent card
The card outside agents read, previewed for the tab as you edit it, before you save, with Copy JSON.

The preview is built exactly as the served card is, so what you read here is what a caller reads.
The card's version changes when, and only when, the card's content does: renaming the agent or its organization, editing the description for outside agents, checking or unchecking a published skill or moving the agent to a version of one that reads differently, and, while a skill is published, changing the example request it carries (the names and examples of the expected-input fields that have an example) or adding the first field or removing the last. An outside agent may stop sending work until it has read a card that changed, as LumiCX does, so tell its developer before you change one. Some changes reach callers without moving the card: which keys may call, and an expected-input field's type, Required and description, and any field without an example, which the card does not carry. Tell the developer of those too, since a field made required refuses the requests that leave it out.
The addresses
Both addresses are on the agent's External access tab. Their base is https://public.askrai.ai:
| What | Method | Path |
|---|---|---|
| Agent card | GET | /a2a/org/{org_id}/proj/{project_id}/agent/{agent_id}/.well-known/agent-card.json |
| Endpoint | POST | /a2a/org/{org_id}/proj/{project_id}/agent/{agent_id} |
- The three ids are the agent's organization, project and agent, each 24 hexadecimal characters. A trailing slash names the same address.
- The card is public: it is read with no key, and counts against no request budget. It holds the agent's name, its organization's name, the description for outside agents, the published skills and the example input, and nothing secret.
- The card is served with
Cache-Control: public, max-age=300and anETag. Send thatETaginIf-None-Matchand an unchanged card is answered304. - A card that is not served is answered
404with{"error": "not_found"}: the agent's access is off, the agent or its project is archived, or the address names no agent. - Neither route is in the API Reference, and an A2A client finds the endpoint on the card.
The Retention Coordinator's card:
{
"name": "Retention Coordinator",
"description": "Takes over customers LumiCX retains on the phone: verifies the discount, opens the case, runs the specialists, and owns the retention plan.",
"supportedInterfaces": [
{
"url": "https://public.askrai.ai/a2a/org/6650f1c2a9e4b3d2c1f0a001/proj/6650f1c2a9e4b3d2c1f0a002/agent/6650f1c2a9e4b3d2c1f0a003",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": { "organization": "Acme", "url": "https://askrai.ai" },
"version": "1.0.0+5f3a9c1e",
"capabilities": { "streaming": false, "pushNotifications": false, "extendedAgentCard": false },
"securitySchemes": {
"askrai_api_key": {
"httpAuthSecurityScheme": {
"scheme": "Bearer",
"description": "An AskRAI API key, sent as Authorization: Bearer askrai_..."
}
}
},
"securityRequirements": [{ "schemes": { "askrai_api_key": { "list": [] } } }],
"defaultInputModes": ["application/json", "text/plain"],
"defaultOutputModes": ["application/json", "text/plain"],
"skills": [
{
"id": "retention-followup",
"name": "Retention followup",
"description": "Take over a customer another agent kept on a call, confirm the retention discount, and plan the follow-up that keeps them. Use when a retention handoff arrives with the customer's phone number.",
"tags": ["retention", "churn", "customer-success"],
"examples": ["{\"phone_number\": \"+13105550142\", \"language\": \"en\", \"retention_offer\": {\"percent\": 25, \"months\": 6}, \"customer_id\": \"DTV-C-7731904\"}"],
"inputModes": ["application/json"],
"outputModes": ["application/json", "text/plain"]
}
]
}- A skill's
idis its name in the skill library, and itsnamethat name with spaces for dashes and underscores. Itstagsare the published version's tags, else its category, elsegeneral. examplesholds one JSON object built from the expected input's examples, when any field has one.inputModesisapplication/jsonwhen the agent declares expected input.securitySchemesnames the agent's method. The card above takes API keys; an agent taking OAuth 2.0 namesaskrai_oauth2, anoauth2SecuritySchemewhoseclientCredentialsflow gives thetokenUrl, and one taking signed tokens namesaskrai_jwt, anhttpAuthSecuritySchemewithbearerFormatJWT.- Only A2A 1.0 is offered: there is no 0.3 card or endpoint.
Authentication
Every request to the endpoint carries Authorization: Bearer <credential>, the kind the agent's card names. Whatever the kind, it is checked as a key is on every other AskRAI endpoint, and refused with the same HTTP answers. A valid credential that the agent does not list, or that is of another kind than its method takes, is refused as an address that names no agent, so a caller never learns of an agent it may not call.
API key
Send one of the keys the agent lists, Authorization: Bearer askrai_<id>_<secret>.
OAuth 2.0 client credentials
Exchange the client's id and secret for an access token at the card's tokenUrl, https://public.askrai.ai/a2a/oauth/token, with HTTP Basic or with both in the form body:
curl -sS https://public.askrai.ai/a2a/oauth/token \
-u "$ASKRAI_CLIENT_ID:$ASKRAI_CLIENT_SECRET" \
-d grant_type=client_credentials{ "access_token": "askrai_at_6650f1c2a9e4b3d2c1f0a0aa_...", "token_type": "Bearer", "expires_in": 900 }Send Authorization: Bearer askrai_at_... until it expires, 15 minutes later, then ask for another. Each token asked for counts once against the client's and your tenant's request budgets. Ask for no scope: the card declares none. The client secret itself is refused on the endpoint, with 403 KIND_DENIED.
A refused token request is answered as OAuth 2.0 has it, {"error": ..., "error_description": ...}:
| HTTP | error | When |
|---|---|---|
400 | invalid_request | The body is not application/x-www-form-urlencoded, a parameter is missing or repeated, or the client authenticated both ways at once |
401 | invalid_client | The id or secret is wrong, or the client is revoked, expired, out of its IP allowlist or its group, or its interface is off |
400 | unsupported_grant_type | grant_type is not client_credentials |
400 | invalid_scope | A scope was asked for |
429 | RATE_LIMITED | A request budget is spent, or too many secrets from your address were refused within a minute, in the API's error envelope with Retry-After |
Signed bearer token (JWT)
Sign a compact JWT with the private half of the key the agent lists, and send it as Authorization: Bearer <jwt>:
- the header's
kidis the signing key's Key ID, and itsalgone the key's type signs:RS256,RS384,RS512,PS256,PS384orPS512for RSA of at least 2,048 bits,ES256for EC P-256,ES384for P-384,EdDSAfor Ed25519; issis the registered issuer andaudthe registered audience, or a list holding it;expis required and at most an hour ahead, andnbfandiat, when present, not in the future. Each time is allowed a minute of clock difference.
{ "alg": "ES256", "typ": "JWT", "kid": "6650f1c2a9e4b3d2c1f0a0bb" }
{ "iss": "https://agents.lumicx.example", "aud": "askrai-retention", "iat": 1794150000, "exp": 1794150300 }Any token that fails a check is refused 401 UNAUTHORIZED, as an unknown key is.
Sending a request: SendMessage
POST the JSON-RPC request to the endpoint, with Content-Type: application/json and A2A-Version: 1.0. A body may be up to 8,192 bytes, sent with a Content-Length header or chunked.
LumiCX's handoff, its key in ASKRAI_A2A_KEY:
curl -sS https://public.askrai.ai/a2a/org/6650f1c2a9e4b3d2c1f0a001/proj/6650f1c2a9e4b3d2c1f0a002/agent/6650f1c2a9e4b3d2c1f0a003 \
-H 'Content-Type: application/json' \
-H 'A2A-Version: 1.0' \
-H "Authorization: Bearer $ASKRAI_A2A_KEY" \
-d @handoff.jsonWith handoff.json:
{
"jsonrpc": "2.0",
"id": "0b6f0c1e-5d8e-4a8f-9a6e-2f1d3c4b5a67",
"method": "SendMessage",
"params": {
"message": {
"messageId": "9d3e7a10-2c4b-4f8e-8a51-6b0c2d1e3f47",
"role": "ROLE_USER",
"parts": [
{ "text": "Customer retained on the call with a discount; please take over the follow-up." },
{
"data": {
"phone_number": "+13105550142",
"language": "en",
"retention_offer": { "percent": 25, "months": 6 }
}
}
]
}
}
}message.roleisROLE_USER, andmessage.messageIda string of 1 to 128 characters, new for every handoff: it is how a retry is told from a new handoff.message.partsholds 1 to 20 parts, each exactly one oftextordata, wheredatais a JSON object. The text parts are joined, and the data objects merged in order, a later key winning: the merged data is what the expected input is checked against. A file part (raworurl) is refused.- Leave out
message.taskId: a new message starts a new task. A message naming a task is only ever an answer to the agent's question about it: see When the agent needs more input. contextIdis echoed in the answer, and a new one is made when you send none.referenceTaskIds,extensionsandmetadataare kept with the request and never acted on.params.configuration.acceptedOutputModes, when you send it, must includeapplication/jsonortext/plain.configuration.historyLengthabove 0 returns your message in the answer'shistory.configuration.returnImmediatelychanges nothing, as the answer is final either way.
The answer
200, with the task in its final state:
{
"jsonrpc": "2.0",
"id": "0b6f0c1e-5d8e-4a8f-9a6e-2f1d3c4b5a67",
"result": {
"task": {
"id": "3f2b6c1e-8d4a-4f6e-9b1c-2a7d5e8f0c34",
"contextId": "6a1d9e2f-4b7c-4c8d-a5e3-1f0b2c3d4e5f",
"status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2026-11-12T13:02:11.482Z" },
"artifacts": [
{
"artifactId": "ack",
"name": "Acknowledgement",
"parts": [
{ "data": { "accepted": true, "reference": "RAI-7K3Q9X" }, "mediaType": "application/json" },
{ "text": "Received. Retention Coordinator is taking it from here. Reference RAI-7K3Q9X." }
]
}
]
}
}
}- The handoff is the A2A task, and it is complete once accepted.
TASK_STATE_COMPLETEDmeans the request is the team's now.GetTaskthen tells you where the team's work on it stands; its result reaches you only from an agent that streams progress. - The reference,
RAI-and six characters of digits and capital letters (never I, L, O or U), is unique in the tenant. The project's people see it on the request and on the task it becomes, so quote it when you talk to them about this customer. idis the A2A task's id, which GetTask reads.- An answer is never
TASK_STATE_INPUT_REQUIREDorTASK_STATE_AUTH_REQUIRED: nobody can answer either in the middle of a call. - Enums are written by their names,
TASK_STATE_COMPLETEDandROLE_AGENT, as A2A 1.0 writes them.
A request the agent isn't taking is answered 200 too, with status.state TASK_STATE_REJECTED, a status.message from the agent (ROLE_AGENT, one text part) saying Retention Coordinator isn't taking requests right now., and {"accepted": false, "reference": ...} in the acknowledgement. That is the answer while the agent is Paused or Archived, or its project On hold or Archived. A rejected request makes no task. A team that is merely stopped still accepts requests, and works them when it is started.
Timing
The answer waits for nothing about the work: only for the key, the address, the request budgets and the request being recorded. Each answer past the key's check carries Server-Timing: app;dur=<ms>, how long AskRAI took from your request's arrival to its answer, which tells its share from your network's.
A request answered late is still accepted. Once it is recorded, its task is made and the team works it, even if your client stopped waiting. Nothing cancels it, as CancelTask refuses every task the agent answered: send the same message again, with the same messageId, and you get the original answer.
Idempotency and retries
A SendMessage repeating an earlier one's key, agent and messageId is answered with the earlier answer: the same task id, reference and state, under your new request's JSON-RPC id. Nothing is recorded again, no budget counts it, and no second task is made, however often you retry. A retry is checked again before it is answered, so it is refused if the agent no longer lists the key, or if the message no longer matches the agent's expected input.
- After a timeout, a dropped connection or a
503, retry with the samemessageId. Never callCancelTaskto give up on a handoff. - A new handoff, even about the same customer, takes a new
messageId. So does sending again a request that was rejected: the samemessageIdgets the same rejection back. - The same
messageIdsent with another key, or to another agent, is a new request.
Other methods
| Method | Answer |
|---|---|
SendMessage | The answer |
GetTask | params: {"id": "<task id>", "historyLength": 1}: the task as it stands, with metadata.followUp, for the key that sent it. Another key's task, an unknown id, or a request the project's reset or deletion has since cleared is -32001 |
CancelTask | -32002 for a task this agent answered: a caller cancels none of the team's work; -32001 for an unknown one |
SendStreamingMessage | From an agent that streams progress: The answer's checks, then a stream that follows the task |
SubscribeToTask | From an agent that streams progress: params: {"id": "<task id>"}, the stream of a task still running. A task that has ended, a SendMessage handoff among them, is -32004 |
SendStreamingMessage and SubscribeToTask of an agent that does not stream, ListTasks, GetExtendedAgentCard | -32004: the agent streams nothing, or has no extended card |
CreateTaskPushNotificationConfig, GetTaskPushNotificationConfig, ListTaskPushNotificationConfigs, DeleteTaskPushNotificationConfig | -32003: the agent sends no push notifications |
| Anything else | -32601 Method not found |
GetTask, CancelTask and SubscribeToTask count against no budget.
Following a request
Every task GetTask and a stream answer with carries where the team's work on it stands, as metadata.followUp:
"metadata": { "followUp": { "state": "done", "updatedAt": "2026-11-12T15:40:02.118Z", "result": "Retained on the 20% offer." } }stateiswaitinguntil the request is a task, then the task's status on the board (todo,in_progress,blocked,done,cancelled),input_requiredwith the agent'squestionwhile it waits for your answer,failedif no task could be made, orremovedonce its task was deleted.resultis what the agent wrote when it marked the task done. It is sent only by an agent with Stream progress to the caller on, which its task tells it, and only while that stays on.- A request awaiting approval reads
waiting, with noresult, until someone approves it. Declined, it readscancelled, and a stream endsTASK_STATE_CANCELED, saying nothing of why.
Streaming. An agent with Stream progress to the caller on lists "streaming": true in its card's capabilities. A SendStreamingMessage is checked and recorded as a SendMessage is, and answered with Content-Type: text/event-stream: each event a data: line holding a JSON-RPC answer whose result is the task, a statusUpdate or an artifactUpdate, as A2A 1.0 streams them. Its task starts TASK_STATE_SUBMITTED, is TASK_STATE_WORKING while the team works it, and ends TASK_STATE_COMPLETED, with a result artifact holding the result, or TASK_STATE_CANCELED or TASK_STATE_FAILED, after which the stream closes. That end is kept: a task reopened on the board moves followUp alone.
- A stream holds one of your key's concurrent streams, as a streamed query does: past its limit it is answered
429before the request is recorded. - A quiet stream sends a
: keepalivecomment every 4 seconds. - A stream may close before its task ends, as when AskRAI deploys, or when the key is revoked or the agent stops streaming. Send
SubscribeToTaskwith the task's id to pick it up where it stands: its first event is the task as it is now.
When the agent needs more input
An agent working a request can ask a question it cannot answer from what it was sent. Its question passes the agent's output guardrails, as everything it writes does, and at Manual autonomy it waits for a person's approval like any message. Who answers is the tab's When the agent needs more input.
The agent's manager answers (the default). The question arrives as a message from the agent to the person or agent it reports to, reading Question about request RAI-7K3Q9X (Request RAI-7K3Q9X from LumiCX): …, and a person is notified of it. An agent that reports to nobody asks the first of the people the project's decisions go to, never the whole project. Reply to the message as to any other: the reply reaches the agent the next time it works. The task carries on meanwhile, and the caller is told nothing.
The calling agent answers. Only a caller that sent SendStreamingMessage follows its task, so only it is asked, and only while its task has not ended for it and its key may still call the agent. Any other question goes to the manager instead, a request sent with SendMessage, whose task was final when answered, among them. While the agent waits, no agent works the task. The caller reads:
- the task
TASK_STATE_INPUT_REQUIRED, itsstatus.messagethe question, onGetTask,SubscribeToTaskor the stream, which closes there; metadata.followUpas{"state": "input_required", "question": "…"}.
Answer with SendMessage, or SendStreamingMessage to follow the task on, sending a new messageId and the task's id as message.taskId:
{
"jsonrpc": "2.0",
"id": "4c1f1f7e-2b8e-4f0a-9c3d-7e6a5b4c3d2e",
"method": "SendMessage",
"params": {
"message": {
"messageId": "a7d0c2f4-9e1b-4c6d-8f3a-2b5e7c9d1a0f",
"role": "ROLE_USER",
"taskId": "3f2b6c1e-8d4a-4f6e-9b1c-2a7d5e8f0c34",
"parts": [{ "text": "They took the 20% offer for six months." }]
}
}
}- An answer is checked as a request's message is, its body held to the same 8 KiB, and a field of the expected input it carries must be of its type. It counts against no budget.
- Only the key that sent the request can answer. Any other key, even one the agent lists, is answered
-32001. - The task reads
TASK_STATE_WORKINGfrom your answer on. Within a few seconds the agent wakes with your question and answer beside its task, and works on. Sending the samemessageIdagain is answered with the task as it stands; one task question takes one answer. - The project's Activity tab reads asked request RAI-7K3Q9X's caller: … and request RAI-7K3Q9X's caller answered. Someone on the project who changes the task's status while it waits takes it over: it no longer waits for your answer, you read the task where it stands, and an answer is then refused
-32004.
Refusals
A refusal of the key, of a spent budget or of the body is an HTTP answer in the API's error envelope, {"error", "code", "detail"}, as on every other AskRAI endpoint:
| HTTP | code | When |
|---|---|---|
401 | UNAUTHORIZED | The key is missing, malformed, unknown, revoked or deleted, or its Channel's interface is turned off, which its detail then names |
403 | CREDENTIAL_EXPIRED | The key has expired |
403 | IP_DENIED | The calling address is not in the key's IP allowlist |
403 | CREDENTIAL_UNGOVERNED | The key's group no longer exists, is inactive or does not list the key |
403 | CHANNEL_DENIED | The key's Channel is CLI or MCP, for example A CLI key cannot call an agent over A2A |
403 | KIND_DENIED | An OAuth client's secret was sent as a key: send the access token it obtains instead |
404 | The address names no agent this key may call: an id that names nothing, an agent whose access is off or that does not list the key, or three ids that do not belong together. The body is the JSON-RPC error -32601 No A2A agent at this address. | |
413 | CONTENT_TOO_LARGE | A chunked body grew past 8,192 bytes. A body whose Content-Length declares more is refused before it reaches the API, with 403 and an HTML page |
429 | RATE_LIMITED | A request budget is spent, or too many keys from your address were refused within a minute. Retry-After says when to try again, and is absent for a budget of 0, which no window renews |
503 | SERVICE_UNAVAILABLE | AskRAI could not record the request just then. Retry after Retry-After with the same messageId |
Past the address, every answer but a spent budget's 429 and a 503 is a JSON-RPC answer with HTTP 200, echoing your request's id, or null when it had none:
| Code | Message | When |
|---|---|---|
-32700 | Parse error | The body is not JSON |
-32600 | Invalid Request | The body is not one JSON-RPC 2.0 request object: a batch, or one with no jsonrpc: "2.0" or method |
-32009 | Version not supported | A2A-Version, as a header or a query parameter, is not 1.0. With none, A2A reads version 0.3, which is refused too |
-32601 | Method not found | A method A2A does not define |
-32602 | Names the first failure | The message is malformed (message.role must be ROLE_USER.), or the data misses a required field or holds a field of another type (phone_number is required., phone_number must be a string.) |
-32005 | Incompatible content types: … | A file part, or acceptedOutputModes that names neither application/json nor text/plain |
-32004 | This task isn't waiting for input. Send a new message without taskId. | message.taskId names a task of this key's that is not waiting for your answer |
-32001 | Task not found | message.taskId, or GetTask's or CancelTask's id, names no task this key sent this agent |
A refused request is not recorded, makes no task and counts against no budget. An error's data holds A2A's typed details, so an A2A SDK can read them: -32009 carries a google.rpc.ErrorInfo with "reason": "VERSION_NOT_SUPPORTED" and "metadata": {"supported": "1.0"}, and -32602 a google.rpc.BadRequest naming the field:
{
"jsonrpc": "2.0",
"id": "0b6f0c1e-5d8e-4a8f-9a6e-2f1d3c4b5a67",
"error": {
"code": -32602,
"message": "phone_number is required.",
"data": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [{ "field": "phone_number", "description": "phone_number is required." }]
}
]
}
}Many requests at once
- Each request is answered on its own, whatever the agent is doing, so ten callers at once get ten answers in the time one takes.
- Each accepted request becomes a task in the agent's inbox. The agent takes them most urgent first, as many a beat as its Max actions per beat allows, and hands parts of the work to its team.
Limiting what outside agents ask of an agent
Three limits under How outside tasks run bound what many callers at once can ask of one agent. Each counts every key that calls the agent together.
| Limit | Default | Past it |
|---|---|---|
| Requests per minute | 10 | 429 with RATE_LIMITED, a Retry-After of the seconds until the next UTC minute, and the detail This agent's budget of 10 requests per minute is spent. It renews in 23 seconds. |
| Max open requests | 50 | TASK_STATE_REJECTED, its status message Retention Coordinator is busy. Retry later with a new messageId., and no task. A request is open from its arrival until the task made of it is finished, and one stopped at its cost cap stays open until someone finishes it |
| Cost cap per task ($) | $0.50 | The request's work stops. Leave the box blank for no cap |
An agent opened before these limits existed is held to the defaults until an Admin changes them. A repeat of an earlier messageId is answered as it was, a rejection included, so a caller told the agent is busy retries with a new one.
A SendMessage also counts against the calling key's and your tenant's per-minute and per-day request budgets, as a query does, once it has passed the checks of its key, its address and its message, a rejected one included. Past them it is answered 429 with Retry-After. To give an outside agent a budget of its own, give it a key of its own, with limits set on that key.
A request stopped at its cost cap
A request's cost is what the agent's runs spent working its task, and the runs of any teammate working a task delegated under it. A run working several tasks at once shares its cost between them. Once a request's cost reaches the cap:
- every unfinished task of that request is set Blocked, and its result reads Stopped: the work on request RAI-7K3Q9X reached its cost cap of $0.50 ($0.53 spent).;
- the project's Activity tab reads stopped request RAI-7K3Q9X's work: it reached its cost cap of $0.50;
- no agent works those tasks again. A run already under way when the cap was reached can carry the cost a little past it.
To let the work go on, raise or clear the cap first, then move each stopped task out of Blocked: each one you move is resumed on its own. Moving one without raising the cap lets one more run work it, and that run stops it again.
What becomes of a request
Within a few seconds of the answer, an accepted request is a task in the agent's inbox:
- titled
Request RAI-7K3Q9X from LumiCX, LumiCX being the name of the key that called; - described by the request's text, then the line From LumiCX, over A2A (reference RAI-7K3Q9X). The caller already has its acknowledgement; nothing written here reaches it., or, from an agent that streams progress, … The caller follows this task's status, and receives your result when you mark it done., then its data as JSON;
- with the acceptance criteria Work this request as your instructions and skills say., High priority, and the agent as both its assignee and its creator.
The project's Activity tab reads received request RAI-7K3Q9X from LumiCX over A2A. While the team runs, the agent wakes for the task within seconds; a stopped team finds it when it is started. The caller's text and data reach the agent marked as the caller's words, apart from its own instructions. The task's drawer reads From LumiCX, over A2A · reference RAI-7K3Q9X, and its View request opens the request it came from.
Approving each request
With Approve each task before it starts ticked, the caller is still answered at once, exactly as above, and its request still becomes a task. But no agent is shown the task, its manager included, until a person approves it:
- The project is told. The people a proposal notifies get one notification, Retention Coordinator needs approval, naming the task, and the request waits in Pending approvals on the project's Interactions tab, counted with the agents' proposals.
- Approve releases it: the agent wakes for it and works it like any other task. The Activity tab reads approved request RAI-7K3Q9X, and only then the request's own entries, created task and received request, which every agent on the project can read.
- Decline closes it, as Done, with your optional reason as its result, Declined: Not one of our customers, and no agent ever sees it. The caller is not told: nothing of the decision goes back to it.
Deciding needs Write access to the project. Until someone decides, the task sits under Awaiting approval on the board, and a dashboard's tasks by status counts it under the same heading. Changing its status or assignee does not release it: only Approve does. A declined request moved back to To do returns to Pending approvals, still unseen by any agent. Unticking the box releases no request already waiting. A waiting request counts against the agent's Max open requests, so decide them as they come.
Incoming A2A requests
On the project's Interactions tab, above Pending approvals, the Incoming A2A requests card lists the requests outside agents sent the project's agents, newest first, with the exact messages exchanged. It shows once one of the project's Active agents is open to outside agents, or a request has arrived, to anyone who can read the project.

Each request keeps what was received and what was sent back, so a handoff can be traced from either side by its reference.
- Before any request arrives, it reads No requests yet, and a line per open, Active agent naming the active keys it lists, such as Retention Coordinator is listening for LumiCX.
- Each row reads the key's name, the reference and the agent, the method (
SendMessageorSendStreamingMessage) with· receivedand how long ago, and Acknowledged or Rejected. The card first shows the newest five, the newest open, and the header counts how many have arrived, as Showing 5 of 12 received while more are left to show. Load More adds the next five, and the rows scroll inside the card, so Pending approvals stays in reach below it. - An open row shows the request's history, then the Request and the Response sent, as JSON. The history reads Received, then Acknowledged in so many ms, or Rejected with why; then, for an accepted request, Waiting for the team to start in the seconds before its task is made, Task created with Open task, which opens it on the board, or Couldn't create the task with why: the agent or the project was deleted or archived in the meantime, or the task was refused. For an agent approving each request, a last line reads Waiting for approval, then Approved by or Declined by whoever decided, with their reason.
The card updates live while the project is open, as each request arrives and as its task is made. A project's Reset and its deletion clear its requests with the rest, after which GetTask no longer finds them. Deleting an agent keeps its requests as history.
Coming soon
What the tab shows marked Coming soon, and the protocol's parts that are not offered yet:
- Allowed callers: choosing which registered outside agents may call.
- Push notifications when a task changes.
- Answering a SendMessage handoff's question: a caller that sent
SendMessageholds a task already final, so its agent's question goes to the manager.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Save external access stays disabled with the access ticked | No description for outside agents, or no key listed | Fill in the description, and list at least one key |
| The tab reads that the endpoint and agent card URL show once the platform knows its public address | The environment has no public address to build them from | Contact AskRAI support |
A listed key reads Interface off | Its Channel's interface is turned off | Turn on A2A (or Runtime API, for an API key) under Programmable Access |
Every request is answered 404 with No A2A agent at this address. | The agent's access is off, it does not list the key, or the address was copied wrong | Turn access on and list the key, then copy the Endpoint from the tab again |
Every request is answered 404 since the method changed | The caller still sends a credential of the old method's kind | Give the caller a credential of the new kind, or set the method back |
Every signed token is answered 401 | Its kid is not the signing key's Key ID, its iss or aud differ from those registered, or its exp is missing or more than an hour ahead | Compare the token's header and claims with the signing key's details on Programmable Access |
The caller is answered -32009 | It sent no A2A-Version: 1.0 | Send the header on every request |
The caller is answered 429 with This agent's budget of … requests per minute is spent | More requests reached the agent this minute than its Requests per minute | Wait for Retry-After, or raise the limit |
| Requests are answered Rejected with … is busy. Retry later with a new messageId. | The agent holds its Max open requests | Finish or close its open requests' tasks, decide those waiting in Pending approvals, or raise the limit; the caller sends again with a new messageId |
| A request's tasks read Blocked, their result Stopped: the work on request … reached its cost cap | Its work cost its agent's Cost cap per task | Raise or clear the cap, then move each task out of Blocked |
| Requests are answered but no task appears | The request was Rejected, or Couldn't create the task, on the Incoming A2A requests card | Read the request's history there. Set a paused agent or an on-hold project back to Active, then ask the caller to send the request again with a new messageId |
Related pages
- Team — the agent's other tabs, and who can change them
- Programmable Access — the interfaces, keys and request budgets an outside agent calls with
- Interactions — the task board and the feeds where a request's work is seen
- Skills — the skills an agent pins, and publishes on its card
- Agent Heartbeat & Autonomy — how often an agent beats, and how much it may do on its own
Agent Heartbeat & Autonomy
Set how often an AI agent acts and how much it can do without you — configure an agent's cadence, autonomy level, and per-beat limits, and review the beats it has run
Assistants
Ask a project's assistants to build dashboards, propose agents and install connectors, and let them speak up when a run hits something the team can't get past