A2A Agent Card Kit: v1.0 Validator, Migrator, Templates + Test Agent

Everything for publishing an A2A agent under A2A Protocol v1.0: a spec-level Agent Card validator, a v0.3 -> v1.0 migrator, a card generator, 8 ready card templates, a reference JSON-RPC agent and a live endpoint checker. Python 3.9+, standard library only, works offline.

• tools/a2a_card.py, a single CLI: - validate CARD.json|URL: every required field, interface (protocolBinding, Major.Minor protocolVersion, URL), capabilities, media types, skills (duplicate ids, tags, examples), all 5 security scheme kinds, one OAuth flow per scheme, required flow URLs, scopes used vs declared, requirements that point at undefined schemes, signatures (JWS header structure), and unknown fields. v0.3 leftovers get a precise "move X to Y" message. --json for CI, --strict fails on warnings too. - migrate OLD.json -o NEW.json: converts a v0.3 card (url / preferredTransport / additionalInterfaces, top-level protocolVersion, supportsAuthenticatedExtendedCard, OpenAPI-style securitySchemes, security) to v1.0 and splits multi-flow OAuth schemes. --protocol-version 0.3 keeps declaring 0.3 if your server hasn't moved yet. - migrate-message OLD.json: v0.3 messages and streaming events (kind, role: "user", "input-required", final) to v1.0 shapes. - new ...: generates a valid card with --auth none|apikey|bearer|oauth2-cc|oauth2-code|oidc|mtls, skills, streaming, extended card, extra HTTP+JSON / gRPC interfaces and an optional 0.3 compatibility interface. - check URL [--send TEXT]: live test of a deployed agent: card endpoint status, Content-Type, Cache-Control and ETag, a conditional request (304), card validation, then over JSON-RPC: version negotiation (-32009), SendMessage result shape, TASK_STATE_* enums, no kind in parts, GetTask history handling and TaskNotFound (-32001). - serve: a reference v1.0 JSON-RPC agent (echo skill) for local testing or as a skeleton.
• a2a_card/server.py: the reference agent as a module. It covers SendMessage, SendStreamingMessage (SSE), GetTask, ListTasks (cursor pagination, includeArtifacts, historyLength), CancelTask, SubscribeToTask and GetExtendedAgentCard, plus the A2A-Version check, spec error codes with @type details, optional bearer auth and the well-known card with ETag. Replace handle_message() with your logic.
• templates/: 8 cards (public, API key, bearer JWT, OAuth2 client credentials, OAuth2 code + PKCE, OIDC + extended card (both files), multi-interface with a 0.3 compatibility entry). All of them validate with 0 warnings.
• examples/: a broken card (13 errors), a real-looking v0.3 card, and a v0.3 message and status event.
• docs/v03-to-v10.md: every card and wire change in two tables, plus versioning and error codes.

./tools/demo.sh

python3 tools/a2a_card.py validate agent-card.json
python3 tools/a2a_card.py validate https://your-agent.example.com          # fetches /.well-known/agent-card.json
python3 tools/a2a_card.py validate agent-card.json --json --strict          # CI

python3 tools/a2a_card.py migrate old-card.json -o agent-card.json
python3 tools/a2a_card.py validate agent-card.json

The migrator prints a note for every change. Upgrading the card does not upgrade your server: a 1.0 interface means PascalCase methods, parts without kind, and ROLE_* / TASK_STATE_* enums. Until your server speaks 1.0, keep a protocolVersion: "0.3" interface.

python3 tools/a2a_card.py new --name "Billing Agent" --description "Looks up invoices." \
  --url https://billing.example.com/a2a/v1 --auth oauth2-cc --org "Example Co" \
  --skill "invoice-lookup:Invoice lookup:Returns invoice status and totals for an invoice id." -o agent-card.json

Serve the result at https://<host>/.well-known/agent-card.json with Content-Type: application/json, a Cache-Control: max-age and an ETag.

python3 tools/a2a_card.py check https://your-agent.example.com --send "hello"
A2A_BEARER_TOKEN=... python3 tools/a2a_card.py check https://your-agent.example.com --send   # token from env, never in a file

python3 tools/a2a_card.py serve --port 8765                       # echo agent with a generated card
python3 tools/a2a_card.py serve --card my-card.json --extended my-extended.json
A2A_BEARER_TOKEN=change-me python3 tools/a2a_card.py serve        # every RPC needs the bearer token

./run_tests.sh runs 22 tests (Python 3.9+, offline). They cover all templates and every auth option at 0 errors; every finding in the broken example; v0.3 detection; migration of the card, messages and events; the CLI exit codes; and a real HTTP server on a free port: card ETag/304, send/get/list/cancel, pagination, input-required, the error codes (-32001, -32002, -32003, -32005, -32009, -32601, -32602), SSE streaming, the extended card, bearer auth and the live check command.

• Signatures: the validator checks structure and the JWS header (alg, kid/jku/jwk) but does not verify the signature. That needs RFC 8785 canonicalization and a crypto library.
• check and the reference server speak the JSON-RPC binding. gRPC and HTTP+JSON interfaces are validated in the card but not called.
• The reference server keeps tasks in memory and does not implement push notifications (it returns -32003). It is a test double and skeleton, not production infrastructure.
• Written against the A2A v1.0 specification as published on a2a-protocol.org in November 2026.