Mnemoverse Docs

Appearance

Edward Izgorodin·Published Jun 19, 2026

The A2A Agent Card: How Agents Discover Each Other ​

TL;DR

  • An Agent Card is a JSON document an agent publishes so other agents can discover its skills, endpoint, and authentication — and decide whether and how to call it.
  • The recommended home is a well-known URI: https://{domain}/.well-known/agent-card.json (RFC 8615). That reduces "connect to this agent" to "know its domain."
  • The card carries identity, a service endpoint, a list of skills, supported input/output modes, and auth requirements. The A2A spec also allows the card to be cryptographically signed, so a receiver can verify who issued it.
  • The card says what an agent can do and how to reach it. It does not give two connected agents shared memory — that stays a separate layer.

If two AI agents are going to work together, one has to find the other first — and learn what it can do, where to send work, and how to authenticate. In the A2A (Agent2Agent) protocol, the answer to all three is one file: the Agent Card.

What an Agent Card Is ​

An Agent Card is a JSON document that describes an agent's identity, capabilities, skills, service endpoint, and authentication requirements. A client agent fetches it to decide whether a remote agent is relevant for a job and how to interact with it. The A2A specification defines it as the document that lets clients handle "discovering suitable agents and configuring their interactions."

It is the first of the protocol's five primitives — Agent Card, Task, Message, Artifact, Part — and the only one you reach for before any work happens. The other four describe a conversation already in progress; the card is how the conversation becomes possible at all.

A useful mental model: the Agent Card is an agent's business card crossed with an API description. The business-card half is human-legible (name, description, who provides it). The API half is machine-actionable (endpoint, skills, auth) — enough for another agent to construct a valid call without a human in the loop.

Where the Agent Card Lives: the well-known URI ​

A2A servers make the card discoverable at a standardized location. The recommended path is:

text
https://{agent-server-domain}/.well-known/agent-card.json

This follows RFC 8615, the well-known URI convention that already hosts files like /.well-known/security.txt. Earlier spec versions (before v0.3.0) used /.well-known/agent.json, and some early deployments may still serve that path, so a robust client checks for both.

The design payoff, described in the agent-discovery topic doc, is that the well-known URI reduces discovery to knowing the agent's domain. If you know the domain, you know where the card is; if you have the card, you can call the agent. That property is what makes a single link enough to introduce one agent to another.

What's Inside: skills, endpoint, auth ​

A card is more than an address. The fields that matter for an automated caller:

  • Identity — name, description, provider, and version. Human-readable, but also how a registry indexes the agent.
  • Service endpoint and transports — the URL to send requests to, and which transport bindings the agent supports (for example a JSON-RPC interface). This is the where.
  • Skills — the heart of the card. Each skill is an AgentSkill object with an id, name, description, tags, examples, and the inputModes and outputModes it accepts and returns (declared as MIME types, such as text/plain or application/json). Skills are how a calling agent answers "can this agent do the thing I need?" — does it handle refunds, can it query inventory, can it summarize a document.
  • Authentication — the schemes a client must satisfy, such as HTTP Bearer tokens or OAuth 2.0 (the card follows OpenAPI 3.0 security-scheme conventions). The spec recommends obtaining credentials out of band rather than embedding static secrets in the card itself.

That last point matters for anyone publishing a card. The card is meant to be fetched widely; it should advertise which auth a caller needs, not contain the secret that grants it.

A Minimal Agent Card, Annotated ​

The fields above are easier to read as one document. Here is an illustrative card for a support-triage agent — the values are invented, but every field name and shape follows the AgentCard object in the A2A specification (§4.4.1):

json
{
  "protocolVersion": "0.3.0",
  "name": "Acme Support Triage",
  "description": "Classifies inbound support tickets and drafts a first reply.",
  "url": "https://agents.acme.com/support-triage",
  "provider": { "organization": "Acme, Inc.", "url": "https://acme.com" },
  "version": "1.4.0",
  "documentationUrl": "https://acme.com/agents/support-triage",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": false
  },
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["application/json"],
  "skills": [
    {
      "id": "triage-ticket",
      "name": "Triage a support ticket",
      "description": "Assigns a category, priority, and suggested owner to a ticket.",
      "tags": ["support", "classification"],
      "examples": ["I was charged twice this month."],
      "inputModes": ["text/plain"],
      "outputModes": ["application/json"]
    }
  ],
  "securitySchemes": {
    "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
  },
  "security": [{ "bearer": [] }]
}

