A2A Protocol

Using the web UI

Open the agent's detail page and select the A2A tab.

1

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.

2

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.

3

Review the advertised skills — exactly what an external caller sees on the card (derived from the agent's template.yaml capabilities).

4

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.

5

Register outbound endpoints (optional) — external A2A endpoints your agent may call, with credentials stored encrypted (never shown again).

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:

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.

1. Discover — fetch the Agent Card

curl -s http://localhost:8001/a2a/new_cool_agent/.well-known/agent-card.json | jq

{
  "protocolVersion": "0.3.0",
  "name": "new_cool_agent",
  "url": "http://localhost:8001/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_….

3. Task — JSON-RPC 2.0

Synchronous (message/send):

curl -s -X POST http://localhost:8001/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." }]
    }}
  }' | jq

Returns an A2A Task:

{ "jsonrpc": "2.0", "id": 1, "result": {
  "id": "zAS45ahu2fwsHG9rwdKxQQ", "kind": "task",
  "status": { "state": "completed" },
  "artifacts": [{ "parts": [{ "kind": "text", "text": "…the answer…" }] }]
}}

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

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:

# 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-partner

The 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.

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. Poll it:

get_a2a_task(agent_name="my-agent", endpoint="research-partner", task_id="<task_id from the call>")

What comes back

Trinity → Trinity

Register the remote instance's agent endpoint (https://their-trinity.example.com/a2a/their-agent) with a Trinity MCP API key from that instance as the credential. Both sides speak A2A v0.3, so it works with no extra configuration.

Troubleshooting

Timeouts, and what "it failed" actually means

Public routes (per exposed agent)

Outbound routes (calling out)

JSON-RPC methods

JSON-RPC error codes

Auth failures are transport-level 401; exposure/allow-list failures are 404/403.