Written by: Mariana Fonseca, Editorial Team, AI Growth Agent
Key Takeaways for Production Agent Cards
- An Agent Card is a machine-readable JSON document at
/.well-known/agent-card.jsonthat declares an agent’s identity, endpoints, capabilities, and skills under the A2A protocol. - Production-grade cards include all required top-level fields, OpenAPI-aligned
securitySchemes, CORS headers, and semantic versioning with an updatedlastUpdatedtimestamp. - Each skill is explicitly defined with id, name, description, tags, input and output modes, and real examples so other agents can discover and invoke them correctly.
- Constraints, rate limits, spend caps, and scope-of-authority boundaries are declared to show what the agent can do autonomously versus what requires human approval.
- AI Growth Agent automatically provisions compliant Agent Cards and the full agent-discovery stack on every client site, and you can schedule a demo to get your first production-ready card live within a week.
Why Agent Cards Matter in the A2A Ecosystem
The agentic internet now operates in production, not as a future concept. Google launched the Agent2Agent (A2A) protocol in April 2025 and donated it to the Linux Foundation in June 2025 to support an open and interoperable ecosystem for AI agents. By April 2026, A2A had reached 150+ supporting organizations with production deployments in finance, supply chain, and insurance, including Microsoft, AWS, Salesforce, SAP, and ServiceNow.
Agent Cards act as the discovery layer that keeps this ecosystem usable. Without a published Agent Card, a compliant A2A client has no standard way to learn what your agent does, which endpoints to call, or how to authenticate. Sites that omit the card appear undocumented to the agents that now perform most discovery work on behalf of users.
The standards landscape is consolidating quickly. Multiple agent communication and discovery protocols are already in active use, including MCP, ACP, A2A, ANP, and agents.json, with ongoing pressure toward consolidation and standardization. A2A v1.0 under Linux Foundation governance now serves as the production-grade anchor of that stack.
As outlined in the key takeaways, AI Growth Agent handles Agent Card provisioning and related discovery files automatically, which removes the engineering overhead of tracking and implementing each new revision of the standard.
Schedule a consultation session to see if you are a good fit and launch the complete agent-discovery stack without manual implementation work.
Required JSON Schema for A2A 1.0 Agent Cards
A compliant A2A 1.0 Agent Card requires at minimum the fields name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes, and skills. The following example shows a copy-paste-ready production card that includes required and recommended fields.
{ "name": "Acme Support Agent", "description": "Handles customer support queries, order lookups, and escalation routing for Acme Corp.", "version": "1.2.0", "lastUpdated": "2026-05-29T00:00:00Z", "url": "https://acme.com/a2a", "supportedInterfaces": [ { "url": "https://acme.com/a2a", "protocolBinding": "jsonrpc", "protocolVersion": "1.0" } ], "capabilities": { "streaming": true, "pushNotifications": false, "stateTransitionHistory": true, "extendedAgentCard": false }, "defaultInputModes": ["text"], "defaultOutputModes": ["text"], "skills": [ { "id": "order-lookup", "name": "Order Lookup", "description": "Retrieves order status and tracking information by order ID or customer email.", "tags": ["orders", "ecommerce", "support"], "inputModes": ["text"], "outputModes": ["text"], "examples": [ "What is the status of order #A12345?", "Where is my package for [email protected]?" ] }, { "id": "escalate-ticket", "name": "Escalate Support Ticket", "description": "Routes unresolved issues to a human support agent with full context.", "tags": ["escalation", "support", "human-handoff"], "inputModes": ["text"], "outputModes": ["text"], "examples": [ "I need to speak to a human about a billing dispute." ] } ], "securitySchemes": { "OAuth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://auth.acme.com/oauth2/token", "scopes": { "support.read": "Read order and ticket data", "support.write": "Create and escalate tickets" } } } } }, "security": [ { "OAuth2": ["support.read", "support.write"] } ] } The security field declares required OAuth2 scopes so client agents can discover required authorization before invoking the remote agent. The protocolVersion field inside supportedInterfaces uses "1.0" for A2A 1.0 implementations.
Hosting Agent Cards at /.well-known/agent-card.json
Each agent publishes its Agent Card at the well-known URL /.well-known/agent-card.json, which lets other agents discover capabilities before routing work. Production environments follow several concrete configuration rules.
CORS and caching. The /.well-known/agent-card.json endpoint includes CORS headers and a one-hour cache directive for cross-origin fetchability, and on Cloudflare Pages these live in the public/_headers file. A minimal correct header set looks like this:
Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, OPTIONS Cache-Control: public, max-age=3600 Content-Type: application/json Link header discovery. The Agent Card endpoint appears in a site-wide HTTP Link header using rel="agent-card", which allows agents to discover it without parsing HTML. Example: Link: </.well-known/agent-card.json>; rel="agent-card".
Reverse-proxy and context-path considerations. When you deploy behind reverse proxies or with a non-root servlet context path, the Agent Card remains reachable at the full expected path, including any context prefix such as /weather/.well-known/agent-card.json. Peer agents discover the card by appending .well-known/agent-card.json to the context path from each remote agent’s base URL, so path rewriting preserves this segment.
Public reachability. The /.well-known/agent-card.json endpoint stays publicly reachable. When the card contains sensitive capability or endpoint information, the A2A specification recommends access controls on the card endpoint and avoidance of plaintext secrets.
Semantic Versioning and lastUpdated Rules
Apply the following rules to every Agent Card change, and treat each tier as a higher-impact change for consuming agents.
- PATCH (for example, 1.2.0 to 1.2.1) corrects a description, fixes a typo, or updates an example. These changes do not alter behavior, so consuming agents can safely ignore them.
- MINOR (for example, 1.2.0 to 1.3.0) adds a new optional skill, capability flag, or output mode. These additive changes stay non-breaking and allow existing integrations to keep working without updates.
- MAJOR (for example, 1.2.0 to 2.0.0) removes a required field, changes an endpoint URL, or alters authentication scheme structure. These breaking changes force consuming agents to update their integration logic, so they require a new major version and advance communication.
The lastUpdated field updates to an ISO 8601 UTC timestamp on every publish, regardless of change size. This pattern lets client agents detect staleness without fetching and diffing the full document.
You can communicate deprecation of resources with the HTTP Sunset header plus an optional Link header that points to migration documentation, which gives consumers time to migrate. A stable versioning strategy supports multiple versions running at the same time so that consumers can move at their own pace.
Declaring Skills, Schemas, and Authentication
Agent Cards declare skills using an object that includes id, name, description, tags, inputModes, outputModes, and examples. The following example shows a skills array with explicit input and output schema annotations aligned with OpenAPI conventions.
"skills": [ { "id": "analyze-sentiment", "name": "Sentiment Analysis", "description": "Classifies the sentiment of a text passage as positive, neutral, or negative with a confidence score.", "tags": ["nlp", "sentiment", "classification"], "inputModes": ["text"], "outputModes": ["text", "application/json"], "input_schema": { "type": "object", "properties": { "text": { "type": "string", "description": "The passage to analyze." } }, "required": ["text"] }, "output_schema": { "type": "object", "properties": { "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative"] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } } }, "examples": [ "Analyze the sentiment of this customer review.", "Is this feedback positive or negative?" ] } ] For authentication, A2A agents declare supported authentication schemes using a format aligned with OpenAPI Specification security schemes, including apiKey, http (Bearer tokens), oauth2, openIdConnect, and mtls. The following snippet shows a Bearer token example.
"securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "security": [ { "BearerAuth": [] } ] Defining Constraints, Boundaries, and Spend Limits
Constraints in the Agent Card communicate scope-of-authority to calling agents and to human operators who audit the system. Production deployments cover several specific categories.
Scope-of-authority declarations. Effective Agent Cards list autonomous actions separately from actions that require human approval, such as an interview scheduler that separates initial screenings from final-round scheduling or last-minute changes.
Rate limits and cooldown periods. Safety controls include rate limits, such as a maximum number of attempts per user and per day, plus cooldown periods between attempts.
Blocking conditions and exception handling. Cards document blocking conditions and exception handling, including escalation to a human operator and automatic holds on edge cases.
Hard stops. GitHub’s analysis of over 2,500 repositories found that the most effective specs use a three-tier boundary system of “always do,” “ask first,” and “never do,” with “never commit secrets” as the most common helpful constraint.
The following JSON block illustrates a constraints section.
"constraints": { "autonomousActions": [ "Retrieve order status", "Send status update notifications" ], "requiresApproval": [ "Issue refunds above $500", "Cancel orders placed more than 7 days ago" ], "hardStops": [ "Never expose PII in response payloads", "Never process payment data directly" ], "rateLimits": { "requestsPerMinute": 60, "requestsPerDay": 5000, "cooldownSeconds": 10 }, "spendLimits": { "maxTransactionUSD": 500, "dailyCapUSD": 10000 }, "operatingHours": { "schedule": "24/7", "quietHours": "22:00-06:00 local" } } Connecting Agent Cards with MCP and Discovery Files
Agent Cards, MCP endpoints, llms.txt, and related discovery files form a layered stack that covers capability declaration, interaction, and content discovery. Each layer serves a distinct function, and missing any layer creates a gap in discoverability or interoperability.
Anthropic donated the Model Context Protocol (MCP) to the Linux Foundation’s Agentic AI Foundation in December 2025. MCP handles the interaction layer by giving an agent a structured way to call tools and retrieve data from a site in natural language. The Agent Card handles the announcement layer by telling a compliant A2A client where the MCP server lives, what it can do, and how to authenticate.
Google Chrome shipped WebMCP in Chrome 146 Canary in February 2026 as an early preview co-developed with Microsoft and incubated at W3C, introducing the navigator.modelContext API for exposing structured tools to AI agents. Sites that expose a Blog MCP compatible with Chrome 146+ and other WebMCP-enabled browsers still publish an Agent Card so A2A-compliant clients can locate and authenticate against the MCP endpoint.
The complete agent-ready stack for a production site includes the following elements.
/.well-known/agent-card.json, which provides the A2A capability declaration- An MCP or WebMCP endpoint, which provides interactive tool access
llms.txtandllms-full.txt, which provide structured content for LLM crawlersrobots.txt, which continues to control crawler access and does not get replaced by the Agent Cardsitemap.xml, which indexes content for traditional and AI crawlers- An OpenAI discovery endpoint exposed via
/.well-known/
The provisioning system described earlier extends to this full stack, including Agent Card guidance, Blog MCP compatible with Chrome 146+ and other WebMCP-enabled browsers, llms.txt and llms-full.txt, and natural language query parameters at /?s={query} that return personalized, internally linked responses to agents. Clients only configure a reverse proxy rewrite that connects the blog to a subdirectory under the client’s domain.
Schedule a demo to see if you are a good fit and have the full agent-discovery stack provisioned on your domain within the first week.
Frequently Asked Questions
What is an Agent Card and how does it differ from robots.txt?
An Agent Card is a structured JSON document served at /.well-known/agent-card.json that declares an agent’s identity, service endpoints, capabilities, authentication requirements, and skills to other A2A-compliant agents. Robots.txt is a flat text file that tells crawlers which paths they may or may not index. The two files serve different classes of reader and different purposes. Robots.txt does not describe an MCP endpoint, declare authentication schemes, or enumerate interactive skills. The Agent Card adds a dedicated layer for interactive agents, and robots.txt continues to handle crawler access controls. A production site uses both.
How long does it take to implement a compliant Agent Card from scratch?
Writing the JSON itself usually takes a few hours for an engineer who understands the A2A specification. The surrounding work, such as configuring CORS headers, setting up the /.well-known/ path on the correct server or CDN layer, handling reverse-proxy path rewriting, wiring the Link header for discovery, integrating with an MCP endpoint, and publishing llms.txt alongside the card, typically takes several days to a week for a team that encounters the stack for the first time. Keeping the card current as the A2A specification evolves under Linux Foundation governance adds ongoing maintenance overhead. AI Growth Agent provisions and maintains the complete stack automatically, which removes that recurring engineering cost.
What authentication schemes does the A2A protocol support in Agent Cards?
The A2A specification aligns authentication declarations with OpenAPI Specification security schemes. Supported types include apiKey, http (which covers Basic and Bearer token patterns), oauth2 (with clientCredentials, authorizationCode, implicit, and password flows), openIdConnect, and mtls. Each scheme appears in the securitySchemes object at the top level of the Agent Card, and the security array references which schemes and scopes are required to call the agent. This structure lets a calling agent determine required authorization before making any requests, which is essential for secure agent-to-agent interactions at scale.
How should constraints and spend limits be versioned and communicated to calling agents?
Constraints live inside the Agent Card document and follow the same semantic versioning rules as the rest of the card. Any change to a rate limit, spend cap, scope-of-authority boundary, or hard stop that could affect a calling agent’s behavior counts as at least a MINOR version increment if it is additive, or a MAJOR increment if it removes or tightens an existing permission. The lastUpdated timestamp updates on every publish so calling agents can detect that constraints changed without diffing the full document. For spend limits and scope-of-authority declarations with compliance or financial implications, teams often also communicate changes through the HTTP Sunset header on deprecated constraint sets and maintain a changelog that is accessible via a Link header in the card response.
How does AI Growth Agent handle Agent Card provisioning and ongoing compliance?
AI Growth Agent automatically provisions Agent Cards, MCP endpoints, llms.txt and llms-full.txt, OpenAI discovery endpoints, and the full agent-discovery stack on every client site within the first week of engagement. The infrastructure is served through a reverse proxy rewrite under a subdirectory of the client’s domain, so the client inherits the parent domain’s authority without changes to the existing site or CMS. When the A2A specification advances under Linux Foundation governance, AI Growth Agent reads the updated spec and rolls out changes across every client site within the week. Clients own all the content and infrastructure, and their only engineering task is the initial reverse proxy configuration, for which AI Growth Agent provides exact setup documentation tailored to the client’s CDN or hosting provider.
Conclusion: Keeping Agent Cards Production-Ready
Agent Cards now serve as the foundational discovery layer of the agentic internet. A production-grade implementation includes a correctly structured JSON document at the canonical /.well-known/agent-card.json endpoint, CORS and Link header configuration for cross-origin discoverability, semantic versioning with accurate lastUpdated timestamps, explicit skill declarations with input and output schemas, OpenAPI-aligned authentication, and a constraints block that communicates scope-of-authority, rate limits, and spend caps to calling agents. That implementation then stays current as A2A evolves under Linux Foundation governance and continues to attract new supporting organizations.
Manual implementation of this stack often becomes fragile and outdated. The automated provisioning approach described throughout this article removes that fragility and maintenance burden by keeping Agent Cards, MCP endpoints, llms.txt, and the broader agent-discovery stack aligned with the latest standards. Clients across the US, Canada, Brazil, and Europe already run the full agentic technical SEO stack on autopilot, with no ongoing engineering overhead and no agency dependency.
Schedule a consultation session to see if you are a good fit and have your first compliant Agent Card, MCP endpoint, and agent-discovery stack live within a week.
