Written by: Mariana Fonseca, Editorial Team, AI Growth Agent
Key Takeaways
- An agent card is a JSON metadata document defined by the A2A protocol. It acts as a machine-readable business card for AI agents and lives at
/.well-known/agent-card.json. - Three practical card types exist in real deployments: A2A protocol cards for machine-to-machine discovery, marketplace and UI cards for human browsing, and enterprise directory cards for internal governance and compliance.
- A2A v1.0 standardized fields such as
supportedInterfaces, madetagsrequired on every skill, and consolidated transport options so different orchestrators discover agents in a consistent way. - Skills blocks inside agent cards describe capabilities at a granular level. Peer agents read these blocks to decide delegation, including input and output modes, examples, and required tags.
- AI Growth Agent helps brands control their narrative across AI search surfaces. See how it works in a focused 20-minute walkthrough.
1. A2A Agent Card JSON Example With Core Fields Explained
A2A v1.0, which reached stable release in 2026 under Linux Foundation governance, consolidated the transport fields from earlier drafts into a single supportedInterfaces array and made tags required on every skill. The card below shows a complete, valid A2A v1.0 Agent Card for a contract-review agent. It includes the minimum viable field set for a working agent: identity, one interface, capability flags, and two skills that a calling agent can evaluate before delegating work.
{ "name": "ContractReviewAgent", "description": "Reviews commercial contracts for risk clauses, missing terms, and compliance gaps. Accepts PDF and plain-text input. Returns structured JSON findings and a plain-language summary.", "version": "2.1.0", "provider": { "organization": "Acme Legal", "url": "https://acmelegal.example.com" }, "supportedInterfaces": [ { "url": "https://agents.acmelegal.example.com/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" } ], "capabilities": { "streaming": false, "pushNotifications": false, "extendedAgentCard": false }, "defaultInputModes": ["text/plain", "application/pdf"], "defaultOutputModes": ["application/json", "text/plain"], "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "security": [{ "bearerAuth": [] }], "skills": [ { "id": "review-msa", "name": "Master Service Agreement Review", "description": "Identifies non-standard liability caps, indemnification clauses, and missing SLA terms in an MSA. Returns a JSON findings object and a plain-language summary.", "tags": ["contracts", "msa", "legal-review", "compliance"], "examples": [ "Review the attached MSA for liability exposure.", "Flag any indemnification clauses that deviate from our standard template." ] }, { "id": "review-nda", "name": "NDA Review", "description": "Checks mutual and one-way NDAs for scope, duration, and carve-out completeness. Returns structured findings.", "tags": ["nda", "confidentiality", "legal-review"], "examples": [ "Does this NDA cover residual knowledge?", "Is the non-compete scope enforceable in California?" ] } ] }Field-by-Field Breakdown of the Core Card:
- name: A human-readable agent identifier, required. Use a stable, descriptive string. Calling agents and orchestrators display this name in logs and routing decisions.
- description: Write this for routing, not marketing. State what the agent accepts, what it returns, and when another agent should choose it. Peer agents rely on this field to decide whether to delegate.
- version: The agent’s build version, not the protocol version. Increment this when skills, authentication, or the endpoint URL changes. Protocol version lives inside each
supportedInterfacesentry. - provider: Optional. In A2A v1.0, the field is
provider.organization, notprovider.name. This rename from pre-1.0 drafts breaks older cards. - supportedInterfaces: Replaces the pre-1.0 top-level
urlandpreferredTransportfields. This field is an ordered array where the first entry is the preferred interface. Every entry must includeurl,protocolBinding, andprotocolVersion. A partially specified entry is an error. - capabilities: Treat these flags as a contract. A client that reads
streaming: trueand calls a streaming method that does not exist receives anUnsupportedOperationError. Leave every flag you cannot honor atfalse. - defaultInputModes / defaultOutputModes: Required arrays of MIME type strings. Individual skills can override these with their own
inputModesandoutputModes. - securitySchemes / security: Optional but recommended for any non-public endpoint. Declare the scheme here and keep credentials out of the card.
- skills: Required, non-empty array. Each skill needs
id,name,description, andtags. Section 3 covers the skills block in more detail.
2. A2A Agent Card Example With Streaming and Push Notifications
The first example covers a synchronous agent, which works until a task takes minutes instead of seconds. A2A supports three interaction patterns discoverable from the Agent Card: synchronous request and response, streaming via Server-Sent Events, and asynchronous push notifications via callback URLs. The card below enables both streaming and push notifications for a data-pipeline agent that runs long jobs.
{ "name": "PipelineOrchestrationAgent", "description": "Orchestrates multi-step data transformation pipelines. Accepts structured JSON job definitions. Streams progress events and delivers a final artifact to a client-provided webhook when the pipeline completes. Typical latency: 30 seconds to 10 minutes depending on dataset size.", "version": "1.4.0", "provider": { "organization": "DataOps Inc.", "url": "https://dataops.example.com" }, "supportedInterfaces": [ { "url": "https://agents.dataops.example.com/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }, { "url": "https://agents.dataops.example.com/a2a/http", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0" } ], "capabilities": { "streaming": true, "pushNotifications": true, "extendedAgentCard": false }, "defaultInputModes": ["application/json"], "defaultOutputModes": ["application/json", "text/plain"], "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://auth.dataops.example.com/oauth/token", "scopes": { "pipelines:run": "Submit and monitor pipeline jobs", "pipelines:read": "Read pipeline status and artifacts" } } } } }, "security": [{ "oauth2": ["pipelines:run"] }], "skills": [ { "id": "run-etl-pipeline", "name": "Run ETL Pipeline", "description": "Executes a defined ETL job against a source dataset. Streams step-level progress events. Delivers a completion artifact to the caller's webhook URL when finished.", "tags": ["etl", "pipeline", "data-transformation", "streaming"], "examples": [ "Run the nightly sales aggregation pipeline for Q3.", "Transform the raw clickstream export into the analytics schema." ] } ] }How the Capabilities Object Changes in This Card:
- streaming: true signals that the agent supports
SendStreamingMessageandSubscribeToTask. As noted in Section 1, a client that calls a streaming operation without this flag set totruereceives anUnsupportedOperationError. - pushNotifications: true signals that the agent delivers results to a client-provided callback URL. This configuration suits tasks that run for minutes or longer when polling would waste resources.
- Two entries in supportedInterfaces: A single card can advertise JSON-RPC, gRPC, and HTTP+JSON endpoints in priority order. Calling agents iterate through the array and select the binding they support.
- OAuth 2.0 client credentials flow: This flow fits backend agent-to-agent workflows where no end user participates. Listing multiple schemes without a clear preference causes silent failures at task-dispatch time. Choose the scheme that matches your deployment and declare it clearly.
3. Agent Card Skills Examples and Field Details
Each skill in the skills array is the field a peer agent reads to decide whether to delegate a task. The skill block carries the most precise capability description. The array below shows two skills with full field coverage that you can adapt into your own cards.
"skills": [ { "id": "generate-sql-query", "name": "SQL Query Generation", "description": "Converts a plain-language business question into a validated SQL SELECT statement for a specified database schema. Accepts a natural-language question and a JSON schema descriptor. Returns a SQL string and an explanation of the query logic. Does not execute queries or modify data.", "tags": ["sql", "query-generation", "natural-language", "analytics"], "inputModes": ["text/plain", "application/json"], "outputModes": ["text/plain", "application/json"], "examples": [ "How many orders were placed in the last 30 days by customers in California?", "Show me the top 10 products by revenue for Q2 2026." ] }, { "id": "explain-query-results", "name": "Query Results Explanation", "description": "Takes a SQL result set in JSON format and produces a plain-language executive summary with key findings, anomalies, and recommended follow-up questions. Suitable for non-technical stakeholders.", "tags": ["sql", "data-interpretation", "summary", "analytics"], "inputModes": ["application/json"], "outputModes": ["text/plain", "text/markdown"], "examples": [ "Summarize these sales results for the CMO.", "What are the three most important takeaways from this dataset?" ] } ]Field-by-Field Breakdown of Skills:
- id: Treat changes to
skills[].idas breaking. This value is the stable machine key that a calling agent stores and references. Use lowercase kebab-case strings. - name: A human-readable label that appears in logs, directories, and orchestrator UIs.
- description: Write this for LLMs. Include what the skill accepts, what it returns, typical latency, and any hard limitations. A vague description leads to poor delegation decisions by calling agents.
- tags: Required in A2A v1.0. Earlier drafts treated tags as optional and many cards omitted them. Tags let a calling agent filter skills without parsing descriptions. A client searching for
analyticsmatches a skill taggedanalyticsdirectly. - inputModes / outputModes: Per-skill overrides for the card-level defaults. Use these when a skill accepts a different modality than the agent’s default, such as a JSON-only skill on an agent whose default input is
text/plain. - examples: Example prompts help a calling agent decide which skill to invoke. Orchestrators can embed these examples directly into system prompts to give context about available capabilities.
Traditional search tools show you where your brand stands. AI Growth Agent makes your brand the answer. Book a kickoff and see your first article live within a week.
4. Agent Card Examples for Marketplace and UI Cards
Marketplace and UI agent cards present the same underlying agent in a human-friendly layout. They appear as rendered components in an agent directory for people browsing a catalog. The agentregistry-dev admin UI implements two distinct human-readable card components, AgentCard and SkillCard, that render registry resources in list views instead of exposing protocol-level discovery fields.
The anatomy of a marketplace agent card typically includes the following elements:
- Name and icon: The agent’s display name and a distinguishing icon. The agentregistry-dev
AgentCarduses aBoticon to distinguish agents from skills at a glance. - Status badge: Operational state such as deployed, staging, or failed. The agentregistry-dev
DeployedPagecolor-codes resources by runtime state. - Description: A one-to-two sentence plain-language summary of what the agent does, written for a non-technical user.
- Capability tags: Human-readable labels such as “Streaming,” “PDF input,” or “OAuth 2.0” that surface protocol capabilities in a scannable format.
- Version indicator: The current version and, where relevant, a version-count badge that shows how many versions exist.
- Owner and team: The accountable team or individual, which is critical for governance in enterprise directories.
- Primary action: A single prominent button. The agentregistry-dev
AgentCardrenders a Deploy action that is only enabled when a valid container image exists. This pattern shows how UI cards embed operational actions instead of A2A protocol fields.
Rendered as a UI card, the same ContractReviewAgent loses machine-readable detail and gains human-facing context. Compare this layout to the JSON in Section 1 and you can see protocol fields replaced by status, owner, and deployment actions.
┌─────────────────────────────────────────────────────┐ │ 🤖 ContractReviewAgent [● Deployed] v2.1.0 │ │ Owner: Acme Legal · Legal Team │ │─────────────────────────────────────────────────────│ │ Reviews commercial contracts for risk clauses, │ │ missing terms, and compliance gaps. Accepts PDF │ │ and plain-text input. │ │─────────────────────────────────────────────────────│ │ Tags: contracts · msa · nda · legal-review │ │ Input: PDF, text/plain Output: JSON, text/plain │ │ Auth: Bearer token Protocol: A2A JSONRPC 1.0 │ │─────────────────────────────────────────────────────│ │ Skills: MSA Review · NDA Review │ │─────────────────────────────────────────────────────│ │ [ View Details ] [ Deploy ] │ └─────────────────────────────────────────────────────┘The key structural difference appears clearly in Microsoft’s design guidance. Microsoft’s Adaptive Cards for agent design treat cards as the human-facing UI layer of agent interaction. They use a JSON format that renders as native UI, adapting to light and dark mode, screen size, and Microsoft 365 surfaces. That design makes Adaptive Cards structurally distinct from the machine-facing A2A protocol Agent Card JSON. A marketplace card helps a person decide whether to deploy an agent. An A2A protocol card helps another agent decide whether to call one.
5. Agent Card Examples for Enterprise Agent Directories
Gartner forecasts that an average global Fortune 500 company could use more than 150,000 agents by 2028, while only 13 percent of surveyed organizations believe they have the right governance in place. The enterprise agent directory card pattern addresses this gap by capturing operational and governance metadata that neither the A2A protocol card nor the marketplace card covers.
An enterprise directory card functions as an operational contract for internal teams. Every agent marketplace listing should contain fields such as job and boundary, owner and sponsor, inputs and data sources, actions and permissions, evaluation status, cost and service level, version and change log, and a feedback and incident link. These fields give risk, legal, and operations teams a shared view of how each agent behaves.
The JSON below shows a complete enterprise directory card example:
{ "agentId": "urn:agent:acmelegal:contract-review:prod", "displayName": "ContractReviewAgent", "owner": { "team": "Legal Technology", "primaryContact": "[email protected]", "sponsor": "VP Legal Operations" }, "environment": "production", "version": "2.1.0", "deployedAt": "2026-08-15T09:00:00Z", "lastReviewedAt": "2026-09-01T00:00:00Z", "approvalStatus": "approved", "dataAccessScope": [ "contracts-repository:read", "legal-templates:read" ], "dataClassification": "confidential", "capabilities": [ "MSA review", "NDA review", "Compliance gap analysis" ], "notClearedFor": [ "Executing contract modifications", "Accessing HR or payroll data", "External network calls beyond approved endpoints" ], "authenticationRequired": true, "authScheme": "bearer", "a2aCardPath": "https://agents.acmelegal.example.com/.well-known/agent-card.json", "incidentContact": "[email protected]", "costCenter": "CC-4421", "estimatedCostPerTask": "$0.08–$0.45 depending on document length", "sla": "P95 response within 90 seconds for documents under 50 pages", "changeLog": [ { "version": "2.1.0", "date": "2026-08-15", "summary": "Added NDA review skill. Updated bearer token scope." }, { "version": "2.0.0", "date": "2026-06-01", "summary": "Migrated to A2A v1.0. Replaced top-level url with supportedInterfaces." } ] }Why This Pattern Matters for Governance:
- owner and sponsor: Orphaned agents, whose creator accounts have been disabled, can continue running with inherited credentials and may not be flagged for review. A named human sponsor and team close this accountability gap.
- dataAccessScope and notClearedFor: EU AI Act enforcement began in August 2026, with penalties up to €35 million or 7% of global annual revenue. The Act requires organizations to maintain inventories of AI systems and demonstrate oversight. Explicit capability boundaries support that demonstration.
- approvalStatus: AWS Agent Registry records progress through a governed lifecycle of DRAFT, PENDING_APPROVAL, APPROVED, REJECTED, and DEPRECATED. Mirroring this in your internal card keeps the directory aligned with external registry state.
- a2aCardPath: This field links the governance record to the machine-readable A2A protocol card so the directory entry and the protocol artifact stay synchronized.
Stop letting AI define your brand at random. Control the narrative across online search. Book a kickoff with AI Growth Agent.
Where the Agent Card Lives
The A2A protocol registers /.well-known/agent-card.json as the standard RFC 8615 discovery path. A calling agent that knows an agent’s domain constructs the URL https://{agent-server-domain}/.well-known/agent-card.json and issues an unauthenticated HTTP GET. The response must return HTTP 200 with Content-Type: application/json and a valid A2A Agent Card JSON body.
Microsoft’s Agent Framework serves the agent card at the well-known A2A path using a dedicated handler separate from the protocol endpoint mapping. Google Cloud’s Agent Registry treats capability declarations as a first-class part of the Agent Card itself rather than a separate sidecar resource.
A2A v1.0 replaced the pre-1.0 path /.well-known/agent.json with /.well-known/agent-card.json as the canonical path. For backward compatibility, serve the canonical path with a 200 response and alias the legacy path with a 308 redirect. Servers should include HTTP caching headers, such as a Cache-Control header with a max-age directive and an ETag derived from the card’s version field. These headers let calling agents use conditional requests instead of fetching the full card on every interaction.
Frequently Asked Questions
What Is an Agent Card in the A2A Protocol?
An agent card in the A2A protocol is a JSON metadata document that a server-side agent publishes to describe itself to calling agents. It declares the agent’s name, description, version, endpoint URLs, supported protocol bindings, capability flags such as streaming and push notifications, accepted input and output MIME types, authentication requirements, and a list of skills the agent can perform. Calling agents fetch the card before initiating any task and use it to decide whether the agent can handle a given job and how to authenticate.
Where Does an Agent Card Live?
An A2A protocol agent card is served at the standardized well-known URI https://{agent-server-domain}/.well-known/agent-card.json, following the RFC 8615 well-known URI convention. The file must be served with Content-Type: application/json and return HTTP 200. No authentication is required to fetch the card itself, even if the agent’s A2A endpoint requires authentication, because clients must read the card to learn what credentials are needed. The legacy path /.well-known/agent.json used in pre-1.0 drafts should be aliased with a 308 redirect to the canonical path.
What Is the Difference Between an A2A Agent Card and a Marketplace Agent Card?
An A2A protocol agent card is a machine-readable JSON document consumed by other agents, AI runtimes, and orchestrators. Its fields, including supportedInterfaces, capabilities, securitySchemes, and skills, are structured for programmatic parsing. A marketplace or UI agent card is a rendered visual component in an agent directory, designed for humans browsing a catalog. It surfaces the same underlying information, such as name, capabilities, skills, and status, in a layout optimized for human decision-making.
