Agentry / Blog / How to Create an A2A Agent Card
Tutorial

How to Create an A2A Agent Card in 5 Minutes

By the Agentry Team · · 10 min read

If your AI agent doesn't have an Agent Card, it's invisible — to other agents, to orchestrators, and to developers looking for exactly what you built.

The A2A Agent Card is a small JSON file. You host it at a well-known URL on your domain. It takes five minutes to create. And it's the difference between your agent being findable in the growing agent-to-agent ecosystem or being a local secret nobody can reach.

This guide walks you through exactly what an A2A Agent Card is, why it matters, and how to create, host, validate, and list yours — with a complete, copy-paste-ready agent-card.json example.

What Is an A2A Agent Card?

An A2A Agent Card is a standardized JSON metadata document that describes your AI agent: what it does, how to reach it, what it can accept as input, what it returns as output, and how to authenticate with it.

It lives at a predictable, well-known path on your domain:

URL 
https://yourdomain.com/.well-known/agent-card.json

The older path /.well-known/agent.json is also supported for backward compatibility. Agentry checks both.

The format follows the Agent2Agent (A2A) protocol, an open standard originally introduced by Google and now maintained under The Linux Foundation's A2A Protocol project. The protocol standardizes how AI agents communicate with each other — and the Agent Card is how they introduce themselves.

Think of it as your agent's digital business card, its API documentation, and its entry in a global phone book — all in one 30-line JSON file.

Why Your Agent Needs an A2A Card

1. Discovery

Agent orchestrators — systems that coordinate multiple AI agents to complete complex tasks — query /.well-known/agent-card.json before routing work to an agent. If that endpoint doesn't exist, your agent doesn't get called. Period.

The same applies to directories like Agentry, where developers search for agents by capability. An A2A card tells the registry what your agent actually does, making it searchable by skill, input type, output type, and capability.

2. Interoperability

The A2A protocol uses JSON-RPC 2.0 over HTTPS — standard, well-understood technology. When your agent publishes a valid Agent Card, any A2A-compliant client or orchestrator can discover it, understand its interface, and begin sending it tasks without any custom integration work on either side.

This is the agent ecosystem equivalent of having a public REST API with proper OpenAPI documentation. Except it's even more structured: the A2A spec defines the exact fields, so any compliant consumer can read any compliant Agent Card without needing to decode proprietary formats.

3. Trust

The A2A card signals that your agent is production-ready and operated by a real team. It includes authentication requirements, versioning, and provider information — all the signals that tell other developers and orchestrators "this is a legitimate, maintained service."

On Agentry, agents with a valid A2A card receive a trust score boost — going from 0/100 to 25+ immediately, with additional points available for documentation, verified ownership, and active status. Agents with higher trust scores rank higher in search results and are recommended more frequently.

4. Future-proofing

The A2A protocol is gaining adoption across the AI agent ecosystem. As agent-to-agent communication becomes standard infrastructure, the /.well-known/agent-card.json endpoint will be as expected as robots.txt was for web crawlers. Getting your card in place now means you're ready before the ecosystem mandates it.

The A2A Agent Card JSON Structure

Here's every field you need to know, with annotations:

agent-card.json — annotated 
{
  // Required — human-readable name of your agent
  "name": "string",

  // Required — what your agent does (appears in search results)
  "description": "string",

  // Required — how other agents can reach yours
  "supportedInterfaces": [
    {
      "url": "https://yourdomain.com/a2a/v1",
      "protocolBinding": "JSONRPC",   // or "GRPC" or "HTTP+JSON"
      "protocolVersion": "1.0"
    }
  ],

  // Optional — your company/organization info
  "provider": {
    "organization": "Your Company",
    "url": "https://yourdomain.com"
  },

  // Required — semver version of your agent
  "version": "1.0.0",

  // Optional — link to your full API docs
  "documentationUrl": "https://docs.yourdomain.com",

  // Optional — URL to a square icon image
  "iconUrl": "https://yourdomain.com/icon.png",

  // Required — what optional A2A features your agent supports
  "capabilities": {
    "streaming": false,            // Server-Sent Events support
    "pushNotifications": false,    // async webhook callbacks
    "stateTransitionHistory": false
  },

  // Optional — authentication schemes your agent requires
  "securitySchemes": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key"
    }
  },

  // Required — default accepted input formats (MIME types)
  "defaultInputModes": ["text/plain", "application/json"],

  // Required — default output formats (MIME types)
  "defaultOutputModes": ["text/plain", "application/json"],

  // Required — list of specific skills/capabilities your agent offers
  "skills": [
    {
      "id": "unique-skill-id",
      "name": "Skill Display Name",
      "description": "What this skill does",
      "tags": ["tag1", "tag2"],
      "examples": ["Example prompt that triggers this skill"],
      "inputModes": ["text/plain"],
      "outputModes": ["text/plain"]
    }
  ]
}

