How to publish Agent Mesh Protocol discovery

An AMP agent publishes an identity document so another agent can find its address and messaging endpoint. If you already run an Agent Mesh Protocol integration, this guide explains how to expose that discovery metadata and check what a public crawler receives.

This is the protocol at ampro.sh, maintained in the agentmeshpro repository. AMP is also used as an acronym by other projects. Their manifests and requirements can differ.

What Agent Mesh Protocol discovery tells a client

AMP's HTTP binding gives an agent an agent:// address and a JSON document at /.well-known/agent.json. The document declares the wire protocol version, the agent's identifiers and the HTTPS endpoint for messages. Optional metadata can describe capabilities, contact policy, keys and lifecycle state.

The HTTP binding groups behavior into levels. Level 0 requires both the identity document and a health endpoint at /agent/health. Higher levels add protocol behavior. Reading the identity document alone cannot establish that those operations work.

Our Agent Mesh Protocol checker tests public discovery. The same check appears as AMP discovery in a full report and can earn a capability badge. Publishing AMP discovery does not add or subtract score points. Use it when your product has an AMP integration to advertise; a content site without an agent does not need one.

Publish the native identity document

For an existing agent, the smallest useful document has these three fields. This example uses a fictional domain; replace every address with the one your implementation uses.

{
  "protocol_version": "1.0.0",
  "identifiers": ["agent://assistant.example.com"],
  "endpoint": "https://assistant.example.com/agent/message"
}

Serve it at https://your-domain.example/.well-known/agent.json with status 200 and Content-Type: application/json. Keep it outside routes that return your homepage for an unknown path. The response must be JSON without a login page or browser challenge in front of it.

The Python package's release number is separate from the wire protocol version. The wire binding's minimal example uses 1.0.0; that value is not a promise that your implementation supports it. Use the version exposed by the implementation and keep the document with its configuration.

AMP defines direct-host addresses such as agent://agent.example.com, registry addresses such as agent://[email protected], and DID addresses such as agent://did:web:agent.example.com. The discovery checker checks address syntax. It does not resolve the registry or DID, verify ownership or contact those addresses.

Unknown optional fields must be ignored by consumers. Add capabilities, security settings and other metadata only when they describe your agent. A declared capability group, a key URL or a certification is not evidence that we verified it.

Where to serve the file

If the AMP server owns the public domain, use its discovery route. If a reverse proxy owns the domain, route the well-known path to that server or serve metadata derived from the same configuration. For a static manifest, a hosting platform can serve .well-known/agent.json as a JSON asset. Check the deployed response: dot directories, fallback routes and authentication middleware can change what reaches a client.

The endpoint may name a separate service host. Our crawler records that address and does not request it. Keep credentials out of URLs and retain the authentication that messaging requires.

AMP recommends caching discovery and publishing a ttl_seconds value, with a default of one hour when it is absent. Set HTTP cache policy consistently with that value. When an endpoint or identity changes, update the discovery document and account for clients that still have the previous copy cached.

Advertise AMP through an A2A card

The project's A2A adapter can also advertise AMP through an extension. A client identifies it by the exact URI below, under capabilities.extensions. The adapter reference specifies required: false and three params: agent_id, amp_endpoint and protocol_version.

This fictional card illustrates that extension. Its A2A endpoint and its native AMP messaging endpoint are separate addresses.

{
  "name": "Example assistant",
  "description": "A fictional assistant for the discovery example.",
  "version": "1.0.0",
  "supportedInterfaces": [
    {
      "url": "https://assistant.example.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "extensions": [
      {
        "uri": "https://github.com/agentmeshpro/agent-mesh-protocol/ext/amp/v1",
        "required": false,
        "params": {
          "agent_id": "agent://assistant.example.com",
          "amp_endpoint": "https://assistant.example.com/agent/message",
          "protocol_version": "1.0.0"
        }
      }
    ]
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "answer",
      "name": "Answer",
      "description": "Answers a question in this fictional example.",
      "tags": ["example"]
    }
  ]
}

Let the adapter generate the card where possible. A hand-written extension should match the deployed adapter's behavior. An AMP name in a description, an amp field elsewhere or a similar-looking extension URI does not establish this declaration.

The checker reads /.well-known/agent-card.json, then typed A2A entries from the site's AI Catalog, including inline cards and at most one linked card. It reuses those documents in a full scan. Once a usable AMP extension is found, the native manifest request is skipped. Cards available only at a private or nested address that the public catalog does not name can remain undetected.

The result confirms the extension's discovery params. It does not validate the whole A2A card, activate the extension with A2A-Extensions or send a task. A site can therefore pass AMP discovery while a separate A2A Agent Card check reports a problem.

Check the response your deployment serves

Use the free checker for the same findings as a report, or inspect the native response yourself:

curl --silent --show-error --location --dump-header - \
  --header 'Accept: application/json' \
  --user-agent 'GoodForBotsBot/1.0 (+https://goodforbots.com/bot)' \
  https://your-domain.example/.well-known/agent.json

Check the final status, content type and body. Redirects can lead to a login page or another site's manifest. A JSON-looking header is not enough if the body is HTML. Check that the version, every identifier and the messaging endpoint match the live implementation.

The command does not enforce robots.txt on your behalf. GoodForBotsBot reads and respects it before fetching discovery. If this metadata is intended to be public, ensure the applicable robots.txt rules allow the discovery paths.

Test the health endpoint separately as part of validating your own implementation:

curl --silent --show-error --dump-header - \
  --header 'Accept: application/json' \
  https://your-domain.example/agent/health

AMP specifies a JSON response with status and protocol_version, status 200 for healthy and 503 for unhealthy. Then test messaging, authentication and any claimed higher-level behavior in a controlled environment with the protocol's own tooling. Our checker does not make these requests.

Fix discovery problems

A relative messaging endpoint

{
  "protocol_version": "1.0.0",
  "identifiers": ["agent://assistant.example.com"],
  "endpoint": "/agent/message"
}

This declaration points to /agent/message without a host. AMP's identity document requires an HTTPS endpoint. Publish the absolute URL used by the integration, including its service host and path. Our checker warns on this example.

An old card at the native path

Older A2A deployments and some plugin manifests also use /.well-known/agent.json. The current AMP fields use protocol_version, identifiers and endpoint. An unrelated card at that path does not earn AMP discovery. Keep the native manifest and the current A2A card distinct, or advertise AMP through the adapter's extension.

A 401, 404 or robots refusal

AMP permits conditional serving. Private agents may return 401 to outsiders, and hidden agents may return 404. A refusal cannot tell us whether the service implements AMP internally. The result means no public discovery was established for our crawler. Keep the privacy policy your agent needs; do not expose private metadata for a capability badge.

A package version copied into the protocol field

Changing the manifest's number does not change the protocol your agent speaks. Read the wire version from the implementation's configuration or generated metadata. If the checker reports a malformed version, fix its semantic-version form without claiming support for a different wire version.

Sources and review

Reviewed on 7 October 2026 against revision a994fb1ed28a0e5b960ae2bb28700748c43d3ec9:

• AMP HTTP wire binding, sections 3, 4 and 19, and Appendix E
• Agent identity JSON schema
• A2A adapter reference, AMP extension section

These are open project references, not an IETF or W3C standard. The examples are ours and are tested against the discovery check at the reviewed version. The checker uses a discovery threshold rather than full schema or runtime conformance validation; its methodology lists the scope and limits.