A2A Agent Discovery and Agent Cards

An Agent Card helps a client find and understand a remote agent before beginning an A2A interaction.

An organization may have dozens of specialized agents: research, contracting, finance, support, logistics, and more. A client that needs contract analysis must first answer a practical question: which remote agent advertises the right capability and a compatible way to communicate?

The Agent2Agent Protocol addresses this with Agent Cards. An Agent Card is a machine-readable public description of an A2A server: its identity, purpose, supported interfaces, capabilities, skills, input and output modes, and security information. It helps clients discover candidates and prepare compatible interactions.

It is not the agent’s system prompt, hidden reasoning, memory, source code, or live availability guarantee.

Discovery is a separate phase

A2A discovery answers questions such as:

• Which remote agents are known?
• What does each one claim to do?
• Which protocol binding and version can the client use?
• What input and output modes are supported?
• What security scheme applies?
• Which advertised skill best matches the task?

After discovery, the client may rank candidates, apply policy, obtain credentials, and start an interaction. The task itself is handled through A2A messages and task operations, not through the discovery document.

Keeping these phases separate prevents a common misconception: finding an Agent Card does not delegate work.

What an Agent Card describes

In A2A v1.0, the conceptual information includes:

Identity and description. A human-readable name and description help clients and operators understand the remote agent.

Supported interfaces. These identify reachable protocol interfaces, including a URL, protocol binding, and protocol version. A client selects an interface it supports.

Capabilities. Server-level capability declarations tell the client which optional behaviors the remote agent supports.

Skills. Skills describe units of work the agent advertises. A skill can include an identifier, name, description, and other discovery metadata useful for matching.

Input and output modes. These indicate the media types or modes the agent can receive and produce, helping avoid an incompatible request.

Security schemes and requirements. These tell the client how access is protected. They describe how to authenticate or authorize; they do not embed private credentials.

Exact fields and requirements should come from the current specification and generated schema. The important architectural point is that an Agent Card describes the external interaction contract.

A conceptual example

The following simplified JSON is illustrative, not a substitute for the normative schema:

{
  "name": "Contract Review Agent",
  "description": "Reviews commercial agreements against approved playbooks.",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/contracts",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true
  },
  "defaultInputModes": ["text/plain", "application/pdf"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "contract-risk-review",
      "name": "Contract risk review",
      "description": "Finds playbook deviations and returns cited risk items."
    }
  ]
}

A production client validates the retrieved card against the current A2A schema, checks a compatible interface, evaluates security requirements, and decides whether the advertised skill fits the task.

How clients find Agent Cards

Discovery environments differ, so no single method fits every deployment. Common patterns include:

Well-known publication

A public or partner-facing server can publish its Agent Card at the standard well-known location associated with its domain. This is convenient for decentralized discovery when the client already knows the domain.

The client must still validate transport security, redirects, content type, size, schema, and server identity. A well-known path makes a document predictable; it does not make the document trustworthy.

Registry or catalog

An enterprise can maintain a governed registry of approved agents. The registry may add ownership, environment, data classification, review state, health, and tenant policy around the underlying Agent Cards.

This approach is useful when compliance requires curation or when agents are not publicly reachable. The registry should preserve the source and version of each card rather than silently rewriting claims.

Direct configuration

A workflow may configure an Agent Card URL or server interface directly. This is appropriate for a small number of stable integrations, private networks, or testing.

Direct configuration reduces search but not verification. The client still needs to confirm compatibility and policy.

Private discovery services

Large platforms may use service discovery, marketplaces, or partner directories. These can index skills and operational metadata, but they should distinguish standardized Agent Card fields from platform-specific ranking or governance fields.

Matching an agent to a task

Skill matching should use more than a keyword. Consider:

• semantic fit between the task and skill description;
• accepted input modes and expected artifacts;
• output modes required by the caller;
• compatible interface and protocol version;
• security and organization policy;
• data residency or tenant boundary;
• operational health, latency, and cost;
• confidence and need for human review.

Suppose the task is “Review this supplier agreement for deviations from our liability playbook and return cited clauses.” A generic document summarizer may match the word “review,” but the contract agent advertises the specific skill, accepts PDF input, and returns structured findings. Those distinctions should dominate selection.

Matching identifies a candidate. It does not prove the agent will succeed. Use evaluation history and runtime safeguards for that.

