// POST 063 / 093

agent.json Examples for Public AI Agent Identity

May 4, 2026 /

Agent.json examples should be copy-paste starting points for public AI agent identity: who owns the agent, what the agent can do, which endpoints are official, how MCP access works, how payments are described, where the directory profile lives, and how callers verify the record.

For HeadlessDomains.com, agent.json belongs in a larger identity bundle anchored by a .agent name. Publish the manifest, SKILL.md, endpoint metadata, payment policy, proof links, and Headless Profile Directory page from one public inspection path before agents call tools or send value.

Copy-Paste Blocks

Block	Use for	Fields to publish	Do not publish
Identity	Canonical agent name and manifest URL	domain, display name, purpose, status, version, manifest URL	Temporary test names or private aliases
Ownership	Accountability and support routing	operator, website, support, security contact, policy URLs	Personal secrets or internal ticket queues
Capabilities	What callers may ask the agent to do	capability ids, descriptions, input modes, output modes, auth flags	Hidden tools or unreviewed actions
Endpoints	Official machine-callable surfaces	OpenAPI, MCP, A2A Agent Card, webhooks, docs, terms	Staging endpoints or credentials
Payments	Paid API access or agent commerce	x402, AP2, MPP, receipt URL, spending policy, dispute policy	Wallet secrets or payment credentials
Verification	Proof that the manifest belongs to the named agent	DNS TXT, JWKS, signed manifest, profile URL, last review date	Private keys or bearer tokens

Minimal Public Identity Example

Start with a small manifest that names the agent and points callers to the stable public records. Keep this layer boring and durable.

{"agent_json_version":"public-identity.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 Example

Ownership metadata lets another agent route questions, policy checks, abuse reports, and security notices to the operator behind the public identity.

{"owner":{"organization":"Atlas Research LLC","website":"https://atlas.example","operator_identity":"atlas.agent","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-05-21","change_log":"https://atlas.agent/agent-json-changelog","retirement_url":"https://atlas.agent/offboarding"}}

Capabilities And Endpoints Example

Capability metadata should say what the agent is likely to do and which official endpoint handles each surface. That keeps discovery separate from authorization.

{"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","webhooks":"https://api.atlas.agent/webhooks","docs":"https://docs.atlas.agent"}}

MCP Metadata Example

For MCP, publish the canonical server URL, protocol version, authorization model, protected resource metadata, and supported scopes. The MCP authorization spec uses OAuth resource indicators and bearer tokens for protected HTTP requests, so do not place tokens in agent.json.

{"mcp":{"server_url":"https://api.atlas.agent/mcp","transport":"streamable_http","protocol_version":"2025-11-25","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_indicator":"https://api.atlas.agent/mcp","docs":"https://docs.atlas.agent/mcp","status":"production"}}

Payment Metadata Example

Payment metadata should tell callers which rail is supported and where verification, receipt, spending, and dispute rules live. Keep credentials outside the public manifest.

{"payments":{"accepted":[{"rail":"x402","payment_requirements_url":"https://api.atlas.agent/.well-known/x402","resources":["https://api.atlas.agent/premium-data"]},{"rail":"ap2","policy_url":"https://atlas.agent/policies/ap2","receipt_url":"https://atlas.agent/receipts/{transaction_id}"},{"rail":"mpp","endpoint":"https://pay.atlas.agent/mpp","renewal":"supported"}],"limits":{"max_single_payment_usd":"25.00","requires_operator_review_above_usd":"100.00"},"dispute_policy":"https://atlas.agent/payment-disputes"}}

Directory Profile And Verification Example

Directory metadata gives humans and agents a profile to inspect. Verification metadata gives callers a checklist for matching the manifest to the public identity.

{"directory":{"profile_url":"https://agents.headlessdomains.com/atlas.agent","category":"procurement","tags":["supplier-search","quotes","mcp","x402"],"display_owner":"Atlas Research LLC"},"verification":{"dns_txt":"_agent.atlas.agent","manifest_sha256":"REPLACE_WITH_HASH","jwks_url":"https://atlas.agent/.well-known/jwks.json","signed_manifest_url":"https://atlas.agent/.well-known/agent.json.jws","proofs":["https://atlas.agent/proof.txt","https://atlas.example/.well-known/atlas-agent-proof"],"revocation_url":"https://atlas.agent/revoked-agents"}}

Full Manifest Checklist

Use one canonical domain and one canonical manifest URL.
Name the operator, support route, terms, privacy page, and security contact.
Publish only public capability descriptions and public endpoint URLs.
Put OpenAPI, MCP, A2A Agent Card, webhooks, docs, and status URLs in separate endpoint fields.
Use OAuth scopes, protected resource metadata, and resource indicators for MCP HTTP access.
List payment rails, policy URLs, receipt URLs, limits, and dispute paths without exposing credentials.
Include directory profile, DNS TXT proof, JWKS URL, signed manifest URL, review date, and revocation path.
Keep secrets, bearer tokens, private keys, staging hosts, and internal runbooks out of public agent.json.

Where HeadlessDomains.com Fits

HeadlessDomains.com gives public agent identity a stable anchor. A .agent record can point to agent.json, SKILL.md, TXT records, MCP endpoints, A2A Agent Cards, payment metadata, and profile pages so other agents can resolve one canonical source before interaction.

Use The Agent Identity Stack as the hub for this publishing model. Then connect the examples above to a .agent identity, a Headless Profile Directory page, and public proof links before partner agents or tools rely on the manifest.

Learn More

FAQ

What is agent.json used for?

agent.json is a public machine-readable manifest for an AI agent. The file can declare identity, operator, capabilities, endpoints, authorization context, payment metadata, directory profile, proof links, and lifecycle state.

Where should agent.json live?

Publish agent.json at a stable well-known URL or link the manifest from a .agent identity record. The key requirement is one canonical inspection path that other agents can resolve before tool use, collaboration, or payment.

Should agent.json include MCP metadata?

Yes, when the agent exposes MCP tools or relies on an MCP server. Publish the server URL, transport, protocol version, authorization servers, protected resource metadata, scopes, docs, and status, but never publish bearer tokens or private keys.

Can agent.json include payment metadata?

Yes. The manifest can point to x402 requirements, AP2 policy, MPP endpoints, receipt URLs, spending limits, and dispute policy. The manifest should describe payment verification paths without exposing wallet secrets or payment credentials.

How does a caller verify the manifest?

A caller can compare the .agent record, manifest URL, directory profile, DNS TXT proof, JWKS URL, signed manifest, operator website, and security contact. The caller should log the version and review date before trusting the endpoint.

Is this the same as an A2A Agent Card?

No. A2A uses an Agent Card to describe supported interfaces, capabilities, skills, security schemes, and interaction requirements. agent.json can link to the Agent Card while also covering ownership, payments, proof links, and directory profile.

[← ALL POSTS] [GET YOUR .AGENT →]