Why architecture matters here
Agent card architecture matters because the card is the first thing another agent sees. A clear, correct card leads to correct integrations; a vague or missing card leads to guessing and bugs. Cards are documentation with teeth — machine-readable and enforceable.
Cost is small but real. Cards must be maintained as agents evolve; stale cards cause silent breakage. Provisioning cards in CI alongside code prevents drift.
Reliability comes from signing and versioning. A signed card proves it came from the claimed provider; versioning lets consumers pin known-good versions and evolve gracefully.
The architecture: every field explained
Walk the diagram top to bottom.
Agent Owner. The organization or team that runs an A2A agent. Responsible for publishing and maintaining the card.
Well-Known URL. By convention, /.well-known/agent.json. Discovery starts here.
Discovery. Consumers fetch the card, cache it (with TTL), and consult it before every session.
Card Contents. Name, description, contact, terms URL, capabilities. Human-readable and machine-readable together.
Auth Requirements. Required auth mechanism (OAuth 2.0, mTLS, JWT), specific scopes, and any provisioning URL for tokens.
Skills / Tools. Named capabilities with typed JSON schemas for inputs and outputs. Descriptions in natural language so an LLM can pick the right one.
Endpoints. Service base URL and transport (HTTPS + JSON-RPC, SSE, gRPC). Consumers know exactly where to send.
Versioning. Semantic version + compatibility metadata. Consumers can pin or accept ranges.
Signing. Card signed with the provider's key. Consumers verify signature against a trusted registry or DNS-based key discovery.
Registry. Public agent catalogs (or private within an org) list cards for discovery. Registries add reputation, ratings, and safety flags.
End-to-end discovery flow
Trace a discovery. Agent A needs a translation capability. It consults its registry with intent "translation." Registry returns candidate agents including Agent B.
Agent A fetches https://agentb.example.com/.well-known/agent.json. Card returned. Agent A verifies signature against known key.
Card lists: - Name: TranslateAgent - Version: 2.4.1 - Skills: [{ name: "translate", inputs: { text: "string", target_lang: "string" }, outputs: { translated: "string" } }, { name: "detect_language", ... }] - Auth: OAuth 2.0, scope "translate:invoke" - Endpoint: https://agentb.example.com/a2a - Contact: ops@agentb.example.com - Terms: https://agentb.example.com/terms
Agent A checks: does version 2.4.1 satisfy my range? Yes. Do I have the OAuth scope? Yes.
Agent A opens an A2A session at the endpoint. Auth handshake with the scoped token. Session initialized. Agent A invokes translate skill with valid inputs. Response returns.
Ten days later Agent B publishes 3.0.0 with a breaking change. Agent A's card cache expires; new card fetched. Version 3.0.0 doesn't satisfy A's pinned range (^2.4). Agent A stays on the 2.4.x endpoint (provider maintains for grace period) or updates its integration.