How to Build & Host a Compliant A2A Agent Card (agent-card.json)

What is an A2A Agent Card?

In the Agent2Agent (A2A) protocol, an Agent Card is the machine-readable manifest hosted at /.well-known/agent-card.json that describes an autonomous agent's capabilities, interface bindings, and skills.

While early v0.x experimental drafts used agent.json, the standard v1.0 specification standardizes on agent-card.json for singular agents and agents.json for domains hosting multi-agent registries.

Required JSON Schema Structure

{
  "name": "Customer Support Triage Agent",
  "description": "Categorizes incoming tickets and generates diagnostic summaries.",
  "version": "1.0.0",
  "documentationUrl": "https://example.com/docs",
  "provider": {
    "organization": "Acme SaaS Inc.",
    "url": "https://example.com"
  },
  "supportedInterfaces": [
    {
      "url": "https://agent.example.com/a2a/v1",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": ["application/json"],
  "defaultOutputModes": ["application/json"],
  "skills": [
    {
      "id": "triage_ticket",
      "name": "Ticket Triage",
      "description": "Assigns priority and tags to user inquiries.",
      "tags": ["support", "nlp"],
      "examples": ["Triage high priority billing issue for account 1042"]
    }
  ]
}

Hosting Best Practices

• CORS Headers: Ensure your server returns Access-Control-Allow-Origin: * on /.well-known/agent-card.json so browser-based and web agents can inspect it.
• Content-Type: Always serve with Content-Type: application/json; charset=utf-8.
• Validate with ActionGuard: Use ActionGuard.ai to automatically verify your agent card and generate an embeddable trust badge.