Ship Your Agent Card in 5 Minutes: A Developer's Guide to A2A Discovery

There are thousands of AI agents being built right now. Most of them are invisible. Not because they don't work — but because there's no standard way for other agents, registries, or platforms to discover what they can do. If your agent doesn't have a public capability manifest, it might as well not exist.

The fix takes about five minutes. The A2A protocol — backed by Google, the Linux Foundation, and 50+ partners including Salesforce, SAP, and LangChain — defines a simple JSON file called an Agent Card that you serve at a well-known URL. That's it. One file, one endpoint, and your agent goes from invisible to discoverable.

The Discovery Problem

Think about the early web before search engines. Websites existed, but finding them meant someone had to hand you a URL. That's where AI agents are today. Your agent might be the best invoice processor on the planet, but if another agent — or a registry like Agentry — can't programmatically find it and read what it does, no one will ever know.

The A2A protocol solves this with a pattern borrowed directly from the web: a well-known URL. Just like robots.txt tells search engines how to crawl a site, or /.well-known/openid-configuration tells auth clients where to authenticate, an Agent Card at /.well-known/agent.json tells other agents what yours can do.

What Is an Agent Card?

An Agent Card is a JSON document that describes your agent's identity, capabilities, skills, and how to interact with it. Think of it as a machine-readable business card — or robots.txt for AI agents. It follows the A2A specification and is designed to be read by other agents, registries, and developer tools.

The required fields are:

• name — Your agent's display name.
• description — A clear, concise description of what your agent does.
• version — Semantic version of your agent (e.g., 1.0.0).
• capabilities — Protocol features: streaming, pushNotifications.
• skills — What your agent can actually do, each with an ID, name, description, and tags.
• defaultInputModes / defaultOutputModes — MIME types your agent accepts and returns.
• supportedInterfaces — The endpoint URL, protocol binding (JSONRPC), and protocol version.

Optional but valuable fields include provider (your organization info), securitySchemes (authentication methods), iconUrl, and documentationUrl. The more you fill in, the higher your trust score in registries like Agentry.

The Minimal Agent Card

Here's a complete, valid Agent Card. Copy it, change the values, and you're done:

