agent.json Examples: Copy-Paste Blocks for Public Agent Identity

agent.json examples on this page are copy-paste starting points for a public identity record: the name, the operator, the official endpoints, and the proof links. They are examples. They are not a Headless Domains schema dump, and they are not an A2A Agent Card.

If you need the definition, read what agent.json is. If you are choosing among an Agent Card, a manifest, and a skill file, use Agent Card vs agent.json vs SKILL.md. This page only shows blocks you can adapt, then check against the schema your client actually reads.

The filename is not a universal standard. The MCP specification does not define agent.json. Match every field name to the schema your client reads, including the Headless Domains manifest when that is the schema you ship. Paste these blocks only after that match.

Which block to copy

Minimal identity block

Start small. Name the agent and point at the stable records. Replace every atlas.agent value before you publish.

{
  "agent_json_version": "public-identity-example.v1",
  "identity": {
    "domain": "atlas.agent",
    "canonical_manifest": "https://atlas.agent/.well-known/agent.json",
    "display_name": "Atlas Procurement Agent",
    "purpose": "Find approved suppliers and request quotes.",
    "status": "active",
    "version": "1.0.0"
  },
  "links": {
    "skill_md": "https://atlas.agent/SKILL.md",
    "llms_txt": "https://atlas.agent/llms.txt",
    "directory_profile": "https://agents.headlessdomains.com/atlas.agent"
  }
}

Ownership block

Another agent needs a public route for support, abuse, and security notices. Dates in the sample below are placeholders. Set last_reviewed to the day you checked your file.

{
  "owner": {
    "organization": "Atlas Research LLC",
    "website": "https://atlas.example",
    "support_url": "https://atlas.example/support",
    "security_contact": "security@atlas.example",
    "terms_url": "https://atlas.example/agent-terms",
    "privacy_url": "https://atlas.example/privacy"
  },
  "governance": {
    "review_cycle": "monthly",
    "last_reviewed": "2026-10-05",
    "change_log": "https://atlas.agent/agent-json-changelog",
    "retirement_url": "https://atlas.agent/offboarding"
  }
}

Capabilities and endpoints

Say what the agent is for, then name the official URL for each surface. Discovery is not authorization. A listed capability does not grant the call.

{
  "capabilities": [
    {
      "id": "supplier_search",
      "description": "Find suppliers from approved catalogs.",
      "input_modes": ["application/json", "text/plain"],
      "output_modes": ["application/json"],
      "auth_required": true
    },
    {
      "id": "quote_request",
      "description": "Draft a request for quote for a reviewed supplier.",
      "input_modes": ["application/json"],
      "output_modes": ["application/json"],
      "auth_required": true
    }
  ],
  "endpoints": {
    "openapi": "https://api.atlas.agent/openapi.json",
    "mcp": "https://api.atlas.agent/mcp",
    "a2a_agent_card": "https://atlas.agent/.well-known/agent-card.json",
    "docs": "https://docs.atlas.agent"
  }
}

MCP metadata block

For MCP over HTTP, publish the canonical server URL and where a client discovers authorization. The MCP authorization spec dated 2026-07-28 requires protected resource metadata (RFC 9728) and tells clients to send the resource indicator from RFC 8707. Do not put bearer tokens in this file.

Set protocol_revision to the MCP revision your server implements. The sample uses 2026-07-28 because that is the date of the MCP authorization revision that requires protected-resource metadata and the resource indicator. Write 2026-07-28 when your server follows that revision. Write a different revision when your server follows a different one. Clients read this field to learn which rules the server speaks.

{
  "mcp": {
    "server_url": "https://api.atlas.agent/mcp",
    "transport": "streamable_http",
    "protocol_revision": "2026-07-28",
    "protected_resource_metadata": "https://api.atlas.agent/.well-known/oauth-protected-resource",
    "authorization_servers": ["https://auth.atlas.agent"],
    "scopes_supported": ["suppliers:read", "quotes:create"],
    "resource": "https://api.atlas.agent/mcp",
    "docs": "https://docs.atlas.agent/mcp",
    "status": "example"
  }
}

suppliers:read and quotes:create are example scope names for Atlas. MCP does not require those strings. How to place an MCP URL inside the manifest, and how to walk the path from outside your account, is covered in publishing MCP endpoints in agent.json.

Payment pointers

Name the rail and the public policy URL. Keep credentials out.

{
  "payments": {
    "accepted": [
      {
        "rail": "x402",
        "payment_requirements_url": "https://api.atlas.agent/.well-known/x402"
      },
      {
        "rail": "mpp",
        "policy_url": "https://atlas.agent/policies/mpp"
      }
    ],
    "dispute_policy": "https://atlas.agent/payment-disputes"
  }
}

Profile and verification pointers

{
  "directory": {
    "profile_url": "https://agents.headlessdomains.com/atlas.agent",
    "category": "procurement",
    "display_owner": "Atlas Research LLC"
  },
  "verification": {
    "dns_txt_name": "_agent.atlas.agent",
    "jwks_url": "https://atlas.agent/.well-known/jwks.json",
    "profile_url": "https://agents.headlessdomains.com/atlas.agent",
    "revocation_url": "https://atlas.agent/revoked-agents"
  }
}

The A2A Agent Card is a different file

Do not treat these blocks as an Agent Card. The A2A specification 1.0.0 defines an Agent Card with its own required fields, including name, description, version, supportedInterfaces, capabilities, defaultInputModes, defaultOutputModes, and skills. Each interface has a URL, a protocol binding (JSONRPC, GRPC, or HTTP+JSON), and a protocol version such as 1.0. A public card is often fetched at /.well-known/agent-card.json.

agent.json can link to that URL. It does not replace the card. How two agents check each other before they collaborate is a separate job, covered in A2A agent identity.

Checklist before you publish

• One canonical domain and one canonical manifest URL.
• Operator, support URL, terms, privacy, and a security contact you will actually read.
• Public capability text only. No hidden tools, no staging hosts.
• MCP block matches the spec revision your server implements, with a protected-resource metadata URL and no tokens.
• Agent Card lives in its own file. This manifest only links to it.
• Payment block lists rails and policy URLs, not secrets.
• Set the review date to the day you checked this file.
• Field names match the schema your client reads. If that client expects the Headless Domains manifest, follow that schema instead of this illustration.

Where these examples stop

A .agent name can point callers at the manifest, the skill file, the MCP server, and the Agent Card so they are not guessing which URL is official. The map of that stack sits in the agent identity stack. File roles for llms.txt and SKILL.md sit in llms.txt vs SKILL.md vs agent.json.

FAQ

Can I paste these examples into production?

Not as-is. Replace the Atlas names, confirm every field against the schema you publish, and set last_reviewed to the day you checked the file. The JSON here is illustrative.

Which MCP date should I write?

Write the revision your server implements. Use 2026-07-28 when the server follows the MCP authorization revision of that date. That revision requires protected-resource metadata (RFC 9728) and the resource indicator (RFC 8707). If the server implements another revision, write that revision so callers are not told the wrong rules.

Is agent.json the same as an A2A Agent Card?

No. Link the card. Do not merge the two documents and hope clients sort it out.

Should the manifest hold API tokens?

No. Publish discovery URLs. Tokens, private keys, and wallet secrets stay off the public file.

Give the agent a name, then point that name at a manifest you have actually reviewed.