Document your agent

You built an agent that speaks A2A, and it serves an agent card. This page shows how to give it an AgentDoc. You need one command to start, and nothing to sign up for.

1. What you get

An AgentDoc is one document about your agent. People read it as a page, and software reads it as JSON. Both come from the same document, so they always say the same thing.

Every line in an AgentDoc names the source it came from. Anything your agent has not said is listed by name, so a reader can see what is missing.

Nobody writes an AgentDoc by hand. A tool assembles it from what your agent already publishes. To change what it says, you change the source and build it again.

2. Make one with one command

You need Node.js 20.10 or later. Run this command with your agent's address.

npx @common-agent/agentdoc build https://your-agent.example

The tool reads your agent card from /.well-known/agent-card.json at that address. It also looks for a signed Descriptor at /.well-known/agent-descriptor.json, which you can add later. It writes two files into a folder named agentdoc-out.

agentdoc-out/.well-known/agentdoc.json
agentdoc-out/agentdoc.html

Add --out and a folder name to write somewhere else. If your agent is not online yet, give the path of a card file in place of the address.

If you will run the tool often, install it once with npm install --global @common-agent/agentdoc. The command is then common-agent-doc, and the rest of this page uses that name. With npx, write npx @common-agent/agentdoc in its place.

3. Where the two files go

Publish the JSON at /.well-known/agentdoc.json on your agent's domain. That puts it beside your agent card, so anyone who has your address can find both.

Publish the page at /agentdoc.html on the same domain, where people can open it. The command, the GitHub Action and this guide all use that address. Link to it from your own site so people find it.

4. What a card-only AgentDoc looks like

This is a shortened AgentDoc for an agent that publishes a card and nothing else.

{
  "agentdoc": "v1",
  "subject": { "id": "https://recipes.example.com/a2a", "name": "Recipe Scaler" },
  "assembled_at": "2026-11-02T15:20:00Z",
  "sources": [
    { "id": "card", "kind": "a2a-card",
      "url": "https://recipes.example.com/.well-known/agent-card.json",
      "fetched_at": "2026-11-02T15:19:58Z", "signature": "unsigned" }
  ],
  "sections": {
    "identity": { "from": ["card"], "name": "Recipe Scaler", "operator": "Example Kitchen Co" },
    "shape":    { "from": ["card"], "visibility": "opaque" },
    "sells":    { "from": ["card"], "offerings": [
                  { "name": "Scale a recipe", "scope": "task-specific",
                    "does": "Rewrites a recipe for a different number of servings." } ] },
    "access":   { "from": ["card"], "address": "https://recipes.example.com/a2a", "protocol": "a2a" }
  },
  "not_stated": [
    "identity.acts_for", "access.schemes", "access.admission", "sells.offerings.price",
    "refuses", "handling", "reaches", "role", "standing"
  ]
}

The card gives a name, an operator, an address and a list of skills. Those fill the identity, sells and access sections. Each section lists card in its from member, which points back to the card in sources.

Most other sections say not stated. A card has no place to say whom the agent acts for, what it refuses, where it keeps data or what it costs. The tool does not guess those answers. It lists them in not_stated, and the page shows that list as plainly as everything else.

Not stated means the agent has said nothing on that point. An agent that says nothing about how long it keeps data has made no promise to delete it. An agent with no published price has not said it is free.

The shape section gives the visibility as opaque. That tells a reader the agent is known only by its card.

5. Add a signed Descriptor

An Agent Descriptor is a file you write about your agent and sign with your agent's own key. It says what the agent does, whom it acts for, what each offering takes and returns, and what it refuses. Three commands make one.

common-agent-doc init https://your-agent.example
common-agent-doc keygen
common-agent-doc sign agent-descriptor.json --key agent.key

init reads your card and drafts agent-descriptor.json. Every value it had to guess is marked, so you know what to check. Open the file and fill in what the card could not say.

keygen makes a signing key on your computer. It writes the secret part to agent.key, which only you can read, and it prints the public key. Keep agent.key out of your repository and keep a copy somewhere safe.

sign ties the Descriptor to that key and adds your signature. Publish the signed file at /.well-known/agent-descriptor.json, and then run build again.

Your AgentDoc now lists the Descriptor as a second source, with its signature marked verified. The sections it covers carry your own words, and the not_stated list gets shorter. A reader can check that the Descriptor came from whoever holds your agent's key. The Agent Descriptor page explains every member you can fill in.

6. Check it

common-agent-doc check agentdoc-out/.well-known/agentdoc.json

check applies the rules in Section 9.10 of the specification. It confirms that every section names a source the document lists. It confirms that a limit is shown as enforced only when a rule enforces it. It also confirms that everything missing is listed as not stated. It prints each problem it finds.

You can point it at a published address. Add --fetch-sources to fetch every listed source and compare it with the digest the AgentDoc recorded.

common-agent-doc check https://your-agent.example/.well-known/agentdoc.json --fetch-sources

It exits with 0 when the AgentDoc passes and 1 when it does not. It exits with 2 when the command was wrong or a fetch failed.

7. Keep it current with GitHub Actions

An AgentDoc goes out of date when your agent changes. The AgentDoc Action builds it again for you. It is listed on the GitHub Marketplace. Save this file in your repository as .github/workflows/agentdoc.yml.

name: AgentDoc
on:
  release:
    types: [published]
  workflow_dispatch:

permissions:
  contents: write

jobs:
  agentdoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.repository.default_branch }}
      - uses: CommonAgent/agentdoc-action@v1
        with:
          address: https://your-agent.example
          descriptor: agent-descriptor.json
      - name: Commit the AgentDoc
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add .well-known/agentdoc.json agentdoc.html
          git commit -m "Update the AgentDoc" || echo "The AgentDoc did not change."
          git push

The workflow runs each time you publish a release. It builds the AgentDoc, checks it, and commits the two files to your main branch. Your usual deploy then publishes them. Put your agent's address in address. Leave out the descriptor line until you have signed one.

The Action also sets three outputs for later steps. They are agentdoc-path, page-path and ok.

8. The JSON Schema, for other languages

If you work in another language, you can validate an AgentDoc against its JSON Schema. The schema follows JSON Schema draft 2020-12.

https://agentdoc.net/schema/agentdoc-v1.json

The schema checks the shape of the document. The rules about sources and silence need the check command or your own code. The test cases in the Common Agent Standards repository show AgentDocs that pass and AgentDocs that fail each rule.

9. Agents that only speak A2A

An agent that publishes only an A2A card still gets a valid AgentDoc. The card is enough to build one.

What the agent has not declared is listed as not stated. Nothing is filled in on its behalf.

A reader can see that the agent is known only by its card. The page says so, and the visibility says opaque.

Publishing a signed Descriptor shows more about the agent. Attestations from other parties show more again. Each one adds a source that a reader can check.

10. The package and its source

The tool is the npm package @common-agent/agentdoc. Its source code is in the Common Agent TypeScript repository, under the Apache 2.0 license.

It is one of the Common Agent Standards tools. It needs no account. It reads only your agent and the sources your agent points to.

Back to the overview