What Is agent.json? AI Agent Manifests Explained

At Headless Domains, agent.json is a public JSON manifest that describes an AI agent and points compatible software to its services and related records. It can publish the agent's name, description, capabilities, operator references, and service information in fields an application can read.

Think of a customer asking where to find your agent, what it does, and how to contact it. A person can read a profile page. Another application benefits from a structured record it knows how to parse. The manifest gives that application a starting point.

The Agent Identity Learning Center places this manifest guide alongside the identity and developer reading paths.

The filename alone does not define a universal standard. Use the schema and discovery instructions for the platform you are integrating with. This guide explains the Headless Domains implementation.

What does a manifest actually do?

A manifest describes something and the resources associated with it. In this case, it describes an agent.

Suppose you run an agent that prepares customer-support summaries. Its public manifest can describe that service and point to the interface or instructions for requesting a summary. A compatible client can read those references without extracting them from a page layout.

The code that produces the summary still runs in your chosen environment. Publishing its description does not create the service, start the agent, or give a caller access to customer conversations.

You can update the service behind the record as the agent improves, while keeping its public description current.

What is inside a Headless Domains agent.json?

Our manifest documentation describes the platform's hosted records. Depending on the published configuration, a manifest can include:

• Agent information: a name, description, version, and declared capabilities.
• Operator and identity references: information connecting the record to its operator or claiming state.
• Service information: references to interfaces, contact routes, or payment endpoints where configured.
• Related documents: links to the agent's hosted Markdown record or other supported resources.

These are categories of information, not a replacement schema. Follow the documented structure and supported management controls rather than adding arbitrary fields and expecting every client to understand them.

A capability is something the publisher says the agent offers. A payment endpoint tells a caller where a payment interaction may occur. Neither field is permission to perform the action.

A simple example: a support-summary agent

Imagine an agent called Support Summary that turns support conversations into summaries for a customer-service team. The following fictional excerpt illustrates the role of a few manifest fields. It is not a live identity, a complete Headless Domains response, or a registration payload. The capability label and document address are illustrative.

{
  "agent": {
    "name": "Support Summary",
    "description": "Prepares summaries of support conversations for review.",
    "capabilities": [
      "support_summary"
    ]
  },
  "skills": [
    "https://example.com/support-summary/guide.md"
  ]
}

The name identifies the agent, the description explains its job, and the capability label gives a compatible application a value to interpret. The skills array points to a separate document describing the service.

That document might explain which conversation formats the service accepts and what a summary contains. Access to actual customer conversations would still require the appropriate authorization. Neither the description nor the capability label grants it.

For an implementation, use the fields and capability values supported by your platform and clients.

Where does the file live?

Headless Domains hosts JSON manifests at addresses following this pattern:

https://headlessdomains.com/manifests/<domain>.json

The documented DNS TXT pointers include agent-manifest= for the JSON document and skill-md= for the Markdown document. The platform's machine instructions also describe its public, read-only resolver, which returns resource links for a registered name.

Follow those published links. Registering a headless domain does not mean you should construct an ordinary browser URL by appending /.well-known/agent.json. The maintained name and the HTTPS address serving its manifest are different parts of the setup.

Why the schema matters more than the filename

Two documents can both be called agent.json and contain different structures. A parser needs to know which fields to expect and what they mean.

The A2A specification, for example, defines its own Agent Card object. Its discovery options include /.well-known/agent-card.json, registries, and direct configuration. A Headless Domains manifest is not automatically an A2A Agent Card.

ERC-8004 specifies a different agent registration file, reached through the registered agent URI. That URI can point to several kinds of location, including HTTPS or IPFS. Sharing the general idea of agent metadata does not make the formats interchangeable.

For the wider choice of documents, use our llms.txt, SKILL.md, and agent.json comparison. It explains when to publish each one.

Does the file prove the agent is trustworthy?

The manifest gives a reader claims and references to inspect. Trust depends on the evidence relevant to the interaction. Naming an operator in JSON does not prove affiliation, and matching names across copied profiles are not independent confirmations.

Likewise, a public record does not grant tool access or spending authority. The receiving service and the surrounding application enforce those decisions. Our identity-record reading guide covers how to separate published claims from checked evidence.

Keep the public file limited to information intended for public discovery. Private keys, API tokens, customer records, private spending approvals, and transaction histories belong in protected systems.

Why connect the manifest to a headless domain?

Your agent may have a profile in one directory, documentation on another host, and a service running elsewhere. A Headless Domains name gives people and compatible clients a maintained public reference connecting those locations.

If the service moves, update its published destination while retaining the name and maintaining the registration. The manifest can describe the current setup without requiring customers to remember every endpoint change.

This is the public naming role within the Agent Identity Stack. Your agent keeps its runtime, credentials, and access controls.

Start with the agent you already run

Give your existing agent the Headless Domains getting-started instructions. Ask it to explain the registration options and cost before taking action, then help you review the published manifest for the name you register. Confirm that the description and service links match the agent you actually operate.

If you have just registered a name, use the post-registration checklist to review the manifest alongside its profile and service links.