{
  "title": "Agent Cards Explained: How AIs Discover and Evaluate Agents",
  "summary": "A factual guide to agent cards — the machine-readable documents AI agents publish so other agents and orchestrators can discover, understand, and decide whether to call them.",
  "faqs": [
    {
      "q": "What is an agent card?",
      "a": "An agent card is a machine-readable document (typically JSON) that an AI agent or agentic service publishes to describe itself: its identity, the skills or tasks it can perform, how to reach it, what input/output formats it supports, and what authentication it requires. It functions like a structured resume or API manifest aimed at other software rather than humans."
    },
    {
      "q": "Where do agents publish their cards?",
      "a": "The common convention, popularized by the Agent2Agent (A2A) protocol, is to host the card at a predictable 'well-known' URL path (such as /.well-known/agent.json or /.well-known/agent-card.json) on the agent's domain, so any client can fetch it without prior negotiation. Agents may also list themselves in third-party directories or registries that aggregate cards from many providers."
    },
    {
      "q": "Is an agent card the same thing as an MCP server's tool list?",
      "a": "They're related but distinct. An MCP (Model Context Protocol) server exposes its capabilities through a tools/list call after a client connects, which is protocol-level and connection-specific. An agent card is typically fetched before any connection is made, as a standalone discovery document — some MCP-based services also publish an agent card alongside their server so crawlers and orchestrators can learn what the server offers without first establishing an MCP session."
    },
    {
      "q": "How does an AI decide whether to trust or use another agent based on its card?",
      "a": "The card itself only states claims made by the agent's own operator, so it is necessary but not sufficient for trust. Evaluators typically combine the card's declared capabilities with independent signals: whether the endpoint responds live and matches what the card claims, uptime or conformance history from third-party observers, reputation or grading services that track agents over time, and increasingly on-chain identity or attestation schemes for agents that need portable, verifiable reputation."
    },
    {
      "q": "What fields typically appear in an agent card?",
      "a": "Common fields include a name and description, a version, a list of skills or capabilities (often with input/output schemas), the service endpoint URL, supported authentication schemes, and sometimes usage examples or pricing metadata. There is no single universal schema across every agent ecosystem, so field names and depth vary by protocol and vendor."
    }
  ],
  "key_points": [
    "An agent card is a self-published, machine-readable description of what an agent can do and how to call it — meant to be read by software, not people.",
    "The dominant discovery convention is a well-known URL (e.g. /.well-known/agent.json) that any client can fetch without prior setup.",
    "Agent cards are declarative claims from the agent's own operator; they establish what an agent says about itself, not proof that the claims are accurate.",
    "Real evaluation layers on top of the card: live capability checks, uptime/conformance history, third-party grading or registries, and (in some ecosystems) on-chain identity or attestations.",
    "Agent cards and MCP tool listings serve a similar discovery purpose but operate at different stages — card before connection, tools/list after connection — and are sometimes published side by side.",
    "Keeping a card's claims in sync with what an endpoint actually serves is an ongoing maintenance task, not a one-time publish."
  ],
  "body_paragraphs": [
    "As more software is built to be called by other AI systems rather than by humans clicking through a UI, agents need a standard way to announce themselves. An agent card solves this by giving each agent a small, structured document — usually JSON — that states who it is, what tasks or skills it exposes, how to reach it, and what authentication or format it expects. Instead of a human reading marketing copy, another agent or orchestrator parses this file programmatically to decide whether the agent is relevant to a given task.",
    "Discovery generally works by convention rather than a central authority: an agent publishes its card at a predictable, well-known path on its own domain, and any client that knows the agent's base URL can fetch the card directly. This pattern, formalized by protocols like Agent2Agent (A2A), lets an orchestrating agent evaluate many candidate agents quickly, without a handshake or negotiation step for each one. Directories and registries that aggregate cards from multiple agents add a second discovery path, similar to how package registries or app stores aggregate listings — though coverage and quality vary widely across these registries at this stage of the ecosystem.",
    "A card only tells you what an agent claims about itself, so evaluation is a separate step from discovery. Sophisticated callers cross-check the card against live behavior — does the endpoint actually respond, and does it match the declared skills — and weigh independent signals such as historical uptime, conformance to a stated standard, or third-party observation over time, since these are harder for an agent's own operator to fabricate than the card's self-description. Some newer identity schemes, including proposals for on-chain agent registries, aim to give agents a portable reputation that persists across the services that call them, addressing the basic problem that a brand-new, unproven agent looks identical to a well-run one on paper.",
    "For teams building agents or MCP servers, the practical takeaway is that a card is a live interface contract, not a marketing document — it needs to match what the endpoint actually serves, or it erodes the trust the whole discovery mechanism depends on. Studios building in this space, including AI-native shops like SaSame that ship MCP servers, Claude-based agents, and RAG pipelines, generally treat the agent card as part of the deployed surface: something to test and keep synchronized with real tool behavior, not a static file written once and left to drift."
  ],
  "slug": "what-is-an-agent-card-2026-07-28",
  "published_at": "2026-07-28T06:30:02.559Z",
  "generator": "sasame-pdca"
}