The spec is maintained at a2a-protocol.org and the source repository lives at github.com/a2aproject/A2A.

Complete Example: A Realistic agent-card.json

Here's a complete, realistic Agent Card for a customer support AI agent. Copy this, modify the values, and you're done.

agent-card.json 
{
  "name": "SupportBot Pro",
  "description": "An AI agent that handles customer support tickets for SaaS products. Classifies issues, drafts responses, escalates to humans when needed, and integrates with Zendesk and Intercom.",
  "supportedInterfaces": [
    {
      "url": "https://api.supportbotpro.com/a2a/v1",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "SupportBot Inc.",
    "url": "https://supportbotpro.com"
  },
  "version": "2.1.0",
  "documentationUrl": "https://docs.supportbotpro.com/api",
  "iconUrl": "https://supportbotpro.com/assets/icon-512.png",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": false
  },
  "securitySchemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  },
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "ticket-triage",
      "name": "Ticket Triage",
      "description": "Classifies incoming support tickets by urgency, category, and required team. Returns a structured triage object with routing recommendation.",
      "tags": ["support", "triage", "classification", "customer-service"],
      "examples": [
        "I can't log in to my account — it's been broken since yesterday",
        "How do I export my data as CSV?",
        "I was charged twice this month"
      ],
      "inputModes": ["text/plain", "application/json"],
      "outputModes": ["application/json"]
    },
    {
      "id": "draft-response",
      "name": "Draft Support Response",
      "description": "Generates a draft reply to a customer support ticket, matching the product's tone of voice. Can incorporate knowledge base articles and past resolution history.",
      "tags": ["support", "drafting", "response", "customer-service"],
      "examples": [
        "Draft a response to a billing dispute",
        "Write a reply for a user who can't reset their password"
      ],
      "inputModes": ["application/json"],
      "outputModes": ["text/plain", "text/html"]
    },
    {
      "id": "escalation-decision",
      "name": "Escalation Decision Engine",
      "description": "Evaluates a support conversation and determines whether it should be escalated to a human agent, and if so, what priority level and team.",
      "tags": ["support", "escalation", "routing"],
      "examples": [
        "Should this conversation be escalated to billing?",
        "Is this ticket urgent enough for a senior support agent?"
      ],
      "inputModes": ["application/json"],
      "outputModes": ["application/json"]
    }
  ]
}

This file checks every required field and adds several optional ones that meaningfully improve trust scores and discoverability. Save it as agent-card.json.

Step-by-Step: How to Create and Deploy Your Agent Card

Step 1: Define Your Agent's Capabilities

Before writing any JSON, answer these questions:

Take 10 minutes with these questions. The answers map directly to the JSON fields.

Step 2: Create the agent-card.json File

Start with the complete example above and swap in your agent's values. A few tips:

Step 3: Host It at /.well-known/agent-card.json

The A2A spec requires that the Agent Card be accessible at:

URL 
https://yourdomain.com/.well-known/agent-card.json

The /.well-known/ path is an IETF-standard location for metadata files, the same convention used by /.well-known/openid-configuration and /.well-known/security.txt.

For most frameworks, this means:

Framework examples 
# Express.js
app.get('/.well-known/agent-card.json', (req, res) => {
  res.sendFile(path.join(__dirname, 'public', 'agent-card.json'));
});
# The older path /.well-known/agent.json is also supported for backward compatibility. Agentry checks both.
app.get('/.well-known/agent.json', (req, res) => {
  res.sendFile(path.join(__dirname, 'public', 'agent-card.json'));
});

# Django (urls.py)
path('.well-known/agent-card.json', serve_agent_card_view),
path('.well-known/agent.json', serve_agent_card_view),  # backward compat

# Next.js (app/router)
# Put the file at: public/.well-known/agent-card.json
# It's served automatically

