simple-agent/docs/a2a.md

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 + meeting intervals)

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 (default when action omitted)
• available_meeting_intervals:read (when action=available_meeting_intervals)

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:

• action: available_meeting_intervals to request interval suggestions (omit for default availability check)
• 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"]
    }
  }'

Meeting intervals:

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-2",
    "method":"SendMessage",
    "params":{
      "action":"available_meeting_intervals",
      "start":"2026-03-10T08:00:00+01:00",
      "end":"2026-03-10T18: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 required scope for the requested action

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