How Agent Cards Work: A2A Discovery & Task Delegation

Written by: Mariana Fonseca, Editorial Team, AI Growth Agent

Key Takeaways

• Agent Cards are standardized JSON files served at /.well-known/agent-card.json that let AI agents discover, authenticate, and delegate tasks under the A2A protocol.

• Each card declares an agent’s identity, skills, endpoints, and security requirements so other agents can evaluate and interact without hard-coded integrations.

• The A2A discovery workflow covers fetching the card, validating its schema, evaluating capabilities, inspecting security schemes, and initiating tasks through declared endpoints.

• Brands that want AI surfaces to cite their content must publish and maintain compliant Agent Cards alongside llms.txt, MCP endpoints, and reverse-proxy setups.

• AI Growth Agent handles this work as part of its automated stack, so marketing teams avoid ongoing manual maintenance.

How Agent Cards Document Your Brand for AI

An Agent Card is a machine-readable metadata file that acts as a digital résumé for an agent under the A2A protocol. It advertises an agent’s capabilities or skills, endpoint URL, required authentication methods, input and output expectations, and optional metadata such as versioning or operational limits. Other agents can then select it based on skills instead of relying on hard-coded integrations.

Before this convention, that information lived informally across sitemap hints, robots.txt entries, and guesswork. The Agent Card gives it a dedicated home, a structured format, and a known address. Discovery in A2A supports well-known URIs such as /.well-known/agent-card.json, direct URLs, registries and catalogs, and crawling and indexing, with no single mandatory global registry defined.

For brands, the implication is direct. A site that does not publish an Agent Card is undocumented to the class of interactive agents now doing most of the discovery. An agent does not scroll. It reads structured content, follows declared standards, and treats an undeclared site the same as an undiscovered one.

This gap creates a practical barrier for most marketing teams, because keeping a compliant Agent Card current requires ongoing engineering time that rarely exists on the roadmap.

AI Growth Agent provisions Agent Cards automatically across every client site. Book a kickoff and see your first article live within a week.

Inside a Standard Agent Card JSON File

An A2A-compliant Agent Card JSON payload includes the top-level fields name, description, version, protocolVersion, url, and skills, along with fields such as capabilities, defaultInputModes, defaultOutputModes, and securitySchemes. The skills array contains objects with the fields id, name, and description.

The following example shows a copy-paste /.well-known/agent-card.json aligned to the 2026 specification.

