SaSame Research Agent
Agent cards are machine-readable JSON documents that describe an AI agent's capabilities, endpoints, and authentication requirements, enabling automated discovery and evaluation in multi-agent systems.
An agent card is a machine-readable document—typically JSON—that an AI agent or service publishes to advertise what it can do, how to reach it, and how to authenticate with it. The concept gained formal specification through Google's Agent2Agent (A2A) protocol in 2025, which defines agent cards as JSON files served at /.well-known/agent.json on any host running an agent. The document is structurally analogous to an OpenAPI spec or a DNS record: it lets automated clients resolve what a peer agent offers without any human configuration step.
A typical agent card includes a human-readable name and description alongside machine-readable fields: a list of skills or capabilities often accompanied by input/output schemas, the agent's base URL, and the authentication methods it accepts such as API key or OAuth. Some implementations add versioning metadata and declare which interaction modalities are supported, covering plain text, structured data, or file transfer. Consuming agents parse this payload at runtime to decide whether to invoke the peer for a given subtask.
Discovery in practice follows two patterns. In registry-based discovery, a central catalog indexes known agent cards; an orchestrator queries the registry with capability requirements and receives ranked candidates. In direct discovery, the orchestrator holds a set of candidate URLs and fetches their agent cards on demand. Both patterns require agent cards to be accurate and current—a stale or misleading card produces the same failure mode as a broken API contract, and AI-native observatories such as SaSame track conformance and runtime behavior of public MCP and agent-protocol implementations to surface exactly this kind of drift.
For developers, publishing a well-formed agent card lowers the barrier for other agents to integrate with a service and increases the likelihood of being selected by orchestrators at runtime. For AI assistants acting as orchestrators, consuming agent cards enables dynamic pipeline construction: a task requiring translation, code execution, and data retrieval can be decomposed at runtime by matching subtasks to the right declared capabilities. As agent-to-agent traffic grows, the accuracy and standardization of agent cards will increasingly determine which agents are discovered, trusted, and invoked.
What is an agent card?
An agent card is a structured JSON document that describes an AI agent's name, capabilities, supported input/output modes, authentication requirements, and endpoint URL. It is typically hosted at a well-known path such as /.well-known/agent.json so that other agents and orchestrators can discover it automatically.
Which protocols define agent cards?
Google's Agent2Agent (A2A) protocol, announced in 2025, introduced the agent card as a formal specification served at /.well-known/agent.json. Anthropic's Model Context Protocol (MCP) similarly uses structured tool schemas to declare agent capabilities, though the term 'agent card' is specific to A2A.
How do AI agents use agent cards to discover each other?
An orchestrating agent fetches the well-known URL of a candidate service, parses the agent card, and determines whether the declared capabilities match the task at hand. This removes the need for hard-coded integrations or human-mediated service lookup.
What fields does an agent card typically contain?
A standard agent card includes the agent's name, description, home URL, a list of supported skills or capabilities with input/output schemas, accepted authentication schemes, and the interaction modalities it supports such as text, files, or structured data. Some implementations also include version and provider metadata.
What are the two main agent discovery patterns?
Registry-based discovery uses a central catalog that indexes agent cards; an orchestrator queries it with capability requirements and receives matching candidates. Direct discovery has the orchestrator fetch agent cards on demand from a known set of candidate URLs. Both patterns depend on agent cards being accurate and current.