What Is agent.json?
If you are asking what is agent.json, the short answer is that agent.json is a public machine-readable manifest for an AI agent. The file can name the agent, the operator, the canonical domain, the official endpoints, the published capabilities, the payment policy, and the proof links another system should inspect before interaction.
For HeadlessDomains.com, agent.json sits inside a larger persistent identity record for the agentic web. A .agent identity can point to agent.json, SKILL.md, TXT records, API metadata, MCP endpoints, and profile pages so agents can resolve one trusted source through command-line and API workflows.
Quick Definition Table
| Layer | Question answered | Common fields | Verification clue |
|---|---|---|---|
| Identity | Which agent is speaking? | domain, display_name, canonical_manifest, status | The same name appears in the .agent record and manifest URL. |
| Operator | Who is accountable? | organization, support_url, security_contact, policy_urls | Support and policy links match the operator website. |
| Capabilities | What can the agent do? | capabilities, input_modes, output_modes, auth_required | Capability names match docs and public endpoints. |
| Endpoints | Where can callers connect? | openapi, mcp, a2a_agent_card, webhooks, docs | Each endpoint is official and versioned. |
| Payments and proof | How are payment and trust checked? | payments, limits, receipts, dns_txt, jwks, signed_manifest | No credentials are exposed; proof links are public. |
What Belongs In The Manifest
Keep agent.json concise but explicit. The file should publish stable identity data, public capability descriptions, endpoint locations, auth context, and verification pointers. Do not place bearer tokens, private keys, wallet secrets, staging hosts, or private runbooks in the public file.
When an agent exposes tools, the manifest can link to MCP metadata. The Model Context Protocol authorization docs describe protected resources and authorization context for remote MCP, which belongs in metadata rather than inside a secret. When an agent collaborates with peers, the manifest can also link to an A2A Agent Card for supported interfaces and interaction rules.
How agent.json Differs From SKILL.md And llms.txt
agent.json answers who this agent is and how to verify its public surface. SKILL.md explains a repeatable workflow. llms.txt maps useful pages and docs. The three files can work together, but they should not be treated as substitutes.
For a side-by-side publishing model, read llms.txt vs SKILL.md vs agent.json. For implementation patterns, pair this glossary with agent.json examples for public AI agent identity.
Example agent.json Record
A minimal public manifest can stay small at launch and expand as the agent gains callable surfaces.
{"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 draft quote requests.","status":"active"},"owner":{"organization":"Atlas Research LLC","support_url":"https://atlas.example/support","security_contact":"security@atlas.example"},"capabilities":[{"id":"supplier_search","auth_required":true},{"id":"quote_request","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"},"verification":{"dns_txt":"_agent.atlas.agent","jwks_url":"https://atlas.agent/.well-known/jwks.json","signed_manifest_url":"https://atlas.agent/.well-known/agent.json.jws"}}Implementation Checklist
- Choose one canonical manifest URL, such as
/.well-known/agent.json. - Name the agent, operator, purpose, status, version, support route, and security contact.
- List public capability IDs and official endpoint URLs.
- Link MCP, A2A, OpenAPI, payment, policy, profile, and proof URLs when available.
- Publish DNS TXT proof, signed manifest metadata, or JWKS metadata for verification.
- Keep credentials, private keys, internal hosts, and draft workflows out of the public manifest.
- Review the manifest after endpoint changes, payment-policy changes, ownership changes, and retirement.
Where HeadlessDomains.com Fits
HeadlessDomains.com gives agent.json a resolvable identity anchor. A .agent name can connect the manifest, SKILL.md, TXT records, lookup data, payment metadata, and profile links into one public inspection path.
Headless Domains names are headless, so agents are not waiting for browser-native resolution. They can inspect records through command-line and API workflows, then verify the manifest before calling tools or sending payment.
Where To Go Next
Use The Agent Identity Stack as the hub for the full discovery, verification, calling, payment, and governance model. Then publish a small agent.json file, attach the file to a .agent identity, and keep the manifest aligned with the endpoints and policies other agents will inspect.
FAQ
What is agent.json used for?
agent.json is used to publish public identity and verification metadata for an AI agent. The file helps another agent or integration inspect the operator, capabilities, endpoints, payment policy, and proof links before interaction.
Where should agent.json live?
Publish agent.json at a stable well-known URL such as /.well-known/agent.json, or link the manifest from a .agent identity record. The key is one canonical inspection path.
Is agent.json the same as SKILL.md?
No. agent.json describes identity and verification context. SKILL.md describes task instructions, output rules, and repeatable workflows.
Can agent.json include MCP or A2A metadata?
Yes. The manifest can link to an MCP server, OpenAPI file, or A2A Agent Card. Keep authorization details public enough for discovery while keeping secrets outside the manifest.
Can agent.json include payment metadata?
Yes. Publish rail names, policy URLs, receipt routes, spending limits, and dispute paths. Never publish wallet secrets, private keys, or bearer tokens.
How does a .agent identity help?
A .agent identity gives the manifest a persistent public anchor. Agents can resolve the same name to inspect agent.json, SKILL.md, TXT proof, endpoint metadata, and profile links before interaction.