Protocol interoperability runbook

Surfaces

• collabrc.ai 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.