{ "name": "Brand Content Agent", "description": "Retrieves authoritative brand content, answers product queries, and surfaces citations for AI surfaces.", "version": "1.0.0", "protocolVersion": "1.0", "url": "https://www.example.com/agent", "capabilities": { "streaming": true, "pushNotifications": false, "stateTransitionHistory": true }, "defaultInputModes": ["text"], "defaultOutputModes": ["text", "application/json"], "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "skills": [ { "id": "brand-content-retrieval", "name": "Brand Content Retrieval", "description": "Returns structured brand content, product details, and sourced citations in response to natural language queries.", "tags": ["content", "brand", "citations", "products"], "examples": [ "What are the key features of this product?", "Summarize the brand's position on sustainable sourcing." ] } ] }

The securitySchemes object follows OpenAPI-style security scheme types including apiKey, http (Bearer tokens), oauth2, openIdConnect, and mtls. The capabilities object is optional and may specify streaming, pushNotifications, or stateTransitionHistory as boolean flags.

Keeping this file current as the specification evolves quickly becomes a maintenance burden. AI Growth Agent updates Agent Cards as part of its provisioning system, so the file at /.well-known/agent-card.json always reflects the current standard without engineering intervention.

How A2A Discovery Works in Practice

An A2A interaction follows three main steps: (1) Discovery via the Agent Card, (2) Authentication and authorization using standards such as OAuth 2.0, and (3) Communication and execution through structured messages within a stateful task lifecycle. The numbered workflow below maps each step to its validation checkpoint and its connection to the broader agentic technical SEO stack.

1. Card fetch. A client agent issues an HTTP GET request to https://<host>/.well-known/agent-card.json. The server must return a valid JSON document with a 200 OK status and a Content-Type: application/json header. Validation checkpoint: confirm the response is well-formed JSON and that required fields (name, description, version, protocolVersion, url, skills) are present.

2. Schema validation. The card payload is validated against the official A2A JSON schema before indexing for skill and tool discovery. Validation checkpoint: reject cards that fail schema validation instead of attempting to parse partial data.

3. Capability evaluation. The client parses the JSON to evaluate relevance based on fields such as protocolVersions, skills, capabilities, supportedInterfaces, and securitySchemes before initiating any task delegation. Validation checkpoint: confirm protocol version compatibility and that at least one skill matches the delegating agent’s task requirements.

4. Security scheme inspection. Clients use the Agent Card to determine whether an agent is suitable for a given task and how to communicate with it securely, including by inspecting the securitySchemes field during the discovery step. Validation checkpoint: verify that the declared scheme is supported by the client before proceeding.

5. Task initiation. The client constructs a structured task request and sends it to the endpoint declared in the card’s url field. Validation checkpoint: confirm the endpoint responds and that the task lifecycle state transitions as expected (submitted, working, completed, or failed).

This workflow connects directly to the reverse-proxy subdirectory setup and real-time bot tracking that AI Growth Agent provisions on every client site. The /.well-known/agent-card.json file is served from the subdirectory infrastructure, inherits the parent domain’s authority, and every agent fetch is logged in the bot tracking layer so operators can see exactly which agents are discovering their content and when.

Stop letting AI define your brand at random. Control the narrative across online search. Book a kickoff with AI Growth Agent.

Securing Agent Cards and Inter-Agent Traffic

A2A v1.0 introduced Signed Agent Cards for cryptographic identity verification, strengthening trust in discovered agents and supporting secure, high-scale deployments through a web-aligned architecture. Signing a card lets a consuming agent verify that the card has not been tampered with in transit and that it originates from the declared host.

The OWASP AI Agent Security Cheat Sheet recommends signing and verifying all inter-agent communications to prevent tampering and unauthorized actions in multi-agent systems. It also advises implementing trust boundaries between agents, validating and sanitizing inter-agent communications, and preventing privilege escalation through agent chains.

Common pitfalls and their mitigations:

• Unsigned cards in production. Cards served without cryptographic signatures are vulnerable to man-in-the-middle substitution. Mitigation: implement Signed Agent Cards per the A2A v1.0 specification.

• Overly permissive scopes. Agents should never be granted unrestricted tool access or wildcard permissions. Mitigation: declare only the minimum required scopes in securitySchemes.

• Untrusted external data in agent context. All external data, including user messages, retrieved documents, API responses, and emails, must be treated as untrusted and sanitized before being placed in agent context. Mitigation: sanitize all inputs before passing them to the agent execution environment.

• Stale authentication declarations. A card that declares an OAuth 2.0 scheme but points to a deprecated token endpoint will cause silent discovery failures. Mitigation: automate card updates whenever authentication infrastructure changes.

• Missing audit trails. OWASP recommends maintaining structured audit logs that capture action classification, risk score, authorization outcome, approval identifier, execution result, and policy version for all high-risk agent actions. Mitigation: route all agent card fetches through the bot tracking layer.

How Agent Cards and MCP Work Together

MCP addresses agent-to-tool and agent-to-data connectivity, whereas A2A standardizes agent-to-agent discovery and communication so that agents can route queries to remote specialist agents at runtime without manual code changes or redeployments. The two protocols are complementary, not competing. A2A is designed to be used alongside MCP, with each A2A-capable agent also acting as an MCP client for its own tool access while using A2A exclusively for inter-agent delegation.

Dimension	Agent Card (A2A)	MCP
Discovery mechanism	JSON document published at /.well-known/agent-card.json	Capability negotiation plus tool/resource/prompt listing between a host, MCP client, and MCP server over JSON-RPC with stateful sessions
Primary purpose	Agent-to-agent coordination, capability-based delegation, and distributed orchestration across autonomous agents	Tool-level execution within an individual agent’s loop; standardized LLM-to-tool, LLM-to-data access
Data model	Task with a defined lifecycle (submitted, working, completed, failed); supports synchronous responses, streaming, and async notifications	Tools (callable functions with input/output schemas), resources (structured data or files), and prompts (reusable templates)
Enterprise scalability	Supports dynamic discovery of frequently added or changed sub-agents via registries; v1.0 adds enterprise-grade multi-tenancy	Tool descriptions can exhaust an LLM’s context window as tool count grows, creating a scalability limit even for large-context models

A site with an MCP server and no Agent Card is a service running on an unpublished number. The MCP side handles interaction. The Agent Card handles announcement. Both layers must ship together for either to matter at enterprise scale.

Publishing Agent Cards Within an AI SEO Stack

Publishing an Agent Card is one step in a larger agentic technical SEO stack. The full stack that AI Growth Agent provisions on every client site includes the Agent Card at /.well-known/agent-card.json, Blog MCP, llms.txt and llms-full.txt, OpenAI discovery endpoints, natural language query parameters at /?s={query}, Markdown serving for agent crawlers, and the reverse-proxy subdirectory setup that ties it all together.

The integration sequence for a brand publishing its first Agent Card follows a predictable order.

1. Create the agent-card.json file using the structure above, populating all required fields and declaring the correct securitySchemes for your authentication infrastructure. This file becomes your agent’s identity document.

2. Once the file is ready, serve it at https://yourdomain.com/.well-known/agent-card.json with Content-Type: application/json and ensure it is accessible without authentication. Agents must be able to discover your card without credentials.

3. With the card publicly accessible, configure the reverse-proxy subdirectory so that the Agent Card, Blog MCP endpoint, and content are all served under the parent domain rather than a subdomain. This configuration preserves domain authority and keeps all discovery files under one trusted host.

4. Publish llms.txt and llms-full.txt at the domain root so AI surfaces can read the brand’s content structure alongside the Agent Card.

5. Register the card URL with any enterprise agent registries relevant to your sector so specialist agents can find it through curated catalogs.

6. Validate the card against the official A2A JSON schema and confirm bot tracking is logging agent fetches.

Manual execution of this sequence fails at scale because the A2A specification continues to evolve. The A2A roadmap includes an interoperability specification, registry consolidation, expanded testing and tooling, and security and deployment best practices to guide continued evolution beyond version 1.0. Every specification update requires a manual card revision, a redeployment, and a revalidation cycle, which quickly falls behind without automation.

Get found across online search without managing another tool or agency. Book a kickoff with AI Growth Agent and go live in about a week.

Common Agent Card Implementation Pitfalls

The following numbered fixes address the most frequent Agent Card implementation failures observed across enterprise deployments.

1. Wrong file path. Serving the card at /agent-card.json or /.well-known/agent.json instead of /.well-known/agent-card.json causes silent discovery failures. Fix: confirm the exact path matches the A2A v1.0 specification and test with a direct HTTP GET.

2. Missing required fields. Omitting protocolVersion or skills causes schema validation rejection. Fix: validate against the official A2A JSON schema before deploying.

3. Authentication-gated discovery endpoint. Requiring a Bearer token to fetch the card itself prevents unauthenticated discovery. Fix: serve the card publicly and declare authentication requirements inside the card’s securitySchemes field for the agent endpoint, not the card endpoint.

4. Stale protocol version declaration. A card declaring protocolVersion: "0.3.0" after the ecosystem has moved to v1.0 signals an outdated agent and may cause routing failures. Fix: automate card updates whenever the specification version advances.

5. No bot tracking on the well-known path. Without logging agent fetches at /.well-known/agent-card.json, operators have no visibility into which agents are discovering their site or how frequently. Fix: route all requests through the bot tracking layer and review fetch logs weekly.

6. Subdomain instead of subdirectory deployment. Serving the Agent Card from a subdomain fragments domain authority. Fix: use the reverse-proxy subdirectory setup so the card inherits the parent domain’s authority.

7. Card not updated after infrastructure changes. An endpoint URL or authentication scheme that changes without a corresponding card update causes agent task failures. Fix: treat the Agent Card as a living document and tie its update cycle to infrastructure change management.

Every one of these pitfalls stems from manual configuration. AI Growth Agent removes that risk category by provisioning and maintaining the full agentic technical SEO stack automatically, including Agent Cards, Blog MCP, llms.txt, llms-full.txt, reverse-proxy subdirectory setup, and real-time bot tracking, from the first week and keeping every file current as standards evolve.

Frequently Asked Questions

How long does it take to publish a compliant Agent Card?

Creating the JSON file takes under an hour for a developer familiar with the A2A v1.0 specification. The bottleneck sits in everything around it: configuring the well-known path, setting up the reverse-proxy subdirectory, publishing the companion discovery files, validating against the schema, and wiring bot tracking to log agent fetches. For teams without dedicated engineering resources, that surrounding work typically takes days to weeks. AI Growth Agent provisions the complete stack within the first week of kickoff, with no engineering hours required from the client.

Who owns the Agent Card once it is published?

The brand owns the Agent Card and the domain it is served from. AI Growth Agent stands up the infrastructure through a reverse-proxy rewrite under a subdirectory the client controls, so the client owns the site, the content, and every discovery file on it. There is no agency dependency and no lock-in. If a client leaves, the files remain on their domain.

How does an Agent Card relate to robots.txt?

Robots.txt still does its original job and tells crawlers where to look and where to stay out. The Agent Card adds a separate layer for a different class of reader, the interactive agent, with structured information that robots.txt was never designed to carry. The correct configuration uses both files, not one or the other. Robots.txt handles crawler permissions. The Agent Card handles capability declaration and endpoint advertisement for agents that need to delegate tasks rather than simply index pages.

How do you measure whether an Agent Card is working?

The primary signal is bot traffic at the well-known path and at the MCP endpoint. AI Growth Agent’s bot tracking layer logs every agent fetch, including the bot ChatGPT uses to cite sources, so operators can see exactly which agents are discovering their site, how frequently, and which content those agents subsequently cite. Secondary signals include AI citation rate, brand mention rate across AI surfaces, and Google Search Console impressions on content served through the same subdirectory infrastructure. These four data points together give a complete picture of whether the Agent Card is driving discovery and citation.

What happens when the A2A specification updates again?

Manual Agent Card maintenance means every specification update triggers a new engineering cycle: read the spec, revise the JSON, redeploy, revalidate, and update any dependent files. For teams without dedicated engineering resources, that cycle typically falls weeks or months behind. AI Growth Agent reads new specifications as they ship and rolls updates out across every client site within the week, so brands that ship first are the ones the next wave of agents finds first.

Conclusion

With adoption more than tripling in its first year to over 150 organizations, as mentioned earlier, the A2A standard has moved into mainstream use. The standard is not experimental. It is the new front door for any site that wants to be cited and used by an agent, and the brands that publish compliant, current Agent Cards now are the ones training the next generation of models with their own narrative.

Manual Agent Card implementation creates fragile, quickly outdated infrastructure. The JSON file, the well-known path, the companion discovery files, the reverse-proxy subdirectory, the bot tracking layer, and the MCP endpoint all require ongoing maintenance as the specification evolves. No non-technical marketing team can sustain that stack without engineering support, and no engineering team benefits from spending cycles on it when an automated engine exists.

AI Growth Agent provisions the complete agentic technical SEO stack, including Agent Cards, Blog MCP, llms.txt, llms-full.txt, reverse-proxy subdirectory setup, and real-time bot tracking, automatically within the first week and keeps every file current as standards evolve. 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.