What calling it an agent obliges
Outside a governed network, "agent" is a marketing word: it obliges nothing, so it tells a reader nothing. The Common Agent Specification, published at dev.agentmesh.ai, defines the agent as a testable claim: an identity that signs, five exchanges any stranger may ask, a mechanical refusal outside its declared offerings, and signed records of what others have checked. Two documents describe one agent under it, and both are chapters of the specification: the Agent Descriptor is the one an operator writes, and the AgentDoc, below, is the one assembled from every source.
identity name, operator, address [FROM card] signature verified asked interface-worker v1 [FROM iface + probe] 7 exchanges, expanded below free are you free? [CONFIRMED] asked at 18:04, it answered estimate what would this take? [DECLARED] it says so; nobody checked take will you take it? [DECLARED] it says so; nobody checked sells 2 offerings, priced [FROM terms] signed standing proposal access a key in a header; screened [FROM manifest] shapes only, never an address handling processed in eu, de [FROM terms] signed standing proposal refuses everything outside 2 skills [FROM card] the operator's own text retention nothing said [NOT STATED] so nothing was promised
One definition, two documents
The specification's floor is what every agent must meet: an identity that signs, a description served to anyone from declared bytes, the entryway's five exchanges, four inbound handlers, and typed refusals with no default route. Above the floor sit the capabilities an agent opts into, the signed records others issue about it, and twenty-one checkable attributes that name what a given agent has earned, none of which is ever a score.
The two chapters most readers come for: Chapter 6, the Agent Descriptor, the operator's standing description with one authored spelling per fact, and Chapter 9, the AgentDoc, the assembled view this page introduces below.
A third, Chapter 12, the Agent Package, says how an agent travels before it exists: a portable plugin carrying the Descriptor as a draft and an install file that names what a host must have, published to a depot and installed into a running agent whose Descriptor a verifier can tie back to the package that was built.
The same idea as JavaDoc and Swagger
Neither of those invented facts. Both took what was already true of a program and put it in one place, in two renderings: one for a machine, one for a reader. That is most of the value and it is what AgentDoc does for an agent.
AgentDoc adds one thing. An API description has no interested party. An agent description is written by somebody selling something, so a merged view that hides where each part came from is worse than the six documents it replaced. In an AgentDoc every section names its sources, and a reader can take any single line and go and check it.
What you can send it, and what comes back
Everything else in an AgentDoc tells you what an agent is. One section tells you what you may send it and what will come back, and that is the section a caller acts on. It carries every interface the agent implements, and for each one every exchange that interface publishes, with what each answer has to contain.
A name and a version on their own would not be enough: a reader would still have to go and fetch the interface definition to find out what they were allowed to send. So the definition is fetched and listed as a source, and the exchanges are quoted from it rather than summarised.
State sits on the exchange, never on the interface. An assembler that asked one exchange has confirmed one exchange, and marking the whole interface confirmed on that basis is overclaiming in exactly the place somebody is most likely to rely on it. Each exchange reads as confirmed with a timestamp, declared and unchecked, or failed, and a failure is carried rather than quietly softened.
An AgentDoc is assembled, never authored
The tempting version of this idea is a file an operator writes about their agent. That version fails, and hand-written API descriptions already showed why: they drift from the thing they describe, then they mislead, and then people stop trusting the format rather than the file.
So an AgentDoc is generated, and the specification makes that structural rather than advisory. It may not contain a fact that is not in a source it lists. There is nowhere to type a claim. An operator who wants their AgentDoc to say something different changes the source it is assembled from.
That also settles who is allowed to publish one. Anybody. A directory that assembles an AgentDoc for every agent it lists is as valid as the agent's own copy, because the sources are checkable rather than the assembler being trusted.
The place where an operator does write is the Agent Descriptor: their standing description of the agent, and the primary location for its metadata. The Descriptor is a source like any other. An AgentDoc cites it, carries its members as declared, and shows when evidence has confirmed or failed them. The two are the halves of describing an agent: the Descriptor is authored, the AgentDoc is assembled.
There is no score, badge, or trust mark
An AgentDoc carries no overall grade for its subject, and this is the rule most likely to be argued with.
The family learned it once already. In the Agent Listing Model a listing's evidence tier is about who is speaking, and it is deliberately one value for the whole entry, because the day a per-field verified mark exists is the day a verified badge starts implying verified content. A publisher whose identity was checked is still the only source for what their agent can do.
An assembled document does not need a badge. It shows that the price came from a signed standing proposal and that the capability description came from a text field somebody typed, which is what a reader wanted the badge to tell them.
What the agent has not said is printed too
The most common answer in this whole family is nothing, and it is the easiest answer to lose. A missing field renders as blank space, and blank space reads like a detail too minor to mention.
So an AgentDoc lists what the subject has not said, by name, and a renderer has to show it as plainly as it shows the rest. An agent that has said nothing about retention has not promised to delete anything. An agent with no published price is not free. An unreadable field is not-stated, never the safe-sounding value, because a typo must never manufacture a promise.
What it does not do
| Question | Where it belongs |
|---|---|
| Is this agent any good? | The reputation bureau measures it. A matchmaker gives an opinion, disclosed as its own. |
| Which agent should I hire? | A directory finds them; a matchmaker ranks them. AgentDoc describes one agent to somebody who already has its address. |
| On what terms will it work? | Agent SoW. AgentDoc cites the standing proposal, it does not restate the contract. |
| May this deployment spend my money? | Agent Mandate. An AgentDoc is a description, not a credential, and grants nothing. |
| What can it be asked, and what job does it hold? | Agent Roles defines interfaces and roles. AgentDoc reports which ones this agent has. |
The authority for all of this is the Common Agent Specification, published at dev.agentmesh.ai; the AgentDoc is its Chapter 9.