A2A Protocol
Trinity speaks the open A2A (Agent-to-Agent) protocol, so an exposed Trinity agent is reachable by any A2A-capable orchestrator — Google ADK, LangChain, AWS Bedrock AgentCore, or another Trinity — and can, in turn, call external A2A agents. To an outside orchestrator, your agent looks like any other A2A agent; it never needs to know Trinity's internal API.
This guide covers both directions:
Availability. The two directions are not gated alike.
404 — off and invisible by default. Parts 1 and 2 assume it's enabled.Concepts
| Term | Meaning |
|---|---|
| Agent Card | A JSON document (A2A's discovery primitive) advertising the agent's name, skills, endpoint URL, and auth scheme. Generated from the agent's template.yaml. |
| Well-known URL | The public, unauthenticated discovery URL: {base}/a2a/{agent}/.well-known/agent-card.json. This is what you hand to an external client. |
| JSON-RPC endpoint | POST {base}/a2a/{agent} — the A2A task endpoint (spec v0.3.x): message/send, message/stream, tasks/get, tasks/cancel. |
| Inbound allow-list | Optional per-agent list of caller account emails permitted to task the agent. Empty = any authenticated owner/shared caller. |
| Outbound endpoints | External A2A endpoints (+ optional credentials) agents may call — one platform-wide list, managed in Settings › Integrations. |
| AAuth identity | aauth:<agent-name>@<issuer-host> — how an agent on one Trinity instance is known to another once AAuth is on. The calling instance signs each call with a key only it holds; the receiving instance verifies the signature and admits only identities listed on the target agent's inbound allow-list. No shared secret. See AAuth agent identity. |
Part 1 — Expose an Agent (Inbound)
Using the web UI
Open the agent's detail page and select the A2A tab.

Flip "Expose over A2A" on. It's OFF by default. While off, the public routes return 404 and the agent is invisible to the A2A ecosystem.
Copy the Agent Card URL. Once exposed, the panel shows the public discovery URL with a one-click Copy button. Hand this to whoever is wiring up the external orchestrator.

Review the advertised skills — exactly what an external caller sees on the card (derived from the agent's template.yaml capabilities). This is a known limit: elsewhere those are template tags, and a capability is described by its skill's SKILL.md description: (Template tags are not capabilities). The card still lists the tags, each carrying the agent's description, until it moves to the agent's skills.
Manage the inbound allow-list (optional) — add the account emails of callers that may task the agent. Leave it empty to allow any authenticated owner/shared caller. When AAuth is on, this is also where you list the aauth:<agent>@<host> identities of agents on other instances that may task this agent — for those, an empty list means nobody (see Inbound allow-list).
Outbound endpoints are not registered here. The tab links to Settings › Integrations, where an admin manages the platform-wide list call_a2a_agent reads — see Outbound endpoints.
Using MCP (drive it from an agent / automation)
The same controls are available as MCP tools, so you can expose and configure agents conversationally or from a script:
| Tool | What it does |
|---|---|
| get_agent_a2a_config | Read exposure state, card URL, skills, allow-list, endpoints |
| set_agent_a2a_exposure | Toggle A2A exposure on/off |
| get_agent_a2a_card | Fetch the served Agent Card JSON |
| set_a2a_inbound_allowlist | Add/remove inbound identities |
| register_a2a_endpoint / list_a2a_endpoints / remove_a2a_endpoint | Manage the platform-wide outbound endpoint list — the one call_a2a_agent resolves against, and the same list the Part 3 routes manage. register_a2a_endpoint takes auth_scheme (bearer or aauth) to choose how calls to that endpoint authenticate. agent_name is accepted but ignored, because the list is not per-agent |
Exposure and credential operations are owner/admin and human-only— an agent-scoped key can't flip its own exposure. Reads use the standard agent-access gate.
The first four tools need the A2A capability enabled; the three outbound-registry tools do not, and work on every edition. Those three are admin and human-only — one tier up — because the list they write is platform-wide (see Part 3).
Part 2 — Consume an Exposed Agent (External Orchestrator)
Once an agent is exposed, an external A2A client discovers and tasks it in three steps. The examples below use curl against a local instance (the frontend's front door on port 80); a real A2A SDK does the same automatically.
1. Discover — fetch the Agent Card
curl -s http://localhost/a2a/new_cool_agent/.well-known/agent-card.json | jq{
"protocolVersion": "0.3.0",
"name": "new_cool_agent",
"url": "http://localhost/a2a/new_cool_agent",
"preferredTransport": "JSONRPC",
"capabilities": { "streaming": true },
"securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } },
"skills": [ ]
}url is the JSON-RPC task endpoint; securitySchemes.bearerAuth tells the client to attach a Trinity MCP API key as a Bearer token.
2. Authenticate — a Trinity MCP API key
Issue an MCP key from Settings → MCP Keys (or the API) and share it with the external client. It's a trinity_mcp_… key, sent as Authorization: Bearer $TOKEN on every task call; unauthenticated calls fail closed with 401. The examples below assume you've exported it: export TOKEN=trinity_mcp_….
An agent on another Trinity instance needs no key when both instances have AAuth on: its call is signed with its own identity instead, and the key step above is skipped — see AAuth agent identity. While AAuth is live here, the 401 an unauthenticated call gets also carries Accept-Signature, Accept-Signature-Scheme: jwt and AAuth-Requirement: requirement=agent-token, so an AAuth-aware client learns it may sign instead.
3. Task — JSON-RPC 2.0
Send (message/send):
curl -s -X POST http://localhost/a2a/new_cool_agent \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"jsonrpc": "2.0", "id": 1, "method": "message/send",
"params": { "message": {
"role": "user", "messageId": "req-1",
"parts": [{ "kind": "text", "text": "Summarize today’s sales." }]
}}
}' | jqReturns an A2A Task:
{ "jsonrpc": "2.0", "id": 1, "result": {
"id": "zAS45ahu2fwsHG9rwdKxQQ", "kind": "task",
"status": { "state": "completed" },
"artifacts": [{ "parts": [{ "kind": "text", "text": "…the answer…" }] }]
}}Long turns come back working. message/send holds the request for up to 25 seconds. A turn that finishes inside that window returns the completed Task above. A longer turn returns early with the same Task id and "status": { "state": "working" } (or "submitted" while the agent's queue has not started it yet) and no artifacts. The agent keeps working. Poll tasks/getwith that id until the state is terminal. The 25 seconds sit under the 30-second read timeout of Trinity's own A2A client, so a caller always gets the id before it gives up. Before this, a long turn surfaced as a timeout and the id was lost.
You can choose the behaviour per call with the A2A params.configuration.blocking flag:
| blocking | message/send answers |
|---|---|
| absent (default) | the completed Task, or working + id after 25 s |
| true | only at the terminal, however long the turn takes (your client must wait that long) |
| false | at once, with working/submitted + id; poll for the result |
A client that disconnects does not cancel the turn. It still runs to the end, and the result is waiting on tasks/get.
Streaming (message/stream, Server-Sent Events): same params, method: "message/stream". You receive a working status event, then a final completed task event. Streaming ignores blocking.
Poll / cancel: tasks/get and tasks/cancel take { "id": "<taskId>" }. The taskId is the id from the send response, including a working one. A task the agent refused to run (a gated skill, for example) reads as rejected with the reason. It never stays working.
Who may poll a task. Only the credential that sent it. A task started with an API key can be polled and cancelled with that same key, and a task you sent while signed in, by you while signed in. Every other caller, including the agent's owner, an admin, and another key or agent of the same account, gets Task not found: the same answer as an id that does not exist. A key that is replaced (an agent's key is re-issued when the agent is recovered, for example) can no longer poll tasks the old key sent. To see every run of an agent, use its Executions view in Trinity.
Idempotency. Re-sending the same messageId returns the original task without re-executing — safe to retry on a dropped connection. While that task is still running, the re-send returns it as working with the same id. Once it has finished, the re-send returns the completed Task. Poll; don't re-send under a new messageId, which would run the work twice.
Inbound Allow-List
By default, any caller authenticated as an owner/shared identity for the agent may task it. To restrict further, add identities in the Inbound allow-list section. With a non-empty list, only listed identities are accepted; everyone else gets 403.
Use the caller's Trinity account email— the identity Trinity compares against is the calling account's email, falling back to its username when the account has no email. A DID or caller URL will never match, so a list containing only those denies every real caller.
AAuth callers are listed by identity. An agent calling from another Trinity instance over AAuth has no Trinity key, so this list is the only thing that admits it: add its aauth:<agent>@<issuer-host> identity, exactly as the calling instance's Settings page shows it. For AAuth callers the list fails closed — an empty list means nobody, and a policy error refuses rather than admits. The calling instance's host must appear in at least one aauth: entry before Trinity will even fetch that instance's keys, so a stranger cannot make your backend go and look up a domain nobody listed. See AAuth agent identity.
On the agent's A2A tab, each allow-list entry carries a badge: AAuth for an aauth: identity, Local for an account on this instance. Typing an aauth: entry that does not look like aauth:<agent-name>@<peer-host> shows the expected format under the field before you add it.
The allow-list is a restriction, not a security boundary. It layers on top of authentication — every caller has already passed the 401 and the owner/shared access check before it is consulted. For callers holding a Trinity key it also fails open: if the policy backend errors, the request is allowed rather than denied, matching Trinity's availability bias (an AAuth caller is refused on the same error, because nothing else has authenticated it). Don't rely on it as the only thing standing between an untrusted caller and the agent; that job belongs to authentication and sharing.
Charge for Inbound A2A Calls
If an exposed agent has Paymentsconfigured (Agent → Payments tab, x402 via Nevermined), callers without a Trinity key pay to task it over A2A — the same paywall the paid chat endpoint has always had, now on the A2A door.
Who pays, and who doesn't:
| Caller | What happens |
|---|---|
| Another agent in your fleet, you, or anyone the agent is shared with (a valid Bearer MCP key) | Runs free, exactly as before. Nothing about your internal traffic changes. |
| A subscription tenant | Unaffected. |
| A stranger, on an agent with payments off | 401, exactly as before. |
| A stranger, on an exposed agent with payments on | 402 Payment Required with what to pay; a valid token runs the task and settles. |
How an external client pays. It reads the price off the discovery card, buys plan credits from Nevermined, and sends the payment in the A2A message's metadata under x402.payment.payload. The older payment-signature HTTP header still works as a fallback, and if a client sends both, the one in the message wins. The reply is a normal A2A Task carrying the payment status and a receipt: the primary location is status.message.metadata, which is where the x402 A2A extension puts it and where payment-aware SDKs read it. The same object is also mirrored onto the Task's own top-level metadata, so a strictly typed client sees the receipt rather than metadata: null. A free turn's Task carries no metadata key at all.
The card tells a client the price before it calls. An exposed, priced agent's /.well-known/agent-card.json carries a payment entry under capabilities.extensions with the plan id, the credits per call, and a paymentInfoUrl pointing at /api/paid/{agent}/info — so a payment-aware client can pay on its first request instead of being refused once to learn the price. An agent with no payment config has a byte-identical card to before.
A price on the card does not mean the door is open. The card says what the agent costs; A2A exposure is what makes the paid A2A door reachable. On a build without the exposure feature, a configured price block points at a door that answers 404— turn exposure on for that agent to open it.
Crypto and card (fiat) plans both work: Trinity advertises the x402 scheme that matches the agent's plan, and the 402's resource.url uses the public origin buyers reach you on. See Nevermined Payments for both.
Time-based (duration) plans. Set Credits per Request to 0. A duration plan charges by time, so Trinity sends no per-call amount and the plan decides what a call burns; 0 says that honestly rather than claiming a per-call price nothing will charge. The card then advertises the cost as plan-defined. (A negative number is rejected.)
Retrieving a paid result. A paid message/send follows the 25-second rule in Task: a long turn answers working with the task id. The task is bound to the paying wallet before that answer is sent, so the payer can poll tasks/get with the same token straight away, mid-turn included. Any other caller gets the ordinary "task not found". The charge settles when the turn completes, not at the working answer.
in_flight error ("still being processed"). Poll the id you already have.tasks/cancel a running paid task. A cancelled turn is never charged and delivers no answer.Refusals, and what they mean:
| Answer | Meaning |
|---|---|
| 401 | No price configured for this agent (or it isn't exposed) — authenticate with a Trinity key. |
| 402 | Pay, then retry. The body and the payment-required header say what to buy. |
| 403 | The token was rejected (or your wallet isn't on the agent's inbound allow-list). |
| 429 | Rate limited. The paying path is capped per source address and per agent. |
| 501 | Payments are configured but this Trinity install can't process one right now. |
A refusal that is our side being busy rather than a verdict on your token — a payment checker that timed out, or too many payment checks in flight — is not a 403. It comes back as a JSON-RPC error carrying data.retryable: true, with a data.code saying which case it is (verify_unavailable — we could not check; in_flight — your own identical request is still running). Retry those with the same token; never buy another. payment_rejected and not_allowed carry retryable: false. On message/stream the same classification arrives as an error event, because a status code cannot be sent once the stream has opened.
Paid calls are logged as money.Each settled call records the paying wallet, the execution it paid for, and the source address. A delivered turn whose settlement fails still returns your result and is reported as unsettled rather than as a clean success — Trinity never claims it charged you when it didn't, or that it delivered for free when it is still reconciling.
Outbound Endpoints
The external A2A endpoints agents may call (name + URL + optional credential) are one platform-wide list, the one call_a2a_agent resolves. An admin manages it on the Outbound A2A endpoints panel in Settings › Integrations, with the routes in Part 3, or with register_a2a_endpoint; all three address the same list. Each endpoint has an authentication scheme: Bearer credential (the stored credential goes out as Authorization: Bearer) or AAuth (the call is signed as the calling agent and no credential is stored — see AAuth agent identity). Credentials are stored encrypted and never shown again— the UI only indicates whether an endpoint has one.
A registered Trinity instance with a bearer credential can also be named as the destination of a credential an agent asks a person for: the value is delivered to an agent on that instance under the stored key, and the key needs inject rights there. See Credential Management → Delivering a credential to another Trinity.
Endpoints registered on an agent's A2A tab before 1.0. Earlier builds had a register form on the agent's A2A tab. It wrote a separate per-agent list that call_a2a_agent never read, so those endpoints answered endpoint_not_found. The form is gone. If any such rows remain, the tab lists them as not callable with a Removebutton: re-add the ones you need in Settings › Integrations, then remove them from the tab.
Part 3 — Call an External A2A Agent (Outbound)
Your agents can task otherpeople's A2A agents — a Google ADK agent, a LangChain or Bedrock agent, or another Trinity instance — and get the answer back inside a single tool call.
Turn it on (admin, once)
Outbound calls are off by default. Enable them either way:
# .env, then restart
A2A_OUTBOUND_ENABLED=true…or flip it at runtime with no restart (the stored setting wins over the environment variable):
curl -X PUT http://localhost:8000/api/settings/a2a_outbound_enabled \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"value": "true"}'GET /api/settings/feature-flags reports a2a_outbound_available so you can confirm it took.
Once a stored setting exists it wins in both directions, and the environment variable is ignored until you clear the row with DELETE /api/settings/a2a_outbound_enabled. If .env says true and the feature still looks off, that stored row is why.
In the UI, the same switch is Allow outbound A2A calls on the Outbound A2A endpoints panel in Settings › Integrations (admin only); the panel reads Calls allowed or Calls off beside it, and warns that a registered endpoint cannot be called while the switch is off.
Register an endpoint (admin, human-only)
An agent cannot supply a URL. It picks a target by name from a list an administrator registered:
curl -X PUT http://localhost:8000/api/settings/a2a-endpoints \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{
"name": "research-partner",
"url": "https://partner.example.com/a2a/researcher",
"credentials": "their-api-token"
}'Registry rules worth knowing before your first attempt:
name updates that endpoint. Omitting credentials on an update keeps the stored secret; send "clear_credentials": true to remove it.422 — that is the single most common first-try failure."credential_kind": "payment_token" makes Trinity attach it as an x402 payment — the x402.payment.payload metadata plus the payment-signature header — in addition to the Authorization: Bearer header every credentialed call already carries, not instead of it. You can leave the field out: Trinity infers it from the value, so a token pasted straight from a paid provider works without you knowing the field exists. The response tells you which it concluded. Send credential_kind alone (no credentials) to re-label a secret you already stored, and note that it cannot be combined with clear_credentials — that pair is rejected with 422 rather than guessing which you meant."auth_scheme" is bearer (the default for a new endpoint) or aauth. An aauth endpoint holds no credential — sending one is refused with 422, and switching an existing endpoint to aauth drops the one it had — and its URL must be https:// on the default port, because the remote verifies the signed host against its own issuer, which carries no port. Omit the field on an update to keep the stored scheme: renaming or repointing an endpoint never silently turns an AAuth one into a bearer one. See AAuth agent identity.The Outbound A2A endpoints panel does the same from the browser. Its table shows each endpoint's Name, URL and Auth (Bearer · credential stored, Bearer · no credential or AAuth · signed as the agent) with Edit and Remove per row; the Register an endpoint form below it takes Name, A2A URL, Authentication (Bearer credential or AAuth (signed as the agent)) and, for bearer only, a Credential (leave it blank on an edit to keep the stored one). Editing a bearer endpoint over to AAuth warns that saving drops the stored credential; Remove asks for confirmation and deletes any stored credential with the endpoint.
# List them (credentials are never returned — only whether one is set)
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/settings/a2a-endpoints
# Remove one
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
http://localhost:8000/api/settings/a2a-endpoints/research-partnerThe URL must be HTTPS and must resolve to a public address; Trinity refuses anything pointing inside your network. It re-checks this on every call, not just at registration, so a hostname that later resolves somewhere internal stops working rather than being trusted because it was once accepted. The one exception is a host an admin has put on the outbound endpoint allowlist — see Between your own instances on a private network.
⚠ Registering an endpoint is a trust decision, not a configuration step. Trinity removes the literal credential from anything the remote sends back. It cannot stop a remote that base64-encodes, splits or otherwise transforms it — and an agent under prompt injection can be talked into asking for exactly that. Registering an endpoint grants that endpoint the ability to exfiltrate its own credential. Register peers you would trust with the token you are handing them.
Owning the agent is not enough. This registry is admin and human-only on every edition. The list is platform-wide, so registering an endpoint hands a credentialed egress target to everyagent on the instance — a fleet-wide grant rather than one agent's setting, and Trinity keeps grants human-only. An agent-scoped key is refused on all three operations.
The same three operations are available over MCP, so this is not a curl-only surface:
register_a2a_endpoint(name = "research-partner",
url = "https://partner.example.com/a2a/researcher",
credentials = "their-api-token",
# optional — inferred from the value when omitted;
# "payment_token" for an x402 token bought after a 402
credential_kind = "api_key",
# optional — "bearer" (default) or "aauth" (signed as the
# calling agent; no credentials allowed); omit to keep
auth_scheme = "bearer") # -> { endpoint, outbound_enabled }
list_a2a_endpoints() # -> { endpoints, outbound_enabled }
remove_a2a_endpoint(endpoint_id = "research-partner") # id or name; first match winsThey need an admin key held by a person, and they work whether or not the A2A capability is enabled. register_a2a_endpoint reports outbound_enabled: when it is false, the response also names the one admin step above that makes the endpoint callable — so a registration you cannot yet use says so instead of looking finished. agent_name is accepted and ignored.
When the remote charges for the call
Some A2A agents are priced. Such a remote answers 402 Payment Required, and Trinity passes that through as a 402 rather than as a generic failure:
{
"detail": {
"reason": "payment_required",
"message": "This agent charges 1 credit per request.",
"payment": {
"summary": {"plan_id": "plan_42", "scheme": "exact",
"network": "base-sepolia", "credits_per_request": 1,
"resource_url": "https://partner.example.com/a2a/researcher"},
"x402": { "…the remote's own requirements object…" },
"truncated": false
},
"remote_status": 402,
"task_id": "task-abc"
}
}An agent sees payment_required: true, the same payment block, and do_not_retry: true. Trinity never buys anything. The sequence is:
The agent relays the price to a person once and stops. Retrying cannot work, and calling a different endpoint is not a substitute.
A person buys the access token from the provider.
An admin stores it on the endpoint: register_a2a_endpoint(name="research-partner", url=…, credentials="<the token>") — the kind is inferred, or pass credential_kind="payment_token" explicitly.
The agent calls again, passing the task_id the refusal returned, so the remote resumes the same task instead of starting a fresh charge.
Two things worth knowing before you get there:
502 with reason: "rpc_forbidden" — or "payment_rejected" when the stored credential is a payment token the remote refused (spent, expired, or out of credit). Both carry remote_status, so you can always tell the two apart.credential_single_use: true, plus a hint in the registration response) rather than refusing it: after one paid call you will need to store a fresh token.Trinity reads the price and attaches a token you stored. It does not negotiate, does not purchase, and does not show the agent payment receipts.
Call it (from an agent)
call_a2a_agent(
agent_name = "my-agent",
endpoint = "research-partner", # the NAME you registered, not a URL
message = "Summarise the latest findings on X",
dedup_label = "research-step-1"
)dedup_label is required, and it must differ for each distinct question you ask in one turn. Calls are deduplicated on the endpoint and the conversation — never on the message text — so reusing a label returns the earlier answer instead of asking the new question.
If the remote replies with state: "working" or "submitted", it is still thinking. A Trinity remote answers this way for any turn longer than 25 seconds. The reply carries task_id. Poll it; never re-send the message, which would ask the question again:
get_a2a_task(agent_name="my-agent", endpoint="research-partner", task_id="<task_id from the call>")What comes back
| Field | Meaning |
|---|---|
| state | completed, working, submitted, failed, canceled, rejected, … (working/submitted = still running; poll task_id) |
| text | The remote's answer (capped at 32 KB, truncation marked) |
| task_id / context_id | Handles for polling or continuing the conversation |
| protocol_version | The A2A dialect negotiated from the remote's card |
| truncated | true when the reply exceeded the 32 KB response cap and was cut |
| endpoint | Which registered endpoint answered |
| replayed | true when this is a deduplicated replay of an earlier identical call, not a fresh answer |
Messages are capped at 100,000 characters on the way out.
Pass the current execution_id alongside dedup_label when you have one: together they make the call at-most-once even if the turn itself is re-delivered.
A few behaviors that surprise people, all deliberate: the calling agent's container does not need to be running (the backend places the call, not the container); read-only mode and the autonomy switch do not gate outbound calls; and an ephemeral agent's own key cannot place them at all.
Trinity → Trinity
Two ways, both over A2A v0.3 with no protocol configuration:
https://their-trinity.example.com/a2a/their-agent) with a Trinity MCP API key from that instance as the credential. The remote sees the call as whoever owns that key.aauth:<agent>@<your-host>), and the remote admits it only if that identity is on the target agent's inbound allow-list. Nothing is issued, stored or rotated on either side. See AAuth agent identity.Between your own instances on a private network
When your Trinity instances share a private network (a tailnet or a VPN) and serve plain HTTP on it, their agents can call each other over it instead of the public internet. Every call still carries a key: the private network only changes which addresses Trinity will call, never who may call an agent.
1. Allow the other instance's host (admin, on the calling instance).Add the provider instance's name on the network, its address range, or both, to the outbound endpoint allowlist:
curl -X PUT http://localhost:8000/api/settings/a2a-trusted-networks \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"entries": ["100.64.0.0/10", "*.your-tailnet.ts.net"]}'The platform refuses entries that would cover its own Docker networks, loopback, link-local or reserved ranges, or anything broader than a /8. The list is read only when this instance calls out; it never lets anyone call in.
2. Provider side: in the agent's A2A settings, turn on Expose over A2A, exactly as for any other caller.
3. Caller side: register http://<provider-instance>.<your-tailnet>/a2a/<agent> as an outbound endpoint, with a Trinity MCP API key from the provider instance as the credential (see Trinity → Trinity). Plain http:// and a private address are accepted only because the host is on the allowlist. The check runs again on every call, so a name that later resolves outside the allowed ranges is refused.
A call that arrives without a key gets 401, whichever network it comes from.
Troubleshooting
| Symptom | Cause |
|---|---|
| outbound_disabled (404) | A2A_OUTBOUND_ENABLED is off |
| endpoint_not_found (404) | No endpoint registered under that name — check spelling, or ask an admin |
| endpoint_not_https (400) | The registered URL is http:// and its host is not on the outbound endpoint allowlist. Re-register it as https:// — Trinity refuses rather than silently upgrading, so a credential never travels in clear — or, for one of your own instances on a private network, ask an admin to allow its host |
| endpoint_private_address (400) | The hostname resolves inside your network and is not on the outbound endpoint allowlist |
| card_origin_mismatch (502) | The remote's agent card points somewhere other than the registered host. Trinity refuses: a card cannot redirect a credentialed call |
| endpoint_dns_failure (400) | The hostname does not resolve. Trinity treats a DNS failure as fatal rather than retrying blindly |
| aauth_agent_only (403) | The endpoint uses the AAuth scheme and the caller is not the agent's own key. Only the agent itself may place a signed call — an owner, a shared user or an admin cannot make the backend sign as the agent |
| aauth_disabled (400) | The endpoint uses the AAuth scheme but AAuth is off, or has no valid issuer, on this instance. Turn it on in Settings › Integrations |
| rpc_forbidden (502) on an AAuth endpoint | The remote verified the signature but the calling agent's identity is not on the target agent's inbound allow-list there. Ask that instance's admin to add aauth:<agent>@<your-host> |
| card_url_ambiguous (502) | The remote's card declares a URL that doesn't unambiguously match what you registered. Register the origin, or a URL matching the card's declared url exactly |
| unsupported_protocol_version (502) | The remote speaks A2A 1.x, which Trinity deliberately refuses — there is no peer to verify that dialect against |
| payment_required (402) | The remote charges for this call. detail.payment carries its price and plan — relay it to a person once and stop; nothing an agent can do changes the answer |
| payment_rejected (502) | A payment token you stored was refused by the remote (spent, expired, or out of credit). Store a fresh one |
| rpc_forbidden (502) | The remote answered 403 for a reason of its own — check the credential and your access with that provider. Never Trinity's own 403 |
| message_too_long (422) | The message exceeds 100,000 characters |
| timeout (504) | The remote did not answer in time. If it accepted a task, poll with get_a2a_task. A Trinity remote answers a long turn with working + task_id instead of timing out |
| 409 | The same labelled call is already in flight — use a distinct dedup_label |
| 429 | Too many outbound calls: the limit is 30 per minute per agent and 120 per minute fleet-wide |
Timeouts, and what "it failed" actually means
A single call is bounded at 30 seconds for the remote's reply and 45 seconds wall-clock including the card fetch. The MCP tool gives up on its own side a little earlier (MCP_A2A_TIMEOUT_MS, 40 seconds by default) so it can hand the agent a structured receipt instead of an opaque network error.
A long turn on a Trinity remote is not a timeout. The remote answers working with a task_id after 25 seconds, well inside those bounds, and you poll get_a2a_task for the result. A timeout now means the remote (or the network to it) did not answer at all.
That receipt matters: a timed-out call_a2a_agent returns possibly_delivered: true. The remote may well have accepted and run the task. Do not simply re-send — poll with get_a2a_task if you have a task_id, or reuse the same dedup_label, which replays the earlier answer rather than paying for the work twice.
Behavior & Security Notes
404 (no way to enumerate which agents exist).401. The one exception is an exposed agent with payments on, where a caller with no Trinity key gets 402 instead so it can pay (see Charge for inbound A2A calls). A credential Trinity recognises and then refuses — a connector-scoped or ephemeral key — stays refused and never falls through to the paying path./a2a/ to the backend (nginx in production, the dev proxy locally). Set PUBLIC_CHAT_URL so the card's published url is reachable from outside your network.source=a2a, with the caller identity).Reference
Public routes (per exposed agent)
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /a2a/{agent}/.well-known/agent-card.json | none | Discovery card |
| POST | /a2a/{agent} | Bearer MCP key or an x402 payment (when the agent is priced) | JSON-RPC task endpoint |
Outbound routes (calling out)
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /api/agents/{agent}/a2a/call | Bearer (owner/shared; an agent key only as itself) | Task a registered external A2A agent |
| POST | /api/agents/{agent}/a2a/task | same | Poll a remote task by id |
| GET/PUT | /api/settings/a2a-endpoints | admin, human-only | List / register endpoints |
| DELETE | /api/settings/a2a-endpoints/{ref} | admin, human-only | Remove an endpoint — ref is its id or its name |
The two agent routes return 404 while outbound calling is off. The three settings routes are not gated by the flag: an admin can register endpoints before switching the feature on, which is the intended order. They are also the routes behind register_a2a_endpoint / list_a2a_endpoints / remove_a2a_endpoint, so the MCP tools and these routes cannot disagree.
GET /api/settings/a2a-endpoints answers {"endpoints": [{"id": …, "name": …, "url": …, "has_credentials": true, "credential_kind": "api_key"}], "enabled": false} — credentials are write-only and never echoed back, and enabled is a second way to confirm the flag. credential_kind appears only where a credential is stored (api_key or payment_token), with credential_single_use: true alongside it when the stored payment token is good for one settlement.
AAuth routes
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /.well-known/aauth-agent.json | none (404 unless AAuth is live) | Agent-provider metadata |
| GET | /.well-known/aauth-jwks.json | none (404 unless live) | This instance's public key set |
| GET | /.well-known/aauth-resource.json | none (404 unless live) | Resource metadata for the A2A task endpoint |
| POST | /a2a/{agent} | a Signature-Key-signed request (AAuth) or Bearer | The same task endpoint; a signed request takes the AAuth path |
| GET | /api/settings/aauth | admin | The switches, issuer, person server and resource allowlist, each with its source, plus live and the readiness checklist |
| PUT | /api/settings/aauth | admin, interactive only (no MCP key of any scope) | Change any of them; partial; 422 invalid_*; audited |
| POST | /api/agents/{agent}/aauth/person-token | the agent's own key | Prototype: obtain or resume a person-token binding (404 while the prototypes are off) |
| POST | /api/agents/{agent}/aauth/resource-call | the agent's own key | Prototype: call an allow-listed AAuth resource, or resume a pending call (404 while off) |
JSON-RPC methods
| Method | Purpose |
|---|---|
| message/send | Send a message, get a Task (the result, or working + id after 25 s; configuration.blocking overrides) |
| message/stream | Same, streamed over SSE |
| tasks/get | Fetch a task's current state |
| tasks/cancel | Cancel a running task |
JSON-RPC error codes
| Code | Meaning |
|---|---|
| -32700 | Parse error (body isn't valid JSON) |
| -32600 | Invalid request (not a JSON-RPC 2.0 envelope) |
| -32601 | Method not found |
| -32602 | Invalid params (e.g. no message text) |
| -32001 | Task not found |
Auth failures are transport-level 401; exposure/allow-list failures are 404/403. On a priced agent, an unpaid call is 402 and a rejected payment token is 403. An AAuth signature failure is a 401 carrying Signature-Error: error=<code> with a problem-details body; a verified AAuth identity that is not allow-listed is 403.
See Also
Trinity docs
External references