You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

2.2 KiB

Raw Blame History

A2A Runbook

Scope

This runbook covers the Agent-to-Agent (A2A) adapter exposed by the REST service in app.main.

Endpoints

Agent Card: GET /.well-known/agent-card.json
RPC endpoint: POST /a2a/rpc

When using Docker Compose:

Base URL: http://127.0.0.1:8000

Protocol contract

protocolVersion advertised in Agent Card: 1.0
Response header on A2A routes: A2A-Version: 1.0
JSON-RPC version: 2.0

Implemented methods:

ping / health.ping / health/ping
SendMessage (availability only)

Authentication

The A2A adapter uses the same auth backend as REST:

AUTH_MODE=api_key: X-API-Key or Authorization: Bearer <AGENT_API_KEY>
AUTH_MODE=jwt: Authorization: Bearer <JWT>
AUTH_MODE=hybrid: API key first, then JWT

Required scope for SendMessage:

availability:read

Request shape for SendMessage

SendMessage accepts several input shapes; the request must contain at least:

start ISO datetime with timezone offset
end ISO datetime with timezone offset

Accepted locations:

params.start / params.end
params.input.start / params.input.end
params.arguments.start / params.arguments.end
JSON embedded in message content

Optional:

calendar_ids: array of calendar ids (defaults to ["primary"])

Smoke tests

Agent Card:

curl http://127.0.0.1:8000/.well-known/agent-card.json

Availability:

curl -X POST "http://127.0.0.1:8000/a2a/rpc" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AGENT_API_KEY" \
  -d '{
    "jsonrpc":"2.0",
    "id":"req-1",
    "method":"SendMessage",
    "params":{
      "start":"2026-03-10T09:00:00+01:00",
      "end":"2026-03-10T10:00:00+01:00",
      "calendar_ids":["primary"]
    }
  }'

Error mapping

-32600: invalid JSON-RPC request
-32601: unknown method
-32602: invalid params (including bad time window)
-32001: unauthorized
-32000: backend/runtime error

Troubleshooting

If you get -32001:

Verify AUTH_MODE
Verify API key/JWT and scope availability:read

If you get -32602:

Ensure start and end include timezone offsets
Ensure end > start

If you get -32000 with OAuth file errors:

Check GOOGLE_CLIENT_SECRETS_FILE path
Check GOOGLE_TOKEN_FILE path

2.2 KiB Raw Blame History