Why each field is there — and why a caller needs it:

  • protocolVersion, name, description, provider, version — identity. These are required (§4.4.1, with provider as an AgentProvider, §4.4.2). They tell a calling agent, and any registry that indexes the card, who issued it and which build they are talking to.
  • url — the A2A service endpoint, required. It is the single address a client sends tasks to; the spec's interfaces array lets an agent advertise additional transports, but one url is enough to call it.
  • capabilities — what the connection supports: streaming (incremental updates), pushNotifications (callbacks), stateTransitionHistory (§4.4.3). A caller reads this to decide whether it can subscribe to progress or must poll.
  • defaultInputModes / defaultOutputModes — the MIME types the agent accepts and returns by default; a skill's own inputModes/outputModes override them. This is how the caller knows to send text/plain and parse application/json.
  • skills — the AgentSkill objects a caller actually selects on (§4.4.5). The id is the stable handle used to invoke the skill; tags and examples make the skill findable and testable.
  • securitySchemes / security — the auth a caller must satisfy, declared in OpenAPI style (here, HTTP Bearer with a JWT). Note what is absent: no token. The card advertises the scheme; the spec wants the credential obtained out of band (§4.5), so a card that travels never leaks a secret.

A reader can take this shape, swap the values, host it at the well-known path, and have a valid, discoverable agent. The one field deliberately left out here — signatures — is what turns this from a readable claim into a verifiable one.

Signed Agent Cards and Trust ​

If a card is a fetch-me-anywhere file, why trust it? Because A2A allows the card to be signed. The specification supports attaching JWS (JSON Web Signature) signatures to an Agent Card, so a receiving agent can verify that the card was issued by the domain owner and has not been altered in transit.

This is the difference between a claim and a credential. An unsigned card asserts "I am the support agent for example.com." A signed card lets the receiver check that assertion against the domain's key before sending it a task. For a card that travels — pasted into a chat, shared in a directory, embedded in a link — that verification is the basis for treating it as a connection token rather than an unverified URL.

How Discovery Actually Works ​

The well-known URI is the default, not the only route. A2A describes three discovery strategies:

  1. Well-known URI — fetch the card from the predefined path on the agent's domain. Standardized and crawlable; best when you know the domain.
  2. Registries and catalogs — query a curated directory of agents (enterprise-internal, public, or domain-specific). Best when you are searching for an agent that can do X, not a specific known one.
  3. Direct configuration — the client is handed the card URL, or the card contents themselves, up front. Best for private or pre-arranged integrations.

These are not exclusive. A registry entry typically points at a well-known card; a direct configuration is just someone handing you the URL the well-known path would have served. The common denominator is the card: every route ends with a client holding one and reading its skills.

What the Agent Card Does Not Carry ​

The card tells a caller what an agent can do and how to reach it. It deliberately stops there. A2A moves tasks and messages between opaque agents — the spec is explicit that agents collaborate "without needing access to each other's internal state, memory, or tools."

So two agents that discover each other through their cards and start exchanging tasks still share no memory. Each remembers its own side. Nothing in the card, or in the protocol, gives them a common place to write down what they learned together, or lets one pick up where the other left off in a later session. That gap — connected, but not remembering together — is not a flaw in the Agent Card. It is the boundary of what the card is for.

Where Mnemoverse Fits ​

The Agent Card solves discovery and connection: find the agent, learn its skills, authenticate, send work. The layer it leaves open is shared, persistent memory between the agents it connects — what they should remember about each other and about the work, across tasks and across sessions.

That is the layer Mnemoverse provides: a memory two agents can both read from and write to, sitting outside either agent and outliving any single task. The card is how agents meet; a shared memory is how a meeting turns into a working relationship. The two compose without overlap — A2A for the wire, a memory layer for what persists — because the protocol was designed to leave that second layer to someone else. For how the protocol draws that line, see A2A Protocol, Explained and Shared Memory for Multi-Agent Systems.

Common questions ​

What is an A2A Agent Card? An Agent Card is a JSON document that describes an agent's identity, skills, service endpoint, and authentication requirements. Other agents fetch it to discover whether a remote agent is relevant and how to call it. It is the discovery primitive of the A2A (Agent2Agent) protocol.

Where is the Agent Card hosted? The recommended location is a well-known URI on the agent's domain: https://{domain}/.well-known/agent-card.json, following RFC 8615. Earlier drafts of the spec used /.well-known/agent.json, so some deployments still serve that path. Registries and direct configuration are alternative discovery methods.

What is inside an Agent Card? Identity (name, description, provider, version), the service endpoint URL and supported transports, a list of skills (each with an id, name, description, tags, and examples), input and output modes, and the authentication schemes a client must satisfy.

What is a signed Agent Card? The A2A specification allows an Agent Card to carry JWS signatures. A receiving agent can verify the signature to confirm the card was issued by the domain owner and was not tampered with — the trust basis for treating a card as a shareable connection token.

How does an agent discover another agent with A2A? Three ways: the well-known URI (fetch the card from a predefined path on the domain), a registry or catalog (query a curated directory of agents), or direct configuration (the client is given the card URL or contents up front). The well-known path reduces discovery to knowing the agent's domain.

Does the Agent Card give two agents shared memory? No. The card advertises what an agent can do and how to reach it; A2A by design moves tasks and messages between opaque agents without exposing internal state or memory. Shared persistent memory between connected agents is a separate layer.

Mnemoverse Library — persistent memory for AI agents. By Edward Izgorodin. Last updated 2026-06-19.