Discovery versus interaction

The boundary can be stated simply:

• Discovery: obtain and evaluate information about a remote agent.
• Routing: decide which candidate should receive the work.
• Delegation: establish responsibility, constraints, and expected result.
• Interaction: exchange A2A messages, tasks, status, and artifacts.

A registry may assist discovery. A router may rank candidates. A coordinator may delegate. A2A then provides the external collaboration contract. These components can live in one application, but they remain different responsibilities.

Security and trust

Agent Cards are usually designed for discovery, so assume their contents may be visible. Never place secrets, private prompts, access tokens, internal reasoning, or sensitive operational details in a card.

Treat a retrieved card as untrusted input:

• require HTTPS for remote publication;
• validate the schema and size;
• restrict redirects;
• verify the expected domain or registry source;
• allowlist agents for sensitive workflows;
• review security schemes before sending data;
• apply organization and tenant policy;
• cache with expiry and refresh behavior;
• record the card version or fingerprint used for a task.

An attacker could publish a card that impersonates a known agent or advertises a misleading skill. User-visible and audit records should preserve the selected agent’s actual identity and endpoint.

Credentials are obtained through the declared security mechanism and protected outside the card. A security declaration is not proof that access has been granted.

Versioning and change

Agent capabilities evolve. A skill may be renamed, an interface upgraded, or an input mode removed. Clients should not assume a card is permanent.

Useful cache behavior includes:

• keying by canonical server identity;
• storing retrieval time and source;
• revalidating after expiry;
• comparing fingerprints or versions;
• invalidating on interaction incompatibility;
• retaining the exact discovery evidence used for important tasks.

If a required skill disappears, fail clearly or route through an explicit fallback policy. Do not send the task to an unrelated skill because the names look similar.

Protocol version compatibility also matters. A client should choose a supported interface from supportedInterfaces and avoid guessing that every endpoint implements the newest binding.

Agent Cards do not describe internal architecture

A remote agent can be implemented as:

• one model and a few tools;
• a deterministic workflow;
• a supervisor with sub-agents;
• a human-in-the-loop service;
• a non-LLM business application exposing an agent-like task interface.

The caller should not need to know. A2A standardizes the external collaboration surface, not the private implementation.

This encapsulation is valuable: the provider can change models, prompts, tools, or orchestration while preserving the advertised skill and interaction contract.

Operational metadata belongs beside discovery

An Agent Card describes protocol-facing capabilities. Production routing may also need dynamic evidence:

• current health;
• region;
• queue depth;
• service level objective;
• recent task success;
• estimated cost;
• maintenance state.

Do not invent these as standardized Agent Card fields unless the specification defines them. Store platform-specific metadata in a registry or routing layer with clear provenance. This keeps the protocol contract accurate and the operational decision current.

Common mistakes

• Treating discovery as automatic delegation.
• Using an Agent Card as a private prompt store.
• Assuming advertised skill equals verified competence.
• Ignoring supported interfaces and protocol versions.
• Sending sensitive data before evaluating security requirements.
• Trusting any card found at a plausible URL.
• Caching a card forever.
• Mixing private registry fields into the standard schema.
• Routing only by skill name.
• Assuming A2A exposes the remote agent’s internal tools or reasoning.

A practical client sequence

1. Receive a task that may require a remote specialist.
2. Query an approved registry or known Agent Card source.
3. Validate cards and supported interfaces.
4. Filter by security, tenant, data, and protocol policy.
5. Match the task to advertised skills and modes.
6. Rank candidates with operational evidence.
7. Select one candidate and obtain authorization.
8. Create the A2A message or task with explicit constraints.
9. Record the card source and selected interface in the trace.
10. Evaluate the returned outcome independently of the discovery claim.

My Take

Agent Cards are most useful when treated like API discovery plus service identity—not like résumés that can be trusted at face value. They make a remote agent understandable enough to consider, but capability claims still need governance and evidence.

The clean architecture is a pipeline: discover, validate, filter, match, select, authorize, then interact. Keeping those steps visible prevents the registry from becoming an invisible super-router and prevents a public metadata document from becoming a misplaced security boundary.

Sources

• A2A Protocol Specification v1.0.0
• A2A Definitions
• What’s New in A2A v1.0
• [Agent2Agent Protocol Explained](/agent2agent-protocol-explained/)