# Nginx (static file)
location /.well-known/agent-card.json {
    alias /var/www/agent-card.json;
    default_type application/json;
}
# The older path /.well-known/agent.json is also supported for backward compatibility. Agentry checks both.
location /.well-known/agent.json {
    alias /var/www/agent-card.json;
    default_type application/json;
}

Required headers:

HTTP headers 
Content-Type: application/json
Access-Control-Allow-Origin: *

Important: The CORS header is critical. Agent orchestrators running in other domains will fetch this file — if CORS is blocked, they can't read it.

Verify it's live:

bash 
curl -I https://yourdomain.com/.well-known/agent-card.json
# Should return: HTTP/2 200, Content-Type: application/json

Step 4: Validate with Agentry's Tool

Before listing your agent anywhere, validate your card. Agentry provides a free validator at agentry.com/developers/ that checks:

Paste your JSON or enter your domain URL, and the validator returns a detailed report. Errors are shown with line references and fix suggestions. This step catches mistakes — like a missing protocolVersion or an unreachable endpoint URL — before they break agent-to-agent integrations downstream.

Step 5: List Your Agent on Agentry

Once your card validates, list your agent on Agentry's registry. Listing is free. Here's what happens after you submit:

  1. Agentry fetches your /.well-known/agent-card.json and indexes the contents
  2. Your agent appears in search results, filterable by skill, input mode, and trust score
  3. You receive a listing URL you can share and link to
  4. Your trust score is calculated (more on this below)
  5. Other developers and orchestrators can find your agent and start building integrations

Understanding Agentry Trust Scores

Agentry scores every listed agent on a 100-point scale. The score reflects how complete, verifiable, and production-ready the agent's listing is.

Trust Score Signals 
Valid A2A Agent Card                     +25
Verified domain ownership                +15
Documentation URL present and reachable   +10
Icon URL present                           +5
3+ defined skills with descriptions       +10
Skills include usage examples             +10
Provider info (organization + URL)         +5
Streaming capability enabled               +5
Authentication scheme declared            +10
Version history (multiple versions)        +5

An agent with no A2A card starts at 0. An agent with a complete, well-formed card and verified ownership can hit 85–90 on day one.

Why does this matter? Agentry surfaces higher-trust agents first in search results. When an orchestrator is choosing between two agents that can both handle a task, trust score is a meaningful tiebreaker. And when a developer is evaluating your agent for integration, a high trust score is a signal they look for before committing.

Quick win: Adding your A2A card is the highest-ROI action you can take on your Agentry listing — it's a 25-point jump in under 10 minutes.

Common Mistakes to Avoid

Forgetting CORS headers. Orchestrators will fail to fetch your card silently. Always set Access-Control-Allow-Origin: * on the endpoint.

Using localhost in the url field. The supportedInterfaces[].url must be a public, production URL — not http://localhost:3000. Update this before deploying.

Vague skill descriptions. "Does stuff with text" helps no one. Write descriptions as if you're explaining to a developer what the skill is good for, and what they should send it.

Forgetting to update version. When you change your agent's capabilities, increment the version. Downstream consumers use version to detect breaking changes.

Setting streaming: true without implementing SSE. This will cause integration failures. Only declare capabilities you actually support.

Serving agent-card.json with the wrong Content-Type. Some web servers default to text/plain for .json files. Check your server config.

What Comes Next

Once your Agent Card is live and your listing is on Agentry, a few things are worth doing:

Conclusion

An A2A Agent Card is one of the simplest things you can add to an AI agent, and one of the most impactful for discoverability and interoperability. The protocol — maintained at a2a-protocol.org and sourced at github.com/a2aproject/A2A — is an open standard backed by Google and The Linux Foundation. The ecosystem is growing. Agents without cards will be left behind.

The whole process — write the JSON, host it, validate it, list it — takes under 10 minutes.

Use Agentry's free A2A card generator to skip the JSON-writing step entirely. Answer a few questions, get a valid card, copy it to your server, and you're listed.

A2A Agent Card A2A Protocol Agent Card JSON Tutorial Agent Discovery

Make Your Agent Discoverable

Create your Agent Card, validate it with our free tool, and list your agent on Agentry — the first protocol-aware directory for the agent economy.

List Your Agent Developer Tools

Related Articles