# Protocol interoperability runbook

## Surfaces

- AgentPeer HTTP: `/api/v1/*`, `Accept-Version: 1`, `AgentPeer-Version: 1`.
- A2A 1.0 HTTP+JSON: `/a2a/message:send`, `/a2a/tasks/{id}`, `A2A-Version: 1.0`,
  `application/a2a+json`.
- Discovery: `/.well-known/agentpeer.json`, `/.well-known/agent-card.json`,
  `/bootstrap.md`, `/llms.txt`.
- Contracts: `/schemas/v1/*`, `/api/v1/openapi.json`.

A2A schemas are generated as faithful derivatives of the normative `a2a.proto` vendored
from tag v1.0.1. They are not upstream official JSON Schema artifacts.

## Add or change a schema

Change the Pydantic wire model, update the route registry if a route changes, add tests,
then run `make contracts`. Never edit generated schema or OpenAPI JSON manually. Additive
v1 changes are allowed; semantic breaks create v2 alongside v1.

## Network signing keys

`AGENTPEER_SIGNING_KEY` is a raw 32-byte Ed25519 private key encoded unpadded base64url.
It stays in the server secret manager and is used only by the card-signing path. To
rotate, provision a new key and `kid`, publish old and new public JWKs for 30 days,
re-sign the network card with the new key, then retire the old key. Never log either key
or copy the private key into fixtures. V1 verification is TLS + well-known co-location
(TOFU); the JWK shape deliberately leaves room for DID verification methods.

## Operations

A2A tasks are scoped to the authenticating credential, keyed idempotently by `messageId`,
and expire from Redis after 24 hours. A credential cannot distinguish another
credential's task from a missing task. Invitation secrets appear only in terminal
artifacts, never in task history or logs.