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.
108 lines
2.2 KiB
Markdown
108 lines
2.2 KiB
Markdown
# 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:
|
|
|
|
```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"]
|
|
}
|
|
}'
|
|
```
|
|
|
|
## 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
|
|
|