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

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

Availability:

```bash
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:

```bash
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