Guides / agent.json a2a protocol

How to add agent.json (A2A protocol)

agent.json advertises your platform capabilities to AI agents using the Agent-to-Agent protocol. Here is how to set it up.

What is agent.json?

agent.json is a machine-readable file at /.well-known/agent.json that describes your platform capabilities using the A2A (Agent-to-Agent) protocol. It tells AI agents what your product can do, what protocols you support, and how to interact with you.

Think of it as a business card for agents — it advertises your capabilities so other agents can discover and interact with your platform programmatically.

Template

Create a file at /.well-known/agent.json:

json
{
  "name": "Your Product",
  "description": "What your product does in one sentence.",
  "url": "https://your-domain.com",
  "version": "1.0.0",
  "capabilities": {
    "protocols": ["a2a", "mcp"],
    "authentication": ["api_key", "oauth2"],
    "api_spec": "https://your-domain.com/openapi.json"
  },
  "endpoints": {
    "api": "https://api.your-domain.com/v1",
    "docs": "https://your-domain.com/docs",
    "status": "https://status.your-domain.com"
  },
  "contact": {
    "email": "api@your-domain.com",
    "docs": "https://your-domain.com/docs"
  }
}

Key fields to include

  1. name and description — Clear, specific product identity
  2. capabilities.protocols — Which agent protocols you support (a2a, mcp, etc.)
  3. capabilities.authentication — How agents can authenticate
  4. capabilities.api_spec — Link to your OpenAPI spec
  5. endpoints — Direct URLs to your API, docs, and status page

Hosting

The file must be at https://your-domain.com/.well-known/agent.json. The .well-known directory is a standard location for machine-readable metadata (like favicon.ico or robots.txt).

Make sure your web server serves it with Content-Type: application/json.

Check your score

After implementing this, scan your domain to verify the check passes and see how your score changes.

Scan your domain