--- description: "A2A agent card reference for v1.0: every schema field, three valid JSON examples, the well-known agent-card.json path, signatures, and discovery." title: "A2A Agent Card Explained: Schema, JSON Examples and Discovery" image: https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w1200/2026/10/a2a-agent-card-explained-schema-json-examples-and-discovery-bifrost-1920x1080.png --- Try Bifrost Enterprise free for 14 days. [Request access](https://www.getmaxim.ai/#enterprise-trial) **TL;DR** - An A2A agent card is the JSON document every A2A server publishes to describe its identity, endpoints, capabilities, skills, and authentication. - In A2A v1.0 the card is served at `/.well-known/agent-card.json`, and endpoints live in an ordered `supportedInterfaces` array whose entries carry `url`, `protocolBinding`, and `protocolVersion`. - v1.0 removed the top-level `url`, `preferredTransport`, and `protocolVersion` fields and moved the extended card flag into `capabilities`. - Bifrost registers an agent by its full card URL, serves a rewritten card with gateway endpoints and gateway authentication, strips upstream signatures, and uses card order to pick the upstream transport. An A2A agent card is the discovery document an [Agent2Agent (A2A)](https://a2a-protocol.org/latest/specification/) server publishes so other agents can find it, judge whether it fits a task, and learn how to call it. [Bifrost](https://www.getmaxim.ai/), the [open-source AI gateway](https://github.com/maximhq/bifrost) built by Maxim AI, reads agent cards to register A2A agents and serves its own rewritten card to callers. This reference covers the v1.0 schema, three annotated JSON examples, the extended card, signatures, discovery patterns, common mistakes, and what changes behind a gateway. ## What Is an A2A Agent Card? An A2A agent card is a self-describing JSON manifest for an agent. It states the agent's identity, the interfaces where it accepts requests, its optional features, media types, skills, and the security schemes a client must satisfy. The A2A specification requires every server to publish one. A client agent uses the card for three decisions in order: whether the agent can do the job (skills and modes), how to prove identity (security schemes), and where to send the request (the first supported interface). For the rest of the protocol, see [how A2A traffic runs through a gateway](https://www.getmaxim.ai/articles/a2a-protocol-gateway/). ![A client agent fetches the A2A agent card from the well-known URL, matches skills, authenticates with a declared scheme, then calls the first supported interface](https://articles-images-cdn.t3.tigrisfiles.io/diagrams/a2a-agent-card/a2a-agent-card-discovery-flow.png) *Figure 1: The card drives every later choice a client makes: which agent, which credential, which endpoint.* The card carries no task state or credentials. Those belong to [messages, tasks, and contexts](https://docs.getbifrost.ai/features/agent-gateway/messages-and-tasks), which start after discovery and which the [Agent Gateway in Bifrost](https://docs.getbifrost.ai/features/agent-gateway/overview) records per session. ## Where the Agent Card Is Served: The Well-Known Path The A2A v1.0 agent card is served at `https://{agent-server-domain}/.well-known/agent-card.json`, following the well-known URI convention in [RFC 8615](https://www.rfc-editor.org/rfc/rfc8615). A client sends an HTTP GET and receives JSON; the spec includes an IANA registration template for this URI. A2A v0.2.5 used `/.well-known/agent.json`; v0.3.0 renamed it to `agent-card.json`. A server answering only on `agent.json` is not found by clients that follow the current spec. Card endpoints should send `Cache-Control` and an `ETag` so clients can revalidate with `If-None-Match`. [Registering an agent in Bifrost](https://docs.getbifrost.ai/features/agent-gateway/registration) requires the complete card URL, such as `https://research.example.com/.well-known/agent-card.json`; the base URL alone is not enough. ## A2A Agent Card Schema: Every Important Field The A2A agent card schema in v1.0 has eight required top-level fields: `name`, `description`, `supportedInterfaces`, `version`, `capabilities`, `defaultInputModes`, `defaultOutputModes`, and `skills`. Provider, security, documentation, icon, and signature fields are optional. JSON field names are camelCase. | Field | Required | What it holds | | --- | --- | --- | | `name`, `description` | Yes | Human-readable identity and purpose | | `supportedInterfaces` | Yes | Ordered endpoints; the first entry is preferred | | `version` | Yes | The agent's own version, such as `1.2.0` | | `capabilities` | Yes | `streaming`, `pushNotifications`, `extensions`, `extendedAgentCard` | | `defaultInputModes`, `defaultOutputModes` | Yes | Media types accepted and returned | | `skills` | Yes | Each with `id`, `name`, `description`, `tags` | | `provider` | No | Publisher `organization` and `url` | | `securitySchemes` | No | Named schemes: API key, HTTP auth, OAuth 2.0, OpenID Connect, mTLS | | `securityRequirements` | No | Which schemes and scopes a client must satisfy | | `signatures` | No | JWS signatures over the canonical card | Each interface requires `url`, `protocolBinding` (`JSONRPC`, `GRPC`, or `HTTP+JSON`), and `protocolVersion`, plus an optional `tenant`. Skills can override default modes and declare their own `securityRequirements`. Each `securitySchemes` value wraps exactly one type, such as `httpAuthSecurityScheme`, and [agent authentication through Bifrost](https://docs.getbifrost.ai/features/agent-gateway/authentication) reads these declarations to choose which credential fields to request. ## A2A Agent Card Examples in JSON The three examples below are valid JSON matching the A2A v1.0 schema: a minimal card, a card with authentication and two skills, and a card advertising three transports with a signature. All describe the same research agent. ### Minimal public agent card ```json { "name": "Library Research Agent", "description": "Answers questions about software libraries and APIs.", "supportedInterfaces": [ {"url": "", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"} ], "version": "1.0.0", "capabilities": {}, "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"], "skills": [ {"id": "library-lookup", "name": "Library lookup", "description": "Explains how to use a library API.", "tags": ["libraries"]} ] } ``` `capabilities` is required but its fields are optional, so `{}` declares no streaming, push, or extended card. With no `securitySchemes`, the agent accepts unauthenticated requests. A [Bifrost registration preview](https://docs.getbifrost.ai/features/agent-gateway/registration#register-in-the-dashboard) shows these skills, interfaces, and capabilities before you save. ### Agent card with security schemes and skills ```json { "name": "Library Research Agent", "description": "Answers questions about software libraries and APIs.", "supportedInterfaces": [ {"url": "", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"} ], "provider": {"organization": "Example Platform Team", "url": ""}, "version": "1.2.0", "capabilities": {"streaming": true, "pushNotifications": true, "extendedAgentCard": true}, "securitySchemes": { "agentBearer": {"httpAuthSecurityScheme": {"scheme": "Bearer", "bearerFormat": "JWT"}}, "agentOAuth": { "oauth2SecurityScheme": { "flows": { "clientCredentials": { "tokenUrl": "", "scopes": {"research.read": "Ask questions", "research.reports": "Generate reports"} } } } } }, "securityRequirements": [ {"schemes": {"agentBearer": {"list": []}}}, {"schemes": {"agentOAuth": {"list": ["research.read"]}}} ], "defaultInputModes": ["text/plain", "application/json"], "defaultOutputModes": ["text/plain", "application/json"], "skills": [ { "id": "library-lookup", "name": "Library lookup", "description": "Explains how to use a library API.", "tags": ["libraries"], "examples": ["How do I reuse one HTTP client in Go?"] }, { "id": "compatibility-report", "name": "Compatibility report", "description": "Compares two versions of a dependency.", "tags": ["dependencies", "reports"], "outputModes": ["text/markdown"], "securityRequirements": [{"schemes": {"agentOAuth": {"list": ["research.reports"]}}}] } ] } ``` Following OpenAPI convention, the two top-level `securityRequirements` entries are alternatives: a bearer token, or an OAuth token with `research.read`. Schemes inside one `schemes` object must all be satisfied. ### Agent card advertising multiple transports ```json { "name": "Library Research Agent", "description": "Answers questions about software libraries and APIs.", "supportedInterfaces": [ {"url": "", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}, {"url": "research.example.com:443", "protocolBinding": "GRPC", "protocolVersion": "1.0"}, {"url": "", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0"} ], "version": "1.2.0", "capabilities": {"streaming": true}, "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"], "skills": [ {"id": "library-lookup", "name": "Library lookup", "description": "Explains how to use a library API.", "tags": ["libraries"]} ], "signatures": [ { "protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJyZXNlYXJjaC1jYXJkLTIwMjYiLCJqa3UiOiJodHRwczovL3Jlc2VhcmNoLmV4YW1wbGUuY29tLy53ZWxsLWtub3duL2p3a3MuanNvbiJ9", "signature": "REPLACE_WITH_BASE64URL_ES256_SIGNATURE" } ] } ``` Interface order is preference order. The gRPC `url` is a bare `host:port`, as the spec requires. The `signature` value is a placeholder for your key's output. ## The Authenticated Extended Agent Card The authenticated extended card is a more detailed card an agent returns only to authenticated clients. The public card advertises it with `capabilities.extendedAgentCard: true`, and clients call `GetExtendedAgentCard` after authenticating with a scheme the public card declares. If the flag is absent, the call must return `UnsupportedOperationError`; if it is set but no extended card exists, `ExtendedAgentCardNotConfiguredError`. The v0.3 field `supportsAuthenticatedExtendedCard` is gone. [Agent Logs](https://docs.getbifrost.ai/features/agent-gateway/observability) in Bifrost record `GetAgentCard` and `GetExtendedAgentCard` separately, so teams can audit who fetched the detailed card. ## Agent Card Signatures A card signature is a JSON Web Signature (JWS) that lets a client verify the card is unaltered and came from the claimed provider. Each entry in the optional `signatures` array carries a base64url `protected` header, a `signature`, and an optional `header`. To sign, remove fields set to default values, exclude `signatures`, canonicalize with the JSON Canonicalization Scheme in [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785), and sign with the algorithm in the protected header, which must include `alg`, `typ`, and `kid` and may include `jku`. Verifiers repeat the canonicalization; multiple signatures support key rotation. Any intermediary that edits the card invalidates its signature, so [governance at the agent layer](https://www.getmaxim.ai/resources/governance) needs a clear rule for which card a client trusts. ## Agent Discovery Patterns: Well-Known URL, Registries, Direct Config A2A defines three ways to find a card: fetching the well-known URI on the agent's domain, querying a curated registry, or reading a URL from direct configuration. All three end in the same JSON document. ![Agent discovery through a well-known URI, a curated registry, or direct configuration all resolve to one A2A agent card that the client agent parses](https://articles-images-cdn.t3.tigrisfiles.io/diagrams/a2a-agent-card/a2a-agent-card-discovery-patterns.png) *Figure 2: Discovery patterns differ only in how the client finds the card; the card itself is the same document.* | Pattern | How the client finds the card | Fits | | --- | --- | --- | | Well-known URI | GET `/.well-known/agent-card.json` | Public or domain-scoped agents | | Curated registry | Query by skill, tag, or provider | Enterprise catalogs, marketplaces | | Direct configuration | URL in config or environment | Private agents, development | The [A2A agent discovery guide](https://a2a-protocol.org/latest/topics/agent-discovery/) notes that no standard registry API exists yet. A gateway that serves registered cards behind access control works as a governed catalog: callers reach only agents their [virtual keys](https://docs.getbifrost.ai/features/governance/virtual-keys) are granted, a role covered in [choosing an agent gateway](https://www.getmaxim.ai/articles/how-to-choose-an-agent-gateway/). ## Common Agent Card Mistakes Most card failures come from v0.3 to v1.0 drift, unreachable endpoints, or sensitive data in a public document. These mistakes most often break discovery or registration. | Mistake | What breaks | Fix | | --- | --- | --- | | Top-level `url` or `preferredTransport` | v1.0 clients find no interfaces | Use `supportedInterfaces[]` | | Card-level `protocolVersion` | Version not read per interface | Set it on each interface | | Card only at `agent.json` | Current clients get 404 | Serve `agent-card.json` | | gRPC `url` with a path | Endpoint rejected | Use `host:port` | | Static secrets or internal hosts | Credential or topology exposure | Out-of-band credentials, extended card | | Interfaces on separate task stores | `GetTask` misses the task | Share one task store | The last row matters when a gateway switches transports: [transport recovery in Bifrost](https://docs.getbifrost.ai/features/agent-gateway/transports-and-recovery) does not copy task state between endpoints. An unapproved runtime origin is another frequent [agent registration error](https://docs.getbifrost.ai/features/agent-gateway/troubleshooting). ## How Bifrost Serves a Rewritten Agent Card [Bifrost, the AI gateway](https://www.getmaxim.ai/), registers an A2A agent from its full card URL and serves its own card to callers. On each request to the gateway card URL, Bifrost fetches the current upstream card, rewrites its interfaces to gateway endpoints and its authentication to gateway authentication, removes upstream signatures, and returns the result. ![Bifrost fetches the upstream A2A agent card on each request, rewrites interfaces to gateway endpoints and gateway auth, removes signatures, and serves the result](https://articles-images-cdn.t3.tigrisfiles.io/diagrams/a2a-agent-card/a2a-agent-card-bifrost-rewrite.png) *Figure 3: Clients discover gateway routes, never the agent server's own addresses or credentials.* - **Separate credentials.** Card fetch options authenticate only the card request; [request authentication](https://docs.getbifrost.ai/features/agent-gateway/authentication#additional-agent-endpoints) is pre-selected from the card's requirements, with a manual override. - **Origin checks.** The card's origin is permitted automatically; runtime endpoints on other origins need approval, and private addresses need the Private Network Allowlist. - **Gateway card URL.** Clients use `/agents/a2a/{name}/.well-known/agent-card.json`, which needs the [External Client URL](https://docs.getbifrost.ai/features/agent-gateway/configuration) set; otherwise it returns 503. - **No stale copy.** The served card is fetched live; if the upstream fetch fails, the client gets an error. Signatures are removed because the rewrite invalidates them; the registration preview still shows the originals. [Agent access grants](https://docs.getbifrost.ai/features/agent-gateway/access-control) control who can call the agent, as part of [AI governance in Bifrost](https://www.getmaxim.ai/ai-governance); an agent grant does not authorize the agent's own model or tool calls. The [Agent Gateway launch post](https://www.getmaxim.ai/bifrost/blog/introducing-agent-gateway-in-bifrost-one-gateway-for-models-tools-and-agents) covers the design. ## How Card Order Sets the Upstream Transport In Bifrost, the order of `supportedInterfaces` in the upstream agent card sets the initial transport preference. Bifrost keeps interfaces with a supported A2A v1 version, binding (`JSONRPC`, `HTTP+JSON`, or `GRPC`), and valid endpoint, orders them by protocol version, and preserves card order among equal versions. ![Bifrost filters supportedInterfaces to eligible A2A v1 entries, keeps card order, tries the first interface, and advances only on unreached or unsupported endpoints](https://articles-images-cdn.t3.tigrisfiles.io/diagrams/a2a-agent-card/a2a-agent-card-transport-order.png) *Figure 4: Put the preferred interface first; Bifrost retries on another interface only when the endpoint was not reached or cannot serve the operation.* No rule prefers gRPC or matches the caller's transport; to change preference, edit the upstream card. Failover follows the card: - A dial failure, HTTP `404`, `405`, `410`, `426`, method-not-found, or gRPC `Unimplemented` tries the next candidate. - HTTP `5xx` or an ambiguous failure returns the error without replay, since a task may have started. - Streaming operations are never replayed automatically. - Statuses suggesting a stale address trigger a throttled background card refresh. For the wider architecture, compare [an agent gateway with an LLM gateway](https://www.getmaxim.ai/articles/agent-gateway-vs-llm-gateway/) and review [enterprise agent gateway criteria](https://www.getmaxim.ai/articles/enterprise-agent-gateway/). ## Frequently Asked Questions ### What is an agent card in A2A? An agent card is the JSON discovery document every A2A server must publish. It lists the agent's name, description, version, ordered interfaces, optional capabilities, media types, skills, and security schemes. Clients read it before sending any [A2A message or task](https://www.getmaxim.ai/articles/a2a-protocol-gateway/). ### Where is the A2A agent card located? In A2A v1.0 the agent card lives at `https://{domain}/.well-known/agent-card.json`, under the RFC 8615 well-known URI convention. Clients can also use a registry or a configured URL. Bifrost serves a rewritten card at its own [gateway endpoint](https://docs.getbifrost.ai/features/agent-gateway/configuration#copy-the-client-facing-endpoints), such as `/agents/a2a/{name}/.well-known/agent-card.json`. ### What is the difference between agent.json and agent-card.json? `/.well-known/agent.json` is the path from A2A v0.2.5. Version 0.3.0 renamed it to `/.well-known/agent-card.json`, and v1.0 keeps that path. Servers should serve `agent-card.json`. ### What fields are required in an A2A agent card? A v1.0 agent card requires `name`, `description`, `supportedInterfaces`, `version`, `capabilities`, `defaultInputModes`, `defaultOutputModes`, and `skills`. Each interface requires `url`, `protocolBinding`, and `protocolVersion`, and each skill requires `id`, `name`, `description`, and `tags`. Provider, security schemes, documentation URL, icon, and signatures are optional. ### Should an agent card contain API keys or secrets? No. The card declares which authentication schemes an agent accepts, never the credentials. The A2A specification recommends out-of-band dynamic credentials over static secrets. Sensitive skills or internal endpoints belong in the authenticated extended card or behind access control on the card endpoint, using mTLS, network restrictions, or OAuth. ### Why does a gateway-served agent card have no signatures? A gateway that rewrites endpoints and authentication changes the signed content, so the upstream JWS no longer verifies. Bifrost removes the original signatures instead of serving signatures that would fail. The upstream signatures stay visible in the registration preview, and raw HTTP capture can preserve the original document when enabled. ## Getting Started with Agent Cards in Bifrost A correct A2A agent card uses v1.0 fields, the right well-known path, ordered interfaces that share task state, and no secrets. Bifrost then registers the agent, serves a gateway card behind access controls, and logs agent traffic next to model calls and the tool calls that run through the [MCP gateway](https://www.getmaxim.ai/mcp-gateway). Start with [agent registration](https://docs.getbifrost.ai/features/agent-gateway/registration#make-your-first-request), then [book a demo](https://www.getmaxim.ai/book-a-demo) to see how Bifrost governs agent cards and A2A traffic for enterprise teams. ## Read next [![AI Agent Registry: How Teams Discover and Govern Internal Agents](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/ai-agent-registry-how-teams-discover-and-govern-internal-age-bifrost-1920x1080.png) An AI agent registry is the system of record for the agents a company runs, from identity and skills to endpoints, auth and who may call them. This guide covers discovery models, a field checklist, how it differs from an MCP registry, and how Bifrost governs registered A2A agents.](https://www.getmaxim.ai/articles/ai-agent-registry/) [![Agent Communication Protocols Compared: A2A, MCP and ACP](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/agent-communication-protocols-compared-a2a-mcp-and-acp-bifrost-1920x1080.png) An agent communication protocol defines how AI agents talk to tools, to other agents, and to users. This guide compares MCP, A2A and ACP, explains what happened to ACP, covers AG-UI and AP2, and shows how to govern them in production.](https://www.getmaxim.ai/articles/agent-communication-protocols/) [![A2A vs MCP: Differences, When to Use Each, and How to Run Both](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/a2a-vs-mcp-differences-when-to-use-each-and-how-to-run-both-bifrost-1920x1080.png) A2A vs MCP is a question of direction: MCP connects an agent to its tools and data, while A2A connects independent agents to each other. This guide compares their message models, transports, auth, discovery and task handling, and shows how to govern both at one gateway.](https://www.getmaxim.ai/articles/a2a-vs-mcp-2/) ## More in Agent Gateway [![Agentic Mesh vs Agent Gateway: Multi-Agent Architecture](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/agentic-mesh-vs-agent-gateway-multi-agent-architecture-bifrost-1920x1080.png) An agentic mesh is a distributed architecture in which many AI agents discover and call each other under shared governance. This guide compares the mesh with the agent gateway pattern, covers hybrid designs, and gives a decision table for platform teams.](https://www.getmaxim.ai/articles/agentic-mesh-vs-agent-gateway/) [![AI Agent Orchestration vs Agent Gateway: Where Each Layer Fits](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/ai-agent-orchestration-vs-agent-gateway-where-each-layer-fit-bifrost-1920x1080.png) AI agent orchestration coordinates which agent runs, in what order and on what input, while an agent gateway governs the model, tool and agent calls that plan produces. This guide compares the two layers, the main orchestration patterns, and how Bifrost sits under any orchestrator.](https://www.getmaxim.ai/articles/ai-agent-orchestration-vs-agent-gateway/) ```json { "@context": "https://schema.org", "@type": "Article", "publisher": { "@type": "Organization", "name": "Maxim Articles", "url": "https://www.getmaxim.ai/articles/", "logo": { "@type": "ImageObject", "url": "https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w256h256/2025/08/thumbnail.png", "width": 60, "height": 60 } }, "author": { "@type": "Person", "name": "Kuldeep Paul", "image": { "@type": "ImageObject", "url": "https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/2025/08/1727978381919.jpeg", "width": 800, "height": 800 }, "url": "https://www.getmaxim.ai/articles/author/kuldeep/", "sameAs": [] }, "headline": "A2A Agent Card Explained: Schema, JSON Examples and Discovery", "url": "https://www.getmaxim.ai/articles/a2a-agent-card/", "datePublished": "2026-10-28T19:06:00.000Z", "dateModified": "2026-10-29T19:07:02.000Z", "image": { "@type": "ImageObject", "url": "https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w1200/2026/10/a2a-agent-card-explained-schema-json-examples-and-discovery-bifrost-1920x1080.png", "width": 1200, "height": 675 }, "keywords": "Agent Gateway", "description": "An A2A agent card is the JSON document an agent publishes so other agents can discover its skills, endpoints, and authentication. This guide covers the v1.0 schema, annotated examples, extended cards, signatures, and how Bifrost serves a rewritten card.", "mainEntityOfPage": "https://www.getmaxim.ai/articles/a2a-agent-card/" } ```