How an AgentDoc is assembled
An AgentDoc holds no facts of its own. Every line in it was copied from a document somebody else published and signed. This page sets out which section draws on which source, what each source is entitled to say, and what it can never answer.
The assembly
The finished document is on the left, and the sources it was built from are on the right. Everything passes through one step in the middle, and that step is deliberately narrow: it gathers, records where each thing came from, and adds nothing.
Section by section
What each section holds, and the sources it is normally built from. Open any source name for what that document is entitled to say.
Every section is optional. If you include one, it has to say where it came from. Two sections carry a rule beyond that: every exchange listed under asked needs its own state, and an access scheme that requires a header has to name it.
What each source may say
Each of these is a document somebody published. What matters when you read a line in an AgentDoc is which one it came from, because they are not equally strong and they do not answer the same questions.
a2a-card
The agent serves this card beside itself. It is usually the first source and the widest, but most of it is the operator's own description.
- Good for
- Name, operator, what it does in a sentence, the interfaces it claims, its declared refusals.
- Cannot say
- Anything a third party would have to confirm.
- Read it as
- Attributable rather than true. A signature makes it undeniable that they said it, never that it is so.
agent-manifest
This is what the agent told a registry when it registered, and it carries the operational facts a card has no room for.
- Good for
- How it is reached, what it accepts, and the access block: the schemes a caller presents and the admission policy behind them.
- Cannot say
- Any address, key or account. A manifest publishes what will be asked for, never where to send it.
- Read it as
- The agent's own words, checked only for shape by the registry that stored it.
sow-standing-proposal
A provider signs one of these per offering, and it holds the terms anyone may countersign. It is the strongest source in the set, because a contract forms on these bytes.
- Good for
- Inputs and deliverables, price, jurisdictions, retention, what it refuses as an actual clause rather than a sentence.
- Cannot say
- That the work will be any good. Form is enforced, quality is not.
- Read it as
- A promise with a remedy behind it, which is what separates it from every description.
interface-definition
The assembler fetches the published interface itself, from the registry that maintains it. It describes the exchanges rather than the agent. Three documents are in play: the agent's card declares the interface, this definition says what that declaration commits it to, and an observation settles whether it answers.
- Good for
- Every exchange an implementer must answer, and what each answer has to carry.
- Cannot say
- Whether this agent actually implements any of it. That claim lives on the card, and the proof lives in an observation or an eval record.
- Read it as
- What an implementer would have to answer. Listing it is what lets an AgentDoc expand an interface without summarising it.
roles-declaration
This is a role's published contract, fetched because the agent itself declares the role on its own card or manifest. The declaration makes the claim, this contract says what the claim means, and an evaluation settles whether the agent lives up to it.
- Good for
- The refusals, handling rules, and exchanges that come with holding the role at all, each entered as declared.
- Cannot say
- That this agent conforms. Claiming the role is claiming the contract, and nobody has checked either until an eval-record exists.
- Read it as
- A contract the agent claimed, which is only as good as the declaration pointing at it.
listing
A directory publishes an entry for the agent, which under the Agent Listing Model must derive from documents rather than being typed.
- Good for
- What a marketplace is willing to publish, and how each claim was evidenced.
- Cannot say
- Anything the underlying documents do not, though a directory can still be out of date.
- Read it as
- Second-hand, and worth less than the document it was derived from.
reputation-report
A bureau signs and publishes this report. It is the only source here written by somebody with no interest in selling you anything.
- Good for
- Engagement history and what a bureau observed.
- Cannot say
- Anything an AgentDoc may average, score, or grade. It is carried whole and attributed.
- Read it as
- Somebody else's document, which this one repeats and never audits.
plugin-package
This is a distributed bundle of instructions and tool declarations. Most agents are packaged long before anyone writes them a document.
- Good for
- Name, version, description, and the tool list split by transport: a tool run locally is the provider's own machinery, a tool reached over a URL means your content leaves the building.
- Cannot say
- Price, inputs, deliverables, refusals, jurisdictions, retention, interfaces, or who is admitted. A package states none of these and none may be inferred.
- Read it as
- The agent itself rather than a description of it. Importing one produces a draft for its author to sign, never a finished AgentDoc.
agent-descriptor
This is the agent's own Agent Descriptor, the one place its operator writes a standing description. Where one exists, the assembler prefers it over any card or manifest generated from it, and records its digest, so a reader can tell whether a signature meant this version.
- Good for
- The one-sentence description, each offering with its typed inputs and outputs, who drives it, the runtime shape, the hosting regions, and the per-caller limits.
- Cannot say
- Any endpoint, key, or price. It holds shapes, and the binding facts stay in the documents that carry them.
- Read it as
- The operator's word, entered at declared like every other claim an agent makes about itself.
eval-record
An evaluator ran the agent against what its role and interfaces say it must answer, and signed what happened. This is the record that moves an inherited member past declared.
- Good for
- Whether the agent answers what it claims, exchange by exchange, with a dated verdict.
- Cannot say
- Anything about the runs it did not make, or any day after the test.
- Read it as
- Evidence rather than description, able to mark a claim confirmed or failed.
observation
This is not a document at all. It is something the assembler did: it asked the agent one exchange and recorded the answer and the moment.
- Good for
- Turning "it says it does this" into "it did this, at 18:04", one exchange at a time.
- Cannot say
- Anything about the exchanges it did not ask. Asking one confirms one.
- Read it as
- The only source that can go stale in a minute, which is why it carries its own timestamp.
Reading the map
The map shows the common case
Nothing fixes a section to a source. Every section in a real AgentDoc names its own sources, and a member that came from a different one names that too. What you see above is where these facts usually live, so treat it as a guide rather than a rule. The document itself is what says where each of its lines came from.
Why there is no badge
There is no score, badge or trust mark anywhere in an AgentDoc, and there is not going to be one. A badge collapses the provenance into one word, and the provenance is the part a reader needs. The same sentence is worth different amounts depending on whether it sits in a description or a signed clause, and the only way to show that is to say which it was.
What a missing section means
Sections are optional, and a missing one is not a gap in the document but an answer about the agent. That is why silence is printed by path in not_stated instead of rendering as blank space. An agent that reads your contracts and has never said how long it keeps them looks identical to one that has, until somebody writes the absence down.