{
  "name": "Acme Invoice Agent",
  "description": "Extracts and processes invoice data from PDFs and images.",
  "version": "1.0.0",
  "supportedInterfaces": [
    {
      "url": "https://api.acme.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "defaultInputModes": ["application/pdf", "image/png", "text/plain"],
  "defaultOutputModes": ["application/json", "text/plain"],
  "skills": [
    {
      "id": "extract-invoice",
      "name": "Invoice Extraction",
      "description": "Extracts line items, totals, dates, and vendor info from invoices.",
      "tags": ["invoice", "extraction", "ocr", "accounting"]
    }
  ]
}

That's 25 lines of JSON. No SDK, no build step, no dependencies. Every field maps directly to the A2A specification. Now you just need to serve it.

Implementation in 3 Frameworks

Serving your Agent Card means making it accessible at /.well-known/agent.json over HTTPS. Here's how to do it in the three most common setups.

Express.js

const express = require('express');
const app = express();

const agentCard = {
  name: "Acme Invoice Agent",
  description: "Extracts and processes invoice data from PDFs and images.",
  version: "1.0.0",
  supportedInterfaces: [{
    url: "https://api.acme.com/a2a",
    protocolBinding: "JSONRPC",
    protocolVersion: "1.0"
  }],
  capabilities: { streaming: false, pushNotifications: false },
  defaultInputModes: ["application/pdf", "image/png", "text/plain"],
  defaultOutputModes: ["application/json", "text/plain"],
  skills: [{
    id: "extract-invoice",
    name: "Invoice Extraction",
    description: "Extracts line items, totals, dates, and vendor info from invoices.",
    tags: ["invoice", "extraction", "ocr", "accounting"]
  }]
};

app.get('/.well-known/agent.json', (req, res) => {
  res.json(agentCard);
});

app.listen(3000);

FastAPI

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

agent_card = {
    "name": "Acme Invoice Agent",
    "description": "Extracts and processes invoice data from PDFs and images.",
    "version": "1.0.0",
    "supportedInterfaces": [{
        "url": "https://api.acme.com/a2a",
        "protocolBinding": "JSONRPC",
        "protocolVersion": "1.0",
    }],
    "capabilities": {"streaming": False, "pushNotifications": False},
    "defaultInputModes": ["application/pdf", "image/png", "text/plain"],
    "defaultOutputModes": ["application/json", "text/plain"],
    "skills": [{
        "id": "extract-invoice",
        "name": "Invoice Extraction",
        "description": "Extracts line items, totals, dates, and vendor info from invoices.",
        "tags": ["invoice", "extraction", "ocr", "accounting"],
    }],
}

@app.get("/.well-known/agent.json")
async def get_agent_card():
    return JSONResponse(content=agent_card)

nginx

If your agent runs behind nginx, you can serve a static JSON file directly:

server {
    listen 443 ssl;
    server_name api.acme.com;

    location = /.well-known/agent.json {
        alias /var/www/agent-card.json;
        default_type application/json;
        add_header Access-Control-Allow-Origin *;
        add_header Cache-Control "public, max-age=3600";
    }
}

Why This Matters

Shipping an Agent Card isn't just a protocol checkbox. It has direct, compounding benefits for your agent's reach and credibility.

Discoverability

Registries like Agentry and other A2A-compatible platforms automatically scan for Agent Cards at well-known URLs. Once your card is live, you're indexed — no manual submission required. Other agents can find you programmatically, the same way search engines find websites by crawling robots.txt and sitemaps.

Trust scoring

Agentry builds trust profiles for every agent it discovers. Agents with valid, schema-compliant Agent Cards rank higher. Having provider info, authentication schemes, versioning, and well-defined skills all contribute to a higher trust score — which means higher visibility in the directory.

Interoperability

Any A2A-compatible client can discover your agent, read its capabilities, negotiate authentication, and send it tasks — all without custom integration code. Your agent becomes a first-class citizen in the multi-agent ecosystem.

Future-proofing

The A2A protocol is governed by the Linux Foundation with backing from Google, Salesforce, SAP, and 50+ major technology companies. Building on A2A means you're investing in the standard that the industry has converged on — not a proprietary format that might disappear.

How Agentry Scans for Cards

Agentry runs automated discovery cycles every 6 hours across all registered agent domains. Here's what happens during each scan:

1. Fetch — We request /.well-known/agent.json and /.well-known/agent-card.json from your domain.
2. Validate — The response is checked against the A2A Agent Card schema. Invalid cards are flagged but still indexed.
3. Diff — We compare the current card against the last snapshot. Changes to skills, capabilities, or version are tracked.
4. Score — A trust score (0–100) is computed based on weighted signals.

The trust scoring weights:

Card resolves             25 pts   // Your card is accessible
Schema valid              15 pts   // Passes A2A validation
Uptime ratio              15 pts   // Consistent availability
Domain matches URL        10 pts   // Card domain = agent endpoint
Has skills defined        10 pts   // At least one skill listed
Has provider info          5 pts   // Organization name and URL
Has auth scheme            5 pts   // Security defined
Has version                5 pts   // Semantic versioning
Has protocol version       5 pts   // A2A version declared
Response time              5 pts   // Fast card delivery

Agents are placed into tiers based on their score:

• Verified (80+) — Full trust profile, featured in search results.
• Basic (50–79) — Card resolves and validates, but missing optional fields.
• Unverified (20–49) — Card has issues or is incomplete.
• Suspicious (<20) — Card fails to resolve or has significant problems.

Get Started Now

Here's the fastest path from zero to discoverable:

1. Create your Agent Card JSON — Copy the minimal example above and fill in your agent's details.
2. Serve it at /.well-known/agent.json — Use any of the framework examples above. Make sure it returns Content-Type: application/json and allows CORS.
3. Add optional fields — Provider info, auth schemes, documentation URL, and additional skills will boost your trust score.
4. Register with Agentry — Add your agent to the directory. Our scanner will pick up your Agent Card automatically within the next discovery cycle.

That's it. Four steps, five minutes, and your agent joins the discoverable web of AI agents built on the A2A protocol. The ecosystem is growing fast — the Google A2A Codelab is a great next step if you want to build a full A2A server, and the Descope guide covers authentication patterns in depth.

The agents that are discoverable first win. Ship your card today.