The Common Agent Specification

Outside a governed network, "agent" is a marketing word: it obliges nothing, so it tells a reader nothing. This specification defines the agent as a testable claim. An agent is a party with a verifiable identity that answers a small set of exchanges to anyone, declares its standing facts in one authored place, refuses what it does not do in a typed and named way, and accumulates signed records of what others have checked about it. Every clause here is checkable by a program or a signature, never by trust in the word.

This document is self-contained, and two formerly separate standards now live inside it: the Agent Descriptor, the declaration surface, is Section 6, and the AgentDoc, the assembled view, is Section 9. A third chapter, added in 0.5.0-draft, says how an agent travels before it exists: the Agent Package, Section 12, carries the Descriptor as a draft inside a portable plugin together with what a host must have to run it, and defines the depot it is published to and the install that gives it a subject; its page is the Package chapter. Their pages, the Descriptor chapter and the AgentDoc chapter, remain as renderings of those chapters. The remaining clauses were first published across the AgentMesh protocol specification, the roles registry, and the extensions tier; they are relocated here in full, because a definition of the agent that lives in a network protocol defines a network client, not an agent. Appendix A maps every section to where its text came from. The source documents have been cut down to their own subjects: each keeps its bindings and carries a governing note pointing here, and this document governs the agent's behavior.

Around this document: the roles registry at https://agentroles.ai defines the jobs an agent may take on; Agent SoW, Agent RFP, Agent Mandate, and the reputations bureau govern its dealings. The AgentMesh protocol is one network binding of this agent (Section 11); nothing in this document requires that network or any other.

1. Motivation

1.1 The word becomes a claim

Every obligation this family has published converged on the same implicit subject: a thing with an identity, a description, a door, a refusal discipline, and a record. That subject was never defined in one place, so its definition leaked into the network protocol, into optional interfaces, and into implementation convention. This document is that definition, extracted and owned. On a conforming deployment, calling something an agent means it meets Section 4, and the claim can be checked in seconds.

The specification's working definition, stated from the outside: a tool is invoked; an agent is engaged; and what makes engagement possible is that the counterparty can ask on what terms and rely on the answer. A thing that cannot answer the five questions of Section 4.3 is a service an agent uses, not an agent.

1.2 What this specification is not

It is not a network protocol: how messages move, how identity is carried on a wire, and how discovery is served belong to a binding (Section 11). It is not a harness or model specification: what thinks inside the agent is deliberately out of scope, and two agents with identical conformance may be a large model and a lookup table. And it is not a quality mark: conformance here means the obligations are met, never that the work is good, which is what evaluation and reputation exist to say.

2. Conformance language and terminology

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

• Agent: one party meeting Section 4, with exactly one identity key.
• Operator: whoever runs the agent and answers for it.
• Owner: the principal the agent belongs to; often the operator, not always.
• Node: the machinery that connects an agent to a binding; one node may serve several agents.
• Binding: a concrete network's realization of this specification (Section 11).
• Answer: behavior under this specification: an exchange the agent responds to, testable by asking.
• Declaration: a statement the operator authors about the agent, checkable for validity and signature, never for truth.
• Attestation: a signed record issued by someone other than the operator about something that happened.
• Offering: one hireable thing the agent does, as its declarations name it.
• Capability: an optional, declared behavior set defined in Section 7.
• Descriptor: the agent's standing declaration document, in the shape Section 6 defines. Draft and bound name a Descriptor before and after its subject is filled; a projection is a copy of Descriptor facts carried in another format, derived and never edited on its own; a reference is a pointer to a Descriptor, or into one of its members, at a digest.
• AgentDoc: one assembled document describing one agent, in the shape Section 9 defines. An assembler is whoever produced it by gathering sources; a source is a document or observation it was assembled from, listed in the document itself; not-stated is a member the subject has published nothing about, named explicitly, never omitted and never defaulted.
• Attribute: one checkable property from the set in Section 10.
• Profile: a named bundle of attributes a buyer reasons with; a profile always decomposes into its attributes.

3. The shape of the definition

Everything an agent is accountable for falls in one of three columns, and the columns have different truth mechanics, which is why they never mix.

What an agent answers is contract: ask the exchange, check the answer. What an agent declares is authored: verify the signature and the format, and treat the content as the operator's word, no more. What others attest is evidence: verify the issuer's signature, and weigh the issuer. A reader who knows which column a fact came from knows exactly how far to trust it, and a document that hides the column is misleading by construction; that is the rule the assembled view (Section 9) enforces for the whole family.

Beneath the columns sits the floor: the obligations that make the word "agent" mean anything at all. Sections 4 and 5 are the floor and the answered behavior above it; Section 6 is the declaration column; Section 7 the optional capabilities; Section 8 the attestation column; Section 9 the assembled view over all three; Section 10 the attributes that name what a given agent has actually earned.

4. The floor

An agent MUST meet every clause in this section. There is no partial floor.

4.1 An identity that signs

An agent holds exactly one Ed25519 keypair, generated on or provisioned to its host. The public key is the immutable agent identifier. Everything the agent authors is signed with this key or attributable to it through its binding's transport identity, and every claim about the agent binds to this key, never to a name. Names are attestations (Section 8.6): an agent MAY hold a handle bound to its key at a registrar, and a reader resolves the handle to the key, never the reverse.

The encryption key (OPTIONAL). An agent MAY additionally hold an X25519 keypair, distinct from its signing keypair, used only for receiving sealed content and never for signing. Its purpose is end-to-end confidentiality where the transport or its operator is not trusted to read payloads: a sender seals a message or a symmetric key to the agent's X25519 public key, and only the agent can open it. An agent that declares an encryption key publishes the public half in its declarations, together with a signed key claim binding the identity key to the encryption key. The key claim is REQUIRED wherever an encryption key is declared, because a reader MUST NOT seal to an unverifiable key. The signing key remains the agent's identity and address; the encryption key is a capability attached to it, and its absence simply means the agent participates only in cleartext.

Where sealing ends. Sealing terminates at the agent's host, because that is where the decryption seed lives, and "provisioned to its host" above includes a host the owner does not operate. An agent hosted on another party's infrastructure has that operator inside the sealed boundary: the operator opens payloads as the agent, which is not a violation of this section but the plain meaning of hosting. A declared encryption key is a statement about a key, not about who operates the host behind it; a sender whose threat model includes the recipient's host must establish where the recipient's agent runs by means outside this specification.

4.2 It says what it is, to anyone

An agent answers a description request before any relationship exists, and the answer is the one substantive thing a total stranger may ask: the agent's equivalent of an unauthenticated HTTP GET. Without it, every introduction is a cold knock on a closed door, and no third party can ever build a map of what exists.

Rules, all normative:

• The agent's node or platform MUST answer the description request regardless of the requester's admission standing; admission filtering (Section 7.1) MUST NOT apply to it.
• The response MUST be served from operator-declared content by the node or the platform on the agent's behalf. It MUST NOT invoke the agent's model, tools, or memory. It is a document, not a conversation. That sentence is the security argument, and implementations are expected to preserve it literally: nothing a stranger sends can make the agent think.
• The description request MUST NOT create a task, MUST NOT enqueue anything in the agent's inbox, and MUST be idempotent and side-effect-free.
• Implementations MUST rate-limit it per requester and SHOULD serve it from cache; the response changes when the operator edits the declarations, not per request.
• Visibility governs listing, not answering: an unlisted agent MUST still answer when addressed directly by identifier or handle, and MUST NOT appear in any listing. A private agent MAY refuse the description request entirely.
• The same document SHOULD also be served over plain HTTPS by the agent's home platform, so parties outside the network, including ordinary web crawlers, can read it without transport credentials. On-network strangers use the exchange; the rest of the web uses the URL. This is deliberate: a search engine will index a URL, and will never join a message bus.

The answer MAY be narrower for a stranger than for an admitted caller; it MUST NOT be false.

4.3 The five questions

The floor's exchanges say how a stranger reaches an agent. This clause says what every agent answers about itself: five questions, each with its answer already living in operator-declared, signed bytes rather than in the agent's head.

The rule of Section 4.2 applies to the whole set: implementations MUST serve these answers from the declared bytes at the node or SDK boundary and MUST NOT invoke the agent's model, tools, or memory to produce them. Pre-admission the five questions are answered by the entryway (Section 4.4); post-admission they are answered the same way, from the same bytes.

The consistency rule. An agent's statements about itself, wherever spoken, are subordinate to its signed declarations. Prose in a conversation, an answer to a buyer's question about its own price or capability or posture: where any of it conflicts with the declarations or the declared terms, the signed bytes govern, and a counterparty MAY rely on them without further inquiry. A persistent conflict is non-conformance, and it is detectable by construction: ask, then diff. Under this rule a stale declaration stops being an operational nuisance and becomes a checkable defect. The mouth and the signature must agree, and the signature is the one that answers.

The interview. The five questions are testable by code that holds no model. A conformance harness fetches the description document, verifies each materialized answer against the signed bytes it derives from, asks out-of-scope questions and expects the standard refusals, and, where it also converses, diffs the spoken answers against the declared ones under the consistency rule. A platform MAY record interview results as evidence beside its other form checks. Recorded results carry who ran them, and the distinction is mandatory in any display: a result an agent ran against itself is a claim; a result a platform or third party recorded is evidence; a surface MUST NOT present the first as the second.

4.4 The entryway

An agent answers five exchanges to a caller with no prior relationship. These are the entire pre-admission surface, and the invariant over all of them is: strangers may read, never run. No pre-admission exchange invokes the agent's model, tools, or memory.

1. What are you? The description of Section 4.2: what the implementer is called, what it does, what it charges, and what it refuses.
2. Show me your descriptor. The agent's current Agent Descriptor as the document's exact bytes with their digest, so the caller can check what it received and cite the version it read. An agent whose operator has published no descriptor MUST say so rather than answer with silence or an error.
3. Will you let me talk to you? A request to be admitted, carrying the caller's identity and nothing else. The answer states admitted, waiting, or refused, and a refusal names its reason.
4. Are you accepting new callers? The current admission policy, stated without reference to the caller asking. The answer MUST NOT name any other caller, nor say who has been admitted or refused.
5. Where do I stand? Never asked, waiting, admitted, or refused, for the caller asking. Exchange 3 is not answered on the spot in the general case, so a caller that could not ask this would have to guess.

The contract that travels with the exchanges:

1. All five are answered without admission. An entryway whose exchanges required admission could not do its job, because admission is the thing being asked for.
2. A request to be admitted carries no work. An agent MUST NOT perform work found in exchange 3, and a caller MUST NOT put work there. The exchange exists to be cheap to receive from a stranger, and an agent that acted on its contents would have given every stranger one free instruction.
3. A refusal is an answer. Silence is not. A caller that is turned away is told, and told why.
4. The roster stays private. Exchanges 4 and 5 tell a caller about the policy and about itself. Neither reveals another caller's standing, and an agent MUST NOT answer either one in a way that allows one to be enumerated from the other.
5. Admission is revocable and says nothing about work. Being admitted means the agent will receive what this caller sends. It is not a promise to accept any particular job, not a price, and not permanent. Once revoked, exchange 5 answers refused.
6. What it says about itself binds nothing. Exchange 1 is a description, not an offer, and a caller MUST NOT read a stated charge there as a price it can hold the agent to. What binds is a signed agreement (Section 7.6) or engagement.
7. No document of its own. The entryway defines no signed statement. The descriptor exchange 2 serves is defined by Section 6 and carried unchanged. Whether a caller was admitted is the agent's own business to keep; what gets signed belongs to the work that follows.

These five exchanges migrate here from the roles registry's entryway interface, where they were optional. On the floor they are not: the registry keeps role-shaped interfaces, and the before-any-relationship exchanges are what being an agent means. This promotion is the one substantive new obligation in this document.

4.5 The agent surface

An agent implements four inbound handlers, however its binding spells them:

Agents MAY implement additional handlers for composed operations but MUST NOT require counterparties to implement anything beyond these four.

4.6 It refuses outside its declared offerings, mechanically

There is no default route. A request naming an offering the agent has not declared is refused at the boundary with a typed not-found refusal, before anything that thinks sees it. This MUST be structural rather than behavioral: a conforming implementation cannot answer undeclared work, rather than being discouraged from it.

Conversation itself is an offering. An agent that can converse in natural language SHOULD declare a chat offering taking text and returning text; a sender that wants to talk requests it like any other offering. If the target has declared no such offering, the sender receives the same not-found refusal and learns the agent is reachable but not conversational. Tool-shaped agents that expose task offerings but no chat remain fully reachable by their declared offerings; they simply decline open conversation.

4.7 Every refusal is an answer

A refusal is typed, names its reason, and where the reason has a named check or fault, names that too. Silence toward an engaged counterparty is never an outcome: not for admission it has been granted, not for budget, not for a missing grant, not for a failed dependency. A system of agents is debuggable exactly to the degree its refusals explain themselves. When a task fails and the failure has a reason, the reason comes from a closed enum, and a failure blamed on a missing input MUST name a need the offering actually declares.

Silence has exactly one legitimate home, and it is deliberate: the inbound protections of Section 4.8 that exist to deny an attacker an oracle. A duplicate, stale, or misaddressed envelope is dropped without acknowledgement, and a blocked stranger cannot distinguish a block from "no such agent." Both rules are the same doctrine read from opposite sides: an engaged counterparty is owed an explanation; a probing stranger is owed nothing that maps the defenses. For the sender this yields a matching obligation: silence from a registered agent means possibly queued, never failed.

4.8 The inbound protections

Every agent enforces these before its model sees anything, in this order where order matters. Byte-exact fence text, window boundaries, and signed example envelopes are pinned by the binding's conformance fixture (Section 13).

1. Verify every envelope signature over the tagged signed bytes before any other check.
2. Reject duplicates on the pair of sender and message id: bounded memory, first-seen eviction, remember before judging.
3. Enforce a freshness window on every delivery path, with the binding stating its live, mailbox, and future-skew bounds.
4. Refuse misaddressed envelopes, silently.
5. Cap inbound sender text (default 65,536 UTF-16 code units) and answer with a typed too-large refusal.
6. Fence sender text with pinned markers before it reaches the model: once, on by default, provenance drawn from the verified envelope only. Inbound content is always presented as third-party material, never as the operator's own instructions; instructions embedded in somebody else's content are the attack being defended against.
7. Admit against the budget before working (Section 5.4): refuse with an estimate, never accept and then fail.
8. On admission by a live handler, signal acceptance immediately, before the handler runs; refusals of admission happen instead of the acceptance, never after it.
9. Never fetch a sender-chosen address implicitly, and never fetch anything before deciding to accept the message (Section 5.3).

5. Work

What an agent answers once engaged: the request round, the task lifecycle where work defers, the deliverables, and the money and time conversation. This section is the behavioral floor for any agent that accepts work; an agent that only emits and subscribes to events has no use for it and is not excused from Section 4.

5.1 Bare answers and tasks

A responder creates a task only when a request cannot be answered with a single terminal reply: when the work is long-running, streamed, or needs another round of input or authorization.

• No task (bare mode): the responder returns a terminal response with no task id. Nothing is persisted; the interaction is a single request and response round. This is the common case.
• Task (deferred mode): the responder returns a non-terminal response carrying a task id, then drives the task through its lifecycle. The task is the durable, resumable record of that work.

Requesters need no advance knowledge of which mode applies. The first substantive response tells them: a terminal status with no task id means done; a task id with a non-terminal status means subscribe for updates. An agent MUST NOT create a task solely to answer a request it can complete immediately, and error responses need not create one.

5.2 Task states and transitions

Non-terminal states: submitted (request received, task created, processing not begun), working, input_required, auth_required. Terminal states: completed (deliverables available), failed (an error during execution, details carried in the error), canceled (by requester or responder), rejected (the responder declined the task: cannot or will not perform the offering; distinct from failed), and exhausted (the governing engagement reached its cap and the work concluded there; deliverables produced before the cap remain attached, nothing past the cap is billable, and a runtime MUST NOT record an exhausted task as failed).

Legal transitions: none to submitted on receipt; submitted to working, canceled, exhausted, or rejected; working to completed, failed, input_required, auth_required, canceled, or exhausted; input_required and auth_required to working, canceled, or exhausted. Transitions not listed are invalid, and implementations MUST reject them with a typed invalid-transition refusal.

Tasks MUST be durably persisted, keyed by task id, in a store that is the authoritative source of truth for task state and updated on every transition. Updates and deliverable notices are published to the task's update channel for the requester, with the durable store remaining canonical for lookups.

Cancellation is honored: a closed reason enum, work stopped, and cancellation forwarded to every still-live delegate the responder engaged for the task.

5.3 Deliverables

Artifacts are the outputs of a task: the deliverables, distinct from conversational messages. An artifact carries one or more parts: inline text, inline structured data, or a reference to bytes held outside the message.

References. A reference is an opaque URI. Readers MUST resolve it through their runtime and MUST NOT parse it to locate the bytes themselves; a reference whose scheme the reader does not know is surfaced as unresolvable rather than guessed at. Every reference carries its media type and size, so a reader can decide whether to fetch before it does, and SHOULD carry a SHA-256 digest of the referenced bytes. A reader that fetches a reference carrying a digest MUST verify it and MUST treat a mismatch as a failed fetch. A digest's absence means unverifiable, never verified. Possession of a reference is the read capability: a reference can be forwarded, so anyone the holder shares it with can read the bytes, and content that must not travel that way is sealed before it is stored.

Inbound files and resources. In the other direction, a sender may hand the agent files or name shared resources the work happens in. Two rules protect the receiver. A receiver MUST NOT fetch a sender-chosen address implicitly: dereferencing automatically turns every agent into a fetch-on-demand proxy for whoever can address it. And a receiver SHOULD NOT fetch anything before it has decided to accept the message: a reference costs nothing to receive, the bytes do not, and fetching during admission lets an unadmitted sender spend the receiver's bandwidth and disk merely by addressing it. A resource entry states the intended access, and a receiver granted read access that intends to write has left the agreement, whatever the resource's own permissions happen to allow. A resource entry MUST NOT carry a credential in cleartext: a secret that must travel travels sealed, to a verified key, or not at all. When a responder holds write access, a change to the resource itself is a legitimate deliverable: the completing response then carries a pointer to what changed and a summary, not a copy of the bytes.

5.4 The budget

A budget is the requester's statement of the most a piece of work may cost and the latest it may finish. It is an offer, and acceptance means something: a responder reads the budget before doing any work, and accepting the request is a statement that it believes the work fits inside it.

A budget carries a deadline (an absolute UTC timestamp), a cost ceiling (denominated in currency), and a revision counter; at least one of deadline and ceiling is present. Only money and time appear, deliberately. Tokens are not fungible across agents: a token of a small model, a large model, and a reasoning pass differ in cost by orders of magnitude, and only the responder knows its own mix, so a token budget would be a constraint written in the responder's private units. The responder owns the conversion. A requester that cares about quality rather than spend should choose a different agent via discovery, not meter this one.

Admission. A responder that does not believe it can complete the work within the budget MUST refuse at admission, before doing the work, rather than accept and fail mid-flight: a budget-insufficient refusal when the ceiling is the problem, a deadline-unmeetable refusal when the deadline is. The refusal SHOULD carry the responder's estimate: its price, or its earliest realistic completion. Refuse-with-estimate is the negotiation mechanism, and it is the family's price-discovery loop: the refusal is equally legal against a request that offered no ceiling at all, in which case the estimate is a price quote and resubmitting at or above it is acceptance. A refusal driven by the responder's own spending policy (the allowance, Section 7.5) is deliberately indistinguishable on the wire from one driven by a too-low offer. Accepting work the budget never covered and then failing is the one outcome this section treats as the responder's fault, because it spends the requester's time, which is part of the budget.

What the deadline means. The deadline is the moment the requester's obligation to wait ends and the responder's authorization to spend ends. It is not a kill switch and it is not retroactive: deliverables produced before the deadline were delivered inside the budget and belong to the requester. Where a task manager holds the clock, it marks the task overdue at the deadline and notifies the requester, who then holds every partial deliverable received so far and a choice: cancel, or keep listening. A completion arriving after the deadline is accepted and recorded as completed late; what a late answer is worth is the requester's decision. Work past the deadline is at the responder's own risk and on its own account.

Hitting the ceiling. A responder that reaches the cost ceiling on work that turned out larger than either party thought MUST stop before crossing it and move the task to input_required with a budget-exhausted reason, reporting spend so far and an estimate to finish. The input required is money: the requester either raises the budget by revision and work resumes, or cancels and keeps the partial deliverables.

Revisions. Either party to a task MAY send a budget revision as a task update carrying only the budget. Revisions are absolute, never deltas: each revision states the entire budget, so a lost or reordered revision cannot corrupt anyone's arithmetic; the highest revision is simply the whole truth. Revisions from anyone but the task's requester or responder are rejected, as are revisions to tasks in a terminal state, and a revision cannot render the present moment retroactively over budget: it constrains only the future.

Enforcement, honestly. The spend half of this section is an honor-system MUST: nothing outside the responder can see inside it. What can be enforced without the responder's cooperation is time, because task state is held centrally. The budget therefore also defines the most a requester can ever be asked to pay for the work, and the overdue and late records support the natural settlement rule, that nothing is owed for work past the deadline, if settlement ever becomes real. Settlement itself is out of scope.

5.5 Usage and cost reporting

On completion, the responder SHOULD report its actual spend as a cost object in the terminal response, and reports declared usage cumulatively in the terminal response, superseding interim figures and covered by the envelope signature. The report is informative rather than normative, deliberately: you can oblige an agent to respect a ceiling, but you cannot oblige its spend report to be true. Verified metering is out of scope; what a platform can add is receipts (Section 7.6).

5.6 Context

A context groups related tasks into a logical session. If a request does not include a context id, the responder MUST generate one and include it in the response. If a request names both a task and a context, the responder MUST verify the task belongs to that context. Context expiration and cleanup are implementation-defined, and agents SHOULD document their retention in their declarations.

6. What an agent declares: the Agent Descriptor

The declaration surface is the Agent Descriptor: the operator's standing description of one agent, and the primary location for its metadata. What it does, what each offering takes and returns, who drives it, what it refuses, and where it runs, in one document, signed once bound, versioned by replacement, referenced at a digest. This chapter is the Descriptor's normative definition; the page at https://agentdoc.net/descriptor-spec.html is a rendering of it.

6.1 Primary, and others bind

An agent's facts end up spelled in several places: a description on a card, offerings on a registration, inputs in a contract, a model name in a config. Two spellings of one fact drift, and then a reader cannot tell which one the operator means. The Descriptor exists to end that: it is the one place the operator writes, and everything else derives from it or points into it.

A fact about the agent appears in the Descriptor once. A card or a manifest MAY carry a copy of a Descriptor fact, but only as a projection: derived from the Descriptor, never edited independently. A signed document that wants to make a Descriptor fact binding references it at a digest (Section 6.5) rather than restating it. A document that spells a Descriptor fact a second time, in its own words, does not conform to this section.

What the Descriptor is not: it is not a card, because it carries no endpoint and no authentication, which are connection facts, and the Descriptor holds shapes only (Section 6.4). It is not a contract: nothing in it binds anyone until a signed proposal references it. And it is not evidence: nothing issued by a third party after something happened is a member of it. Verdicts, records, and reputation check the Descriptor from outside.

6.2 The document

A Descriptor is a JSON object. Three members are required in every Descriptor, draft or bound:

The subject, draft and bound. The subject member holds the agent's key and handle: { "id": <public key>, "handle": <handle> }. A draft leaves subject absent, because a builder describes agents that do not exist yet; the subject is filled at deployment, when the agent receives its identity. Nothing binds to a draft: a signed proposal MUST NOT reference a Descriptor without a subject, and a registry MUST NOT store one as an agent's Descriptor. Once bound, a Descriptor's subject MUST NOT change. A new agent gets a new Descriptor, not an edited one.

Offerings. offerings[] carries one entry per hireable thing. Each entry has an id, a name, one sentence of description, and its inputs and outputs:

• inputs[]: each input's name, its kind (Section 6.3), whether it is required, and external: true when it is reached rather than furnished. An input that is a grant rather than a thing sent MAY carry via, one or more values from Agent SoW's grant-mechanism vocabulary, naming the mechanisms the operator accepts for making the grant. A caller reads it before deciding whether to engage, which is the point of stating it here.
• outputs[]: each deliverable's name, its kind, and when: per_task for a deliverable each task produces, standing for one maintained across tasks.

The line between an input and a system: something furnished or named per task is an input, and something bound once at deployment and used across tasks is a system (systems[], below).

Interaction and refusals. interaction is "interactive" when a person attends the agent and "service" when nobody is in the loop; the caller-side semantics are Section 6.7's. refusals is prose: what the agent will not do, in the operator's own words. Refusals gain force elsewhere, as SoW clauses and role contracts; here they are the operator's plain statement.

Extensions. Every member beyond the core is optional, and an absent one means not stated (Section 6.4):

A consumer that meets a member it does not recognise MUST ignore it rather than fail: an unknown extension is somebody else's business.

6.3 Kinds

An input or output kind is a media type where the thing is a file: application/pdf, application/gzip, text/csv. Not every input is a file, so four value kinds sit beside the media types:

A non-file input MUST use a value kind. Forcing an agent handle into a media type misdescribes it, and a consumer checking inputs would check the wrong thing.

6.4 The rules

1. Every fact has one authored spelling. A fact appears in the Descriptor once. Any other document carries a projection or a reference (Sections 6.1 and 6.8).
2. An absent member means not stated. A consumer MUST treat an absent member as something the operator has not said, never as a default. An unreadable member is treated as absent, never as the safe-sounding value.
3. It carries shapes only. Media types, region names, and system roles belong in a Descriptor. Addresses, credentials, endpoints, and account identifiers MUST NOT appear in one. A document violating this does not conform, whoever wrote it.
4. Evidence stays outside it. Nothing issued by a third party after something happened is a Descriptor member. A Descriptor states; records and verdicts check.

6.5 Versioning and the digest

A Descriptor is standing: true until its operator changes it. It is versioned by replacement. There is no partial edit; a new version is a whole new document.

The digest is over the exact bytes served, with no canonicalization. The digest of a Descriptor is the SHA-256 of the byte sequence a consumer fetched, exactly as fetched. This matches how an Agent SoW contract forms on bytes: a reference names an artifact, and the artifact is the bytes.

A reference to a Descriptor carries its digest, and MAY carry a location. A signed proposal that elevates Descriptor members references the Descriptor at its digest, which is why an operator's later edit cannot move what an existing signature meant.

agent_version orders versions of the agent, not edits of the document. Two Descriptors with different digests and the same agent_version are two spellings of the same agent version, and only the digest tells them apart. A Descriptor describing a changed agent MUST carry a new agent_version.

6.6 The signature

A bound Descriptor SHOULD carry the operator's signature, made with the subject's identity key, so a copy stays checkable wherever it travels. A bound Descriptor without one is trusted only as far as the place it was fetched from.

The signature follows the family convention (Section 8.1). The tag defined here:

• descriptor-statement-v1: the operator's statement that this is the subject's standing description. by MUST be the subject's own key, the same key as subject.id.

The digest (Section 6.5) is over the served bytes including signatures: a reference names the exact artifact, signature and all. The signature is over the canonical form without itself: a statement survives reserialization, an artifact does not, and the two jobs are different on purpose.

A draft has no subject and therefore no subject key, so a draft carries no descriptor-statement-v1 signature. Whoever passes a draft around vouches for it themselves.

6.7 Serving and discovery

The addresses. A subject reachable at a domain SHOULD serve its current Descriptor at https://<domain>/.well-known/agent-descriptor.json, beside the A2A card and the AgentDoc. Most agents are not reachable at a domain, so the general case is a pointer: the subject's registration SHOULD carry the location of its current Descriptor and that version's digest. A consumer who has found the agent has found its Descriptor.

The registry. At registration the subject SHOULD hand the registry the Descriptor itself, not only a pointer. A registry that stores Descriptors MUST serve the current one for a subject, MUST retain and serve every version it has stored by digest, and becomes the reliable place to fetch from when the operator's own serving goes away. Where a registry's stored copy and the operator's served copy disagree, a consumer MUST NOT merge them: the disagreement is reported, the same rule the assembled view follows for drifted projections.

Asking the agent. A subject SHOULD answer a request for its own current Descriptor, before any agreement exists, answering with the document bytes and their digest. This is entryway exchange 2 (Section 4.4); a consumer on the same network as the agent then needs no other serving at all.

History. A signed reference is only checkable while the version it names can still be fetched. Whoever serves Descriptors for a subject MUST keep serving each version they have served, by digest, for as long as they serve the subject at all. The registry's stored history is the backstop; an operator SHOULD keep their own. A countersigner is well advised to keep their own copy besides, since their signature is the reason the version matters.

Hosted agents. Where a platform hosts the agent, the platform serves the Descriptor on the operator's behalf, and that hosted copy is the authoritative home: the pointer in the registration points at it, and its bytes are the ones a digest names.

Knowing it changed. Replacing a Descriptor SHOULD be announced as an event where the subject is registered, so a consumer who cares can subscribe rather than poll. A consumer without the event compares digests on refetch. Staleness is detectable either way; the event only makes it cheap.

6.8 Projections and consumers

Four documents consume the Descriptor, each in its own way, and none of them edits its copy:

• The A2A card is generated from it: does becomes the description, offerings become skills, and kinds coarsen to input and output modes. The serving machinery adds the endpoint and authentication, which are connection facts the Descriptor never holds.
• The registration manifest carries the pointer and digest and projects interaction and the shape members it has fields for.
• An Agent SoW standing proposal elevates by reference: it signs Descriptor members at the Descriptor's digest, which is what turns a described input or price into a binding one. It does not restate them.
• An AgentDoc lists the Descriptor as a source, prefers it over any projection of it, records its digest, and reports rather than merges when a projection has drifted (Section 9.4).

A projection that disagrees with its Descriptor is a defect, and every consumer that can see the disagreement MUST report it rather than pick a side silently.

Checking a Descriptor is mechanical: the three required members are present, format names this specification, every kind is a media type or a defined value kind, no member carries an address, credential, or endpoint, a bound document's signature verifies against subject.id, and a draft carries no subject and no subject signature. An agent's behavior against its Descriptor's claims is a separate question, answered by an evaluator's signed record (Section 8.4), and never by this document about itself.

6.9 The wider declaration set

The declarations below are what a well-described agent states about itself beyond the Descriptor's core members. Each is carried by the Descriptor, by a document it points to, or by the binding's registration projection; each is the operator's word, presented as such.

Standing. One defined value: guest. A guest is an agent a platform provisions and operates on trial terms: temporary tenure, at the platform's expense, for a principal who runs nothing of their own yet. The declaration exists so a counterparty knows what it is dealing with before agreeing to anything, so a platform that hosts guests MUST declare it on every guest it provisions; an agent that is not a guest declares nothing here, and absent means not stated, never resident. Four obligations follow from the declaration, wherever it appears. A guest MUST run under an allowance (Section 7.5) at all times, and every cost the guest incurs is metered against it, including the guest's own model spend where the platform runs the model. A guest buys and never sells: it MUST NOT declare a price or hold offerings, and a registry MUST refuse both from a declared guest. A commitment a guest enters MUST fit inside its remaining allowance at signing, so no counterparty is ever owed money by a party built to expire. And a guest past its tenure refuses mechanically (Sections 4.6 and 4.7), stating that it has lapsed, rather than going silent. The tenure itself, how a guest is funded, how long it lasts, how many one principal may hold, is the platform's policy, stated where the platform binds this specification, never here.

Interaction, the caller's side. service means sending disturbs nobody, and a reply does not wait on human attention; interactive means delivery lands in a live session a human is using, sending may interrupt someone, and a reply arrives when they get to it. Absent means unknown, and a careful caller SHOULD treat unknown as interactive, the cautious reading. This is a statement of fact about how the agent currently runs, not a security boundary: an agent that misdeclares inconveniences callers rather than gaining privilege, and implementations SHOULD derive it from how they actually run rather than asking an operator to assert it.

Modes. The media types an offering accepts and produces, with agent-level defaults as fallback where an offering does not say. Resolution is the offering's own modes, then the agent's defaults, then nothing; and nothing means the agent has not said, which a caller reads as text and MUST NOT read as a refusal of other types. Agents that handle anything beyond text SHOULD declare, because a caller has no other way to learn it before sending: an agent that accepts PDFs and says nothing is indistinguishable from one that does not, and consumers faced with that silence have historically invented an answer on the agent's behalf.

Needs and delivers. What must be in hand before work can start, and what the caller gets. A need is a shared resource with an access level, a file by media type, a credential (a sign-in to a named third-party service the agent does not control, with the narrowest true scope stated), or prose. Delivers states the final deliverable, whether interim checkpoints arrive as task updates, and whether the deliverable lands in a caller-provided resource rather than travelling back. Both are declarations, deliberately loose: the reader at discovery time is usually a model deciding whom to hire, so they must read well to a model, not validate well in a parser. The honesty doctrine applies: an agent that needs a repository and says nothing is indistinguishable from one that needs nothing. A credential need is neither a permission nor a promise about handling, and nothing in the declaration transports a credential; a renderer SHOULD present a credential need more prominently than the other kinds, because it is the one entry a reader can be harmed by missing.

Reporting level. An offering MAY declare the progress-reporting level it offers, on an ordinal vocabulary compared meets-or-exceeds. It is an advertisement, not a clause, it is self-declared and MUST be shown as such, and an unreadable value is dropped at registration, because a declaration that cannot be read declares nothing and MUST NOT be presented as if it did.

Sealing posture. A declared encryption key says an agent can be sealed to; the sealing posture says whether anyone should, and what happens to a request that arrives in the clear. required means the agent will not read a cleartext request: a sender MUST seal, and the receiver MUST refuse an unsealed request with a typed sealing-required refusal. preferred means a sender SHOULD seal when it can, and the agent reads both. Absent means the agent has not said, and a sender MUST NOT infer a posture from silence, and MUST NOT seal to an agent that has not asked to be sealed to. A posture REQUIRES the encryption key, and a registry MUST refuse a declaration stating one without the other: a posture is a promise about reading, and an agent with no key cannot keep it. The sealed unit is the request's input and the terminal response's output: the caller's material and the deliverable. Routing, status, errors, and timing stay readable, so a sealing posture protects content, never the fact of the conversation, and an implementation MUST NOT describe it as anonymity or traffic confidentiality.

Data use. What happens to content a buyer hands the agent, declared once, at agent level, deliberately: the pipeline is the operator's, shared by every offering, and a per-offering split posture is a gaming surface. Promises carry only the promises made (no_training, no_third_party_sharing, no_human_reading), each spelled true: false is spelled by omission, because a promise left out is a promise not made, and a reader MUST NOT infer one. Retention states the ceiling in days the operator is prepared to bind. Processors name the services content passes through, which is what lets an agent built on an upstream model API make the no-third-party-sharing promise honestly instead of staying silent or lying; an empty processor list is a statement, an omitted one states nothing. Jurisdictions name where content may be processed and stored, as a set tested by subset against a buyer's allowed list; an operator that cannot truthfully pin a jurisdiction declares nothing, and an absent declaration fails any jurisdiction requirement, which is the correct fate for "we don't know where it runs" when the buyer asked. Confident fiction is the failure mode this declaration must not invite. Everything here is self-declared, MUST be shown as such, and an unreadable data-use declaration is dropped whole rather than served in part, because a partially readable privacy claim misleads more than none at all. What binds is the signed engagement's confidentiality clause; where the declaration and the signed document disagree, the signed document wins.

Compliance. The postures an operator claims (SOC 2, ISO 27001, GDPR, HIPAA, PCI-DSS, an open vocabulary of lowercase tokens compared by exact equality), each with a scope in words and an attestation pointer: an auditor's name, a URL a reader can follow, an expiry after which the claim is stale on its face. Everything here is self-declared, including the pointer; nothing fetches the URL, verifies the auditor, or checks the expiry against anything but the calendar. Directories MAY index and filter on the tokens under the same presentation rule: a filter over self-declared claims is a filter over claims, and labeling it otherwise is the platform lying on the operator's behalf.

Access. How a caller presents identity, and who gets in, and they are different questions: the scheme is the lock, the policy is whose key was cut. The admission policy is a closed vocabulary of four values: open (anyone who satisfies a scheme is admitted), allowlist (only parties the operator already added), screened (a knock is evaluated, by policy or a person, and may be refused on grounds the operator does not have to publish), negotiated (admission is arranged out of band before any knock is meaningful). The vocabulary is closed because it feeds a decision, whether it is worth knocking, and an unrecognized value MUST be treated as unstated rather than as open. The membership of an access list is never published: publishing it turns a storefront into a customer roster, and the one reader guaranteed to find it useful is the one probing for accounts to impersonate. Schemes are alternatives, never a conjunction: a caller satisfies any one. Three states, and silence is one of them: schemes declared, schemes declared empty (a real answer: nothing to present), and nothing said, and a reader MUST NOT collapse the third into the second, because an agent that never described its door is not an agent with an open one. Schemes are shapes, never bindings: a member whose value would differ from one caller to the next is a binding and does not belong. An access declaration MUST NOT carry a credential, token, key, secret, account or tenant identifier, or per-caller URL, and a registry that detects one MUST drop the block whole rather than serve it, for a sharper reason than usual: a secret served on a pre-admission page has already leaked by the time anyone notices it was a validation error. Declaring a scheme grants nothing: nothing here issues a credential or promises admission, and what a caller must furnish to do the work once admitted is the offering's needs declaration.

6.10 The declaration doctrine

Three rules bind every consumer of any declaration:

1. Absent means not stated. Never a default, never the flattering value, and printed by name in any assembled view. A requirement stated against a declaration treats silence as not meeting it: fail closed.
2. Shapes, never bindings. Declarations carry media types, roles, vocabularies, and regions; never credentials, endpoints, addresses, or account identifiers.
3. Declared is a strength, not a verdict. An authored claim enters every view at declared strength and moves only on attestation (Section 8). No consumer may render a self-declaration as verified or enforced.

7. Capabilities

A capability is an optional behavior set the agent opts into, declared so a counterparty can rely on it, and specified as an extension to this document. Each capability below is normative for the agents that declare it and invisible to those that do not. A binding MAY carry any of them natively; the obligations are the same on every binding.

7.1 The door

An agent's address is public: knowing it is enough to deliver a message, the same reachability model as email. For an agent, handling a message can mean a model call, so reach is a cost, and a stranger who guesses the address can spend the owner's tokens one message at a time if every inbound message reaches the agent. The transport authenticates who a sender is; it does not decide whether the agent should serve them. That decision belongs to the owner, and it must be enforced cheaply, before the model is consulted, from owner-set policy, not reasoned out per message by the agent itself.

The roster. Admission policy is a single JSON document owned by the account holder and signed by the owner key, portable by design so the policy is never trapped in one client or one deployment. It carries per-tier defaults, limits, and explicit entries, each naming a subject (a handle or a key) with a stance and a timestamp. The signature covers a domain-tagged form under the convention of Section 8.1. A consumer MUST verify the signature against the owner key before enforcing the roster and MUST reject an unsigned or invalidly signed one, falling back to the conservative defaults below. The signed roster is the export: a conformant implementation MUST be able to export and import it as one signed document, which is the anti-lock-in guarantee.

Tiers. Every inbound sender sorts into exactly one tier, for free, from identity the transport already verifies: rostered (an explicit entry matches), contact (an accepted mutual contact with no entry), registered (a verified identity, unknown to you), anonymous (no verified identity). Most-specific wins: an explicit entry always overrides the tier default. An implementation SHOULD ship defaults that protect an owner who sets nothing: contact allows, registered holds, anonymous blocks.

Admission and discovery consent are different relationships and never conflate: an accepted contact informs the default, but admission is the owner's alone, and a block always wins over any contact relationship.

Stances. block: not delivered, and MUST NOT be acknowledged; a blocked sender MUST NOT be able to tell a block from "no such agent." hold: queued for owner review, and MUST NOT invoke the agent; this is the zero-cost path, and the point of the tier: an unknown sender never costs a model call. allow: delivered for handling. Two limits back the stances: a per-sender hourly rate cap applied even to allowed senders, so a compromised or looping friend cannot drain you (RECOMMENDED), and a daily ceiling on model spend answering inbound, independent of who is asking (REQUIRED for any client that invokes a paid model on inbound).

Enforcement placement. The cost gate MUST live with the recipient's own client or node, because only it knows what handling a message costs and what its budget is, and a client MUST function with no network-side enforcement at all. Upstream enforcement, where offered, enforces a projection of the roster and is never the authority.

The knock. With anonymous-block as the default, an unlisted sender's first message vanishes without a trace: correct for spam, but leaving a legitimate stranger no way to politely ask. The knock fills that gap: entryway exchange 3, deliberately content-free; the sender's signed identity, and through resolution its handle and operator label, are the entire message. A knock MUST NOT invoke the agent and MUST NOT enter the inbox: its only effect is a held-attempt report surfacing the sender in the owner's waiting list. It MUST be rate-limited independently of message limits (RECOMMENDED one per sender per day, with a global daily cap), and the response MUST be identical for every outcome, so a knock cannot probe roster state. Any pre-delivery enforcement layer MUST pass knocks through regardless of the sender's tier stance: they are the one envelope a blocked-tier sender may deliver, and the recipient's own rate limits bound the cost.

Held review. Held senders accumulate in a review queue the owner resolves to allow or block; notification MAY use out-of-band channels. The report to the owner carries who knocked, never what they said: sender key, resolved handle and operator label, timestamps, and an attempt count; message bodies, excerpts, subject lines, and sizes MUST NOT be reported. Reports are idempotent, and waiting entries expire after 30 days without a repeat attempt, so the list means "senders currently waiting on you," not an archive. The owner's decision is transported as intent, but the signed roster remains the enforced artifact: the recipient applies the decision to its own roster, re-signs under the owner key, and releases or drops the held mail locally. Authority never moves, and the recipient MUST NOT enforce an unsigned document.

Revocation. A roster edit: setting a stance to block takes effect on the next signed roster and is enforced with no distinguishable acknowledgement. Admission is permission to reach, not a statement about authorship: every delivered message still self-verifies, and an allow never lets a sender speak as someone else.

7.2 Sealed conversations

The transport is secured; that does not hide payloads from the platform. This capability closes that for direct messages: when the recipient has declared an encryption key, the request payload crosses the network as ciphertext only the recipient can open, and the reply comes back the same way.

A sender SHOULD seal whenever it knows the recipient's declared encryption key, obtained from the recipient's published card or declarations; the key is public and pre-distributed, and sealing costs one box. A sender MAY refuse to send in cleartext at all. An agent that declares no key participates only in cleartext. What is never sealed: envelope headers (routing, trace, signature; the transport needs them, and the signature already binds sender to ciphertext), knocks (content-free by definition), and held-attempt metadata. Admission gating is unaffected: stances act on the verified sender, not the payload.

The sealed form. The payload, and only the payload, is replaced by a sealed object carrying a version discriminator, an ephemeral X25519 public key, a nonce, the ciphertext, and an optional reply key (the sender's durable X25519 public key). The box is NaCl crypto_box (X25519 with XSalsa20-Poly1305). The outer keypair is ephemeral per message: sender identity does not ride the crypto layer, because the Ed25519 envelope signature already proves authorship, and it signs the ciphertext, so tampering breaks before decryption is attempted. The plaintext is the canonical JSON of the payload that would otherwise have been sent.

Reply sealing. The reply key names where the answer should go. A recipient answering a sealed message SHOULD seal to it and include its own key as the new reply key, so a sealed thread stays sealed hop by hop. A responder MUST resolve a claimed reply key against the sender's own published encryption key and MUST refuse to seal to one that disagrees with it. A responder that opened a sealed request whose sender asked for a sealed reply, and cannot resolve a key to seal to, MUST NOT answer in the clear: an error is the correct outcome. A sealed request carrying no reply key asked for nothing and MAY be answered in the clear.

Failure. A sealed payload that does not open (wrong recipient, tampering, garbage) MUST NOT be processed or queued. The recipient SHOULD log locally and return the same generic acknowledgement shape a delivery would produce, consistent with the door's indistinguishability rule. There is no renegotiation: the remedy for a key mismatch is re-resolving the recipient's published card, whose signature and pinning make a silently swapped key loud.

What it protects. The network routes and, transiently for offline delivery, stores ciphertext. The receiving agent's node opens the box and stores plaintext in its local inbox: the node is the agent's trust boundary, the same place held mail already lives, and Section 4.1's hosting caveat applies in full.

7.3 Screening

This capability defines a socket, not a detector: a recipient-side consultation point where an owner-chosen screening provider is asked about content before the agent reads it, and a small vocabulary for the answer. It carries no detection logic and never will. A detector shipped under the platform's name makes every miss the platform's miss, and detection quality in this field changes weekly; providers who sell exactly this can price that liability, and a protocol cannot. The honesty rule travels with it: an account with no provider configured is unscreened, an implementation MUST be able to report that state plainly, and MUST NOT describe an unscreened account as protected.

Where it happens. Interception is always local to the recipient: the agent's own node calls the screener, and nothing is screened in transit or by the platform. This is forced, not preferred: sealed payloads cannot be read by the platform, so platform-side screening would silently cover unsealed traffic only, a partial guarantee that reads as a total one, which is worse than none. Once the recipient has plaintext, sending a copy to a screener the owner chose is the recipient exercising a right it already holds: showing its own mail to an advisor. The provider may be an HTTPS service or another agent consulted through the ordinary request exchange. Consultation, never proxy: the message is delivered as it always was, the screener receives a copy and returns an opinion, never holds custody, never sits in the delivery path, never re-originates. Three properties depend on this: the sender's end-to-end identity stays intact, a screener outage degrades to the owner's configured stance instead of stopping mail, and a screener cannot silently drop or reorder traffic it dislikes.

The request. Carries the content to be judged and the facts a judge needs: direction, call site, an opaque provider-side policy handle the platform never interprets, and counterparty facts: identity, the admission stance in force, relationship age and depth (a day-old identity claiming to be your brother is exactly as suspicious as it looks), and whether the payload arrived sealed. Content is always presented as third-party material: implementations MUST NOT submit inbound content in a field a provider treats as the operator's own prompt.

Call sites. A message is not read once. Each of these is a distinct moment at which content reaches a model, and each MUST pass the socket when a provider is configured: delivery (an inbound message is about to be handed to the agent), history (a durable shared conversation's record is being replayed: an injection posted in March is read for the first time in June by a member who joined in May, and screening only at delivery leaves that hole open by construction), fetch (a shared file's bytes have been fetched and digest-verified, before the agent reads them: a file is judged when its bytes are read, not when the record noted it), board (a posted work item is being read, and certainly before it is claimed: claiming means deliberately acting on a stranger's written instructions, so a poisoned item is an injection with a built-in execution mechanism), and send (outbound, the agent is about to send content to a counterparty). Outbound is on by default wherever a provider is configured: the moment of damage in a successful injection is rarely the reading, it is the sending, your files and context to a counterparty the attacker chose, and a protective measure that only works once its owner finds the setting protects nobody. An owner may narrow to inbound alone, and should know what that gives up. An outbound hold refuses the send and says so to the agent that asked; an outbound flag sends and records, because the content is the owner's own agent's work, and stopping it on a maybe produces an agent that mysteriously will not speak.

Verdicts. pass: nothing found, delivered normally. flag: suspicious, not certain, delivered with the reason attached. hold: should not reach the agent unreviewed; routed to the door as a held item, with the reason, for the owner to release or block. The reason MUST be a plain sentence an owner can act on; the provider detail is opaque, recorded verbatim, and never branched on. Hold rather than block, deliberately: "ignore what I said earlier" is ordinary human speech, a screen that silently destroys mail on a false positive destroys trust faster than any attack, and the door is already the mechanism for "a human should look at this first." Verdicts are personal: two recipients with different providers may reach different verdicts about the same content, and both are correct; each owner bought the judgment they chose.

When the screener does not answer (unreachable, timed out, malformed), the recipient applies the owner's configured stance: fail closed (hold) or fail open (deliver and log loudly), and either way the outcome is recorded as an unscreened delivery, never as a pass: a timeout is not a clean bill of health. The default is fail closed: configuring a screener is somebody asking for their mail to be looked at, and delivering it unlooked-at is the opposite of that, not a smaller version. The asymmetry decides it: held mail is visible at the door and released in one click; mail that slipped through during an outage is invisible for ever.

Sealed content is screened by default, because an exemption the sender can trigger unilaterally (seal your attack to skip the screener) is not a policy, it is a documented bypass. But it is the owner's knowing choice: implementations that screen sealed content MUST disclose it in the configuration surface and MUST support per-counterparty exemption, so an owner can keep specific correspondents (a lawyer, a doctor) out of the screener's view without switching screening off. Exemption belongs to the recipient, by name.

The record. Every verdict, including pass, including an unscreened delivery, is written to the receiving agent's audit chain with the provider id, policy handle, and policy version, keyed to the message id or content digest it concerned. After an incident, an owner can prove what was screened, by whom, under which policy version, and what the provider said; it also makes a provider's track record provable rather than claimed. In shared contexts, a screener MAY sit as an ordinary, visible member, so consent is visible rather than buried in configuration; any member MAY write a verdict annotation, additive metadata that never alters or hides the annotated content, always carrying its author, and never presented as the room's own verdict. A shared verdict is a signal, not a substitute: a member whose own provider is configured still screens on fetch.

7.4 Systems health

An agent's tool fails: the credential is wrong, the grant expired, the vendor rate-limited the tenant. Four parties need to learn this at four different speeds. The running instance needs it immediately, so it stops burning attempts. Sibling instances and the owner's other agents on the same grant need it within seconds, so they do not each rediscover it. The owner needs it on their screen, because for the whole grant-fault class the fix is theirs. And a counterparty mid-engagement needs it when they ask or when a task fails, not by broadcast. Traces serve none of these: they arrive hours later, after every instance in the window has failed the same way.

The fault vocabulary. A fault names what stopped the system and, by its class, whose move the fix is. Six values, and the set is open: an unrecognized value is carried verbatim, never dropped.

A fault report names the system by its ROLE, the same vocabulary as the agent's declared systems and its delegation grants: never a vendor, never an endpoint, and a report MUST NOT carry the upstream error body, because error bodies leak tenant identifiers and request content.

The report door. The runtime cannot see inside the agent's harness, so the agent reports: a verb pair (report a fault, clear it) on the CLI and the local session surface, and an SDK hook that SHOULD also report automatically where the SDK's own tool client sees an auth or rate-limit failure. A report is the agent's own statement about its own tooling. The record's door accepts at most sixty reports per agent per hour and refuses beyond with the limit named: state changes are rare by nature, an agent reporting faster is looping, and the agent's own local state is unaffected by the refusal. A report MAY name a system the agent's public declaration never listed, because health is the agent's private truth; but the circuit never refuses work on an undeclared system's account, because an agent's private tooling failures must not change its public behavior in ways nothing in its public record explains. The consequence is deliberate: an agent that reaches systems it does not declare gets no fast-refusal protection, which is one more reason to declare.

The circuit. The runtime keeps one state per declared system role: ok, degraded, or failing, with the current fault, when it started, and the count. A grant-class fault moves the system to failing immediately: these do not heal by retrying, so the first report is conclusive until the grant changes. Rate-limiting and unreachability move it to degraded, and to failing after repeated reports inside a short window. A success report, or the operator's clearing verb, returns it to ok; while failing on a transient fault, the runtime retries at half-open intervals, honoring the retry-after. While a system is failing on a grant-class fault, a new request whose offering declares that system among its needs is refused fast, with the typed fault, instead of being attempted: the caller learns in milliseconds what a doomed attempt would have told them in minutes, and the refusal names whose move the fix is. Transient faults do not refuse: the work is attempted and the state rides along as a warning. The state is visible in the agent's local status surface and never enters the public declarations, because health is not a standing fact.

The private record. State changes are written to a per-agent health record the platform keeps: current state per system role, shapes only, no bodies, no vendors, no endpoints. Two readers are the point: the owner's surfaces (each grant's health beside its revoke control, and a grant-class fault raises a needs-you item, because the grantor is the one person who can fix it), and sibling instances holding the same grant, which read the record before attempting. The record is deliberately not a public broadcast: days of "the CRM grant is failing" is operational intelligence about a business, and publishing it by default would punish exactly the agents that report honestly. An operator who wants a public status surface MAY declare a systems state feed carrying the same shapes; that is a choice, never a side effect of reporting.

The counterparty. Directed, never broadcast. A task that fails on a system fault carries the typed fault in its error, as a dependency-fault code with the report as its detail. An answer to a progress inquiry MAY carry the active faults for the systems that engagement declares. And where the failing grant is the client's own grant to this agent, the fault SHOULD reach the client as a needs-you item, not only as a task failure, because "your grant stopped working" is a to-do, not a status.

Nothing in this capability ever carries a credential, a vendor name, an endpoint, or an upstream error body. Traces remain forensics after the fact, neither replaced nor fed, and no reputation is written here: the loud path is made cheap, and no new score is created.

7.5 The allowance

The family has two spending ceilings, easy to conflate, enforced in different places because they cross different boundaries. A budget travels with work, between parties: the requester attaches it, it guards the requester's money against the responder's appetite, and it binds the responder; it is an offer in a negotiation between agents that may not trust each other, which is why it rides the signed request. An allowance stays at home, within one household: the owner sets it on their own agent, it guards the owner's money against their own agent's appetite, and it binds nobody but that agent's own runtime. No counterparty ever sees it, verifies it, or cares, which is why it is a locally held signed policy document rather than a wire field: it crosses no trust boundary. One sentence: a budget is what you'll pay someone else; an allowance is what you'll let your own agent burn. When one interaction has both, each is enforced where it lives, and the tighter of the two decides.

The document. One JSON document per agent, signed by the owner key under the convention of Section 8.1 and held at the agent's runtime. It carries the governed agent key, the owner key, a cost model (the owner's DECLARED conversion from the agent's tokens to money: the runtime cannot learn the model's price, so the owner states it, and a token rate is legitimate here where it is forbidden on the wire, because inside one household the owner knows exactly whose units they are), one or more ceilings each scoped to a task, a context, or the UTC day (optionally narrowed to one named task or context), an on-exhausted behavior (refuse or ask_owner), and a timestamp. The document is replaced whole; the latest timestamp under a valid signature is the policy. Money is integer micro-units of an ISO 4217 currency; no floating point ever touches money.

Fail closed. A runtime MUST verify the signature against the owner key before enforcing, and MUST NOT treat a document that fails verification as absent: a configured allowance that does not verify treats every ceiling as exhausted until a valid document replaces it. Failing open here is failing open on the owner's money.

Enforcement. The runtime meters each model invocation against the cost model with integer floor arithmetic, accounted to the task, the task's context, and the UTC day. It refuses at admission work that would exceed a ceiling, through the budget's refusal-with-estimate: the estimate is a price quote, resubmission at or above it is acceptance, and on the wire an allowance-broke refusal is indistinguishable from a budget-broke one, deliberately, so a counterparty never learns which ceiling it hit. Every applicable ceiling applies at once: specificity determines what a ceiling covers, never which one wins, and the binding ceiling for a given decision is whichever applicable ceiling has the smallest remaining amount. On exhaustion, refuse answers the refusal-with-estimate; ask_owner pauses instead: the runtime holds the work, surfaces the question through the owner channel the door's review already uses, and proceeds only if the owner raises the ceiling. Deadlines are the budget's concern, not this document's: an allowance has no time axis.

Visibility without enforcement. Spend is honor-system; nothing outside the runtime can see inside it. What the platform can do is make the honor system observable: per-context spend rollups from metering receipts, scoped to the requesting owner's agents; and an owner MAY register the signed allowance, in which case reported spend crossing a ceiling SHOULD surface as an operator-visible exceeded event and an owner notification. The platform never blocks: an exceeded allowance is a fact made visible, not a delivery decision, and enforcement belongs to the runtime that holds the owner's policy, and to nobody upstream of it.

Out of scope by declaration: settlement and payment; cross-agent allowances (constraining someone else's agent is a contract, not a config: it crosses a trust boundary, and the instrument for that is the budget on a signed request, never a policy document the other party cannot verify was ever enforced); and external mandate mapping, parked with the field name reserved.

7.6 Pricing and agreements

SKUs. What an agent sells is declared as a SKU, a named unit of commercial terms: what is covered, what it costs, and who bills for it. Each SKU has a stable identifier, a covers clause (the whole agent or a named subset of its offerings; where SKUs overlap, the most specific match applies), a price, and a billing provider. An offering covered by no SKU is free. That is the default, and paid is the declared exception: charging is something an operator says out loud, never something a consumer discovers on an invoice. Free is also declarable as an explicit price model, so a free offering can still carry terms and a provider: agreement without money is a terms gate.

Price shapes. A closed five: free; flat (a fixed amount per delivered request); per-unit (an amount per N units of a named meter, floored in integer arithmetic); package (an amount per package of units over a period, partial packages rounded up); tiered (graduated: each tier rates its own span; volume pricing, the whole quantity at the reached tier's rate, is deliberately not offered: one shape, no flag). An optional included block grants a free daily or monthly allowance deducted before rating. Money is non-negative integer micro-units of an ISO 4217 currency, with private-use X codes legal where a deployment clears in its own credit unit.

Comparability. Flat prices are comparable across agents; declared-meter prices are not. A token is each responder's private unit, so a per-unit price on tokens is indicative of that agent's own arithmetic, never a basis for cross-agent comparison. The number that binds an interaction is the budget's cost ceiling, denominated in currency precisely because currency is the unit that is fungible across agents. SKUs travel on the agent's public surface, advertised pre-admission, so a buyer compares terms before ever messaging the agent.

Digest-pinned terms. A SKU's digest is the hash of its tagged bytes, and any change to coverage, price, or provider moves it. The digest is what an agreement binds to, so no consumer can be rated against terms they never accepted. For a terms URL, the digest covers the URL, not the document behind it; an operator who edits the document at an unchanged URL is changing terms out from under standing agreements, so providers SHOULD version terms URLs.

Agreements. An agreement binds a consumer account to a SKU at a specific digest, signed by the consumer's OWNER key, never an agent key, because it is a human's money: one person approves once, every agent under that owner is covered, and an agent cannot click through a terms page. A digest mismatch is a missing agreement: when the seller changes terms, every standing agreement goes stale at once, and re-approval is the rule; there is no grandfathering because there is nothing to grandfather. Agreements are revocable by their signer, prospectively only: usage already metered under a live agreement remains rated. Enforcement is the seller's admission-time obligation: a request whose offering is covered by a non-free SKU, from a consumer whose owner holds no unexpired agreement at the SKU's current digest, MUST be refused before any work with a typed agreement-required refusal carrying the SKU id, its digest, and an approval URL.

Metering and receipts. The responder's obligations are Section 5.5's. The platform SHOULD emit one receipt per completed task: a derived fold of the task's meter events plus its budget context, recording the parties, the offering, timing, the responder's claimed cost (informative, since nothing can see inside the responder), the final budget that applied, and whether completion arrived late. Canceled tasks get a receipt too, under a distinct name carrying the cancellation reason, because a cancellation ends spending authority the way a completion does, and a consumer folding completed receipts must never have cancellations arrive under the completed name. Token counts are deliberately absent from the receipt: a bare token count is meaningless across responders; the receipt summarizes money and terms, and the meter events carry the quantities.

Rating. Rating MUST be a pure function of the event stream, the SKUs, and the registered agreements: replaying the same events reproduces the same charges to the micro-unit, all arithmetic integer. No agreement, no charge: an event for a paid SKU with no agreement matching the digest current at the event's timestamp rates to zero, a recorded fact, never a retroactive bill; enforcement should have refused the work, and rating declining to charge is the second wall. Refusal events rate to zero, always. The ceiling binds rating: rated charges against a budget MUST NOT exceed its cost ceiling, and a responder that declares more quantity than the ceiling covers has declared unpaid work: the honor system given mechanical teeth by arithmetic, not by dispute.

8. What others attest

8.1 The record convention

Every attestation in this family is a JSON document with a signatures array of { "tag", "by", "sig", "alg": "ed25519" } entries, where sig is the Ed25519 signature, base64, over the ASCII tag, one newline, and the JCS (RFC 8785) canonical JSON of the document with signatures removed. by is the issuer's key, and what that key is worth is the reader's judgment: an attestation is evidence, not truth.

Rules that bind every producer and consumer:

1. The by-equality rule. The record's own by member, the signature entry's by, and, where a door accepts the record over an authenticated channel, the submitting identity MUST all be the same key. A record signed by one key and submitted by another is refused at the door and shown as failed by a reader.
2. A failed record is shown, not dropped. A record whose signature does not verify moves nothing anywhere, and is carried as failed rather than discarded, because a reader must be able to see that a bad record exists.
3. Unsigned is a stated condition. A record produced where no key was available carries "signatures": [] and an _unsigned note; the note is outside every signature by construction and never covered. An unsigned record is a claim with no issuer and weighs accordingly.
4. Unknown members are carried verbatim, never dropped: a signed document does not become unreadable when a format grows.
5. The common trunk. Every record states its format generation, the role of its producer, the act it records, when it was produced, and who produced it, alongside the members its own format defines.

8.2 The build record

Tag agent-build-record-v1, issued by whoever built an agent package, at build time, attesting that these bytes were produced by this builder at this moment. It says nothing about whether the agent is any good, and a package's draft status survives the record.

8.3 The deployment record

Tag agent-deployment-record-v1, issued by whoever deployed a package as a running agent, in a deploy and a remove variant. This record is the natural version authority for a running agent: it exists at exactly the moment the running version changes, and evaluations and reviews SHOULD cite it.

8.4 The evaluation record

Tag agent-eval-record-v1, issued by an evaluator that tested a subject against what its package, role, or interfaces oblige.

A verified evaluation record moves the covered members of an assembled view (Section 9) to confirmed or failed; coverage is by name and never invented, and a consumer that stores or displays these records enforces the by-equality rule at its door.

8.5 Normalizations against current producers

The member tables above state the normalized formats. The shipped producers deviate in six known ways, each a queued producer update rather than a spec concession: the deployment record does not yet carry descriptor_digest (only the ephemeral deploy output does); the deployment record names its subject agent rather than subject; requested_by and instructed_by are emitted as fixed literals rather than principals; the two shipped consumers check signature attribution asymmetrically where this document requires the by-equality rule everywhere; the unsigned fallback shape varies; and the per-format package sub-objects differ in member sets, which this document keeps, because a build, a deployment, and an evaluation genuinely know different things about a package.

8.6 Attestations defined elsewhere

Handle cards belong to the registrar's specification, reputation reports to the bureau's, listings to the Agent Listing Model, delegation chains to Agent Mandate, and engagement documents to Agent SoW. Each is an attestation in this section's sense: signed by its issuer, verified before weighed, weighed by the reader.

9. The assembled view: the AgentDoc

An agent describes itself in the Descriptor; others attest in their records; and nobody deciding whether to engage an agent wants six fetches and a mental merge. The AgentDoc is one document that assembles them, served from a known location, in a form a program can act on and a person can read. This chapter is the AgentDoc's normative definition; the page at https://agentdoc.net/spec.html is a rendering of it.

JavaDoc and Swagger did the same thing, and it is worth being precise about which part of it matters. Neither 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. The AgentDoc does that for an agent, with one addition neither of them needed. An API description has no interested party. An agent description is written by somebody selling something, so every part of an AgentDoc says where it came from.

9.1 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 how: they drift from the API they describe, then they mislead, and then people stop trusting the format rather than the file.

So an AgentDoc is generated, and this specification makes that structural rather than advisory: an AgentDoc MUST NOT contain a fact that is not present in a source it lists (Section 9.3). There is nowhere to type a claim. An operator who wants their AgentDoc to say something changes the source it would be assembled from: their Descriptor for a standing fact, or the signed document for a binding one.

It is not a new source of truth, and it is not a registry. The card, the terms, the listing, and the reputation report remain what they always were. An AgentDoc is a view, and a view that outlives its sources misleads while looking current, which is why staleness is visible rather than fatal (Section 9.3). It also does not compete with the A2A Agent Card: where the two overlap, an AgentDoc restates the card and cites it (Section 9.9).

9.2 Where an AgentDoc lives

An agent reachable at a domain SHOULD serve its AgentDoc at https://<domain>/.well-known/agentdoc.json, beside the A2A Agent Card at its own well-known path. A reader who has one address has both.

An AgentDoc MAY also be served by somebody who is not the subject. A directory that assembles AgentDocs for every agent it lists is a conforming assembler, and its documents are as valid as the subject's own, because the sources are checkable rather than anybody being trusted. The location above is where the subject's copy goes, not a claim of exclusivity. An agent that is not reachable at a domain, which is most agents on a network, has its AgentDoc served wherever its operator or its directory serves it, and the document is unchanged: the format does not depend on the address. Every AgentDoc SHOULD also be available as a human page at the same path without the .json extension, rendered from the same document (Section 9.8).

9.3 The rules that make it worth reading

Every section names its sources. Each section of an AgentDoc carries from, listing the source identifiers it was assembled from. A section with no source does not conform. This is what lets a reader take any single line and go and check it. Where a member came from a different source than its section's other members, it carries its own pointer: any member MAY be accompanied by <member>_from, naming one source id. This is a narrowing, never a widening: a member-level pointer MUST name a source already listed in the section's from, and its only job is to say which of them.

An assembler adds no facts. An AgentDoc MUST NOT state anything that is not in a listed source. Reformatting, unit conversion, and restating a signed value in a section are all fine. Inference is not: an assembler that concludes an agent "probably handles European data" from a European address has manufactured a claim the agent never made, and the agent will be held to it. Where an assembler wants to publish its own opinion about a subject, that is a recommendation, and the roles registry already defines the role that produces one.

There is no summary grade. An AgentDoc MUST NOT carry a single overall score, badge, tier, or trust label for its subject. An assembled document does not need a badge, because it has something better: it says where each part came from, and the reader can see that the price is from a signed standing proposal and the capability blurb is from a text field the operator typed. Provenance is the evidence. A badge is a summary of provenance that discards the part that mattered.

It says when it was assembled, and it goes stale. Every AgentDoc carries assembled_at, and every source carries when it was fetched. A reader MUST be able to tell how old the view is. An AgentDoc MAY carry stale_after; past that moment a reader SHOULD treat it as an old view rather than a false one: the sources it cites are still fetchable, and re-assembling is the remedy. An expired AgentDoc is not invalid, it is out of date, and those are different enough to be worth separate words.

What the assembler signs, and what it does not. An assembler MAY sign an AgentDoc with agentdoc-assembly-v1 (Section 9.11). The signature means exactly one thing: this assembler gathered these sources at this time and reported them faithfully. It is not a claim that the subject's statements are true, and it MUST NOT be presented as one. An assembler signs its own work, never the subject's. Where a source was itself signed, the AgentDoc records that separately, per source; those two signatures answer different questions and must never be shown as one.

9.4 The document and its sources

Top level:

{
  "agentdoc": "v1",
  "subject": { "id": "…", "handle": "…", "name": "…" },
  "assembled_at": "2026-08-29T18:04:00Z",
  "assembled_by": "…",
  "stale_after": "2026-09-05T18:04:00Z",
  "sources": [ … ],
  "sections": { … },
  "not_stated": [ … ],
  "signatures": [ ]
}

subject.id is the agent's stable identifier, normally its public key; handle and name are conveniences and MAY be absent; id MUST NOT be. assembled_by identifies the assembler, and where the assembler is the subject's own operator it says so, because a self-assembled AgentDoc and a third-party one are different things to a reader and the difference should not require inference.

Sources. Each entry describes one thing the AgentDoc was built from: an id the sections reference, a kind, a url, fetched_at, a digest, and signature, one of verified, unsigned, failed, or not_checked. unsigned and not_checked are different facts and MUST NOT be collapsed: one says the document carried no signature, the other says this assembler did not look. Defined kinds: a2a-card, agent-manifest, sow-standing-proposal, listing, reputation-report, roles-declaration, interface-definition, plugin-package, agent-descriptor, eval-record, and observation; others MAY be used and SHOULD be namespaced. An observation source is something the assembler did rather than fetched: asking an agent whether it was free, and recording the answer and the moment. It carries at and what in place of url, and it is the only source kind that can go out of date within a minute.

Packaged agents as a source. Most agents will exist as a package before anybody writes them a document, and plugin-package names one. It is a legitimate source, and this specification says exactly what may be taken from it, because the temptation to take more is strong and the package is not a document about the agent, it is the agent. Derivable: the name, the version, the description, and the tool list split by transport; that split is the one thing in a package a buyer genuinely needs and cannot get elsewhere, because a tool that runs as a local process is the provider's own machinery while a tool reached over a URL means content leaves the building. Never derivable, and an assembler MUST NOT infer them: price, pricing arrangement, inputs, deliverables, refusals, jurisdictions, retention, interfaces, or admission. Never carried at all: env values, command, args, cwd, and header values, which are bindings and machinery and the members most likely to hold a secret. An importer produces a draft, never an AgentDoc: what a package's author types in answer to the questions the package cannot answer MUST land in a signed card or standing proposal, from which an AgentDoc then assembles. Writing those answers straight into an AgentDoc would make the importer the one place in the system where a claim can be typed into a format built on there being nowhere to type one.

A declared role as a source. A roles-declaration source is a role's published contract, listed because the subject itself declares the role: the role's standard offering name appears among the offerings on the subject's own card or manifest. An assembler MUST NOT list a role the subject has not declared; behaving like a bookkeeper, being named like one, or matching one's description is not a declaration. The source fills the role section, and MAY fill inherited sections by citation: the exchanges from the role's primary interface, the role's refusals into refuses, and the role's handling rules into handling. Every member filled this way enters at the declared state and never higher, because a declared role is the subject's claim about itself; an evaluation record is what moves an inherited member past declared. An inherited refusal carries kind: "role", a third value beside prose and clause: stronger than a sentence in a description, because the subject staked a standard name on it, and weaker than a signed clause, because no counterparty holds it. The vocabulary is shared with the roles registry on purpose: the registry owns the must-form and this specification owns the does-form, and neither restates the other's.

The Descriptor as a source. An agent-descriptor source is the subject's own Descriptor (Section 6). Where one exists, it is the authored source for the sections it covers, and an assembler SHOULD prefer it over any projection of it. What it fills: the one-sentence description, the offerings with their inputs and outputs into sells, interaction and the shape members into shape, the refusal prose into refuses (as kind: "prose"), the declared role and interfaces (which the assembler then resolves as above), the hosting regions, the standing systems into reaches, and the per-caller limits. Every member enters at the declared state, because a Descriptor is the operator's word about their own agent. Two rules travel with it: the source entry records the Descriptor's digest, because a signed proposal references a Descriptor at a digest and a reader must be able to tell whether the document assembled here is the one a signature meant; and where a projection of the Descriptor disagrees with the Descriptor itself, an assembler MUST NOT merge them silently: the Descriptor's value is carried, and the disagreement is reported.

An evaluation record as a source. An eval-record source is a signed verdict from a conformance evaluation of the subject: an agent-eval-record-v1 document (Section 8.4), naming the subject, the package or contract it was graded against by digest, and a per-case result. It is the checking source: the one kind of document that can move an inherited or declared member to confirmed or failed. The mapping is per case and never wholesale: a passing case on an exchange or a refusal confirms that member, with the record's timestamp; a failing case marks it failed, and a recorded failure MUST NOT be silently downgraded to declared. A verdict whose overall answer is that the subject does not conform does not erase the subject's declarations; it sits beside them, case by case, which is exactly what a reader deciding whether to trust the subject needs to see. An assembler MUST verify the record's signature against the evaluator key inside it and record the result like any source, and MUST NOT treat an unsigned verdict as confirmation of anything.

9.5 The sections

Every section is optional. An absent section means the subject published nothing to build it from, and Section 9.6 requires that absence be named.

• identity: who it is. Name, operator, address, and what signs for it.
• shape: what it is. Whether it is a service or a person's own agent, what it runs on, whether it is one process or a fleet behind one identity.
• asked: what it can be asked. The largest section, and the one a caller acts on.
• role: the standard role it holds, if any.
• sells: what it actually does. Each offering with what the client furnishes, what comes back, and what it costs.
• access: how you reach it at all. What a caller presents, and who is let in.
• refuses: what it will not do. Drawn from its declared scope, its role's refusals, and its terms. This section is usually the most useful one on the page and is usually the emptiest, which is itself worth seeing.
• reaches: the standing systems it runs with, from the Descriptor's systems member: a role, an access level, and what the access is for.
• handling: where it processes data and how long it keeps it, cited to the terms that promise it.
• standing: what third parties have published about it: reputation reports, attestations, directory checks. Carried, never audited, and attributed.

The asked section, in full. This is the section a caller actually acts on, and it is the reason an AgentDoc is worth fetching rather than reading a description. An interface entry names the interface, the version, where its definition lives, and every exchange that definition publishes, each with its own state. It MUST NOT be reduced to a name and a version: a reader who has to go and fetch the interface definition to find out what they may send has not been given a description at all.

"asked": {
  "from": ["card", "iface-worker", "probe"],
  "interfaces": [
    {
      "name": "interface-worker",
      "version": "v1",
      "definition": "https://agentroles.ai/worker.html",
      "declared_in": "card",
      "exchanges": [
        { "id": "free", "asks": "are you free?",
          "answer_carries": ["free", "reason when not", "job when not"],
          "state": "confirmed",
          "confirmed_at": "2026-08-29T18:04:00Z", "confirmed_by": "probe" },
        { "id": "estimate", "asks": "what would this take?",
          "answer_carries": ["can (CAN|CANNOT|UNSURE)", "commitment", "note"],
          "state": "declared" }
      ]
    }
  ]
}

Three rules govern it. The exchange list comes from the interface definition, and the definition is a source: an assembler does not invent the exchanges, it resolves the published interface and lists what that publication says, citing it like any other source. State is per exchange, never per interface: an assembler that asked one exchange and got a conforming answer has confirmed one exchange, and marking the whole interface confirmed on that basis is exactly the overclaiming the no-added-facts rule forbids, in the place a reader is most likely to rely on it; the states are declared, confirmed (with the timestamp and the observation that did it), and failed (a fact worth carrying, and MUST NOT be silently downgraded to declared). And a declared interface with no exchanges listed does not conform: if the assembler could not resolve the definition, it says so with the interface present and its exchanges absent, and names the interface in not_stated.

The sells section, in full. asked says how to hand work over and follow it; this section says what the work is. Each offering carries what the client furnishes, what comes back, and what it costs, quoted from the standing proposal that offers it.

"sells": {
  "from": ["card", "terms"],
  "offerings": [
    {
      "name": "clause-review",
      "does": "Reads a contract and reports unusual or one-sided clauses.",
      "inputs": [
        { "name": "contract", "media_type": "application/pdf", "when": "per_task" },
        { "name": "house-positions", "media_type": "text/markdown", "when": "standing" }
      ],
      "deliverables": {
        "per_task": [
          { "name": "clause-report", "media_type": "application/pdf" },
          { "name": "flags", "media_type": "application/json" }
        ],
        "interim": [
          { "name": "summary", "media_type": "application/pdf",
            "recurrence": { "every": "month", "due_by_day": 5 } }
        ]
      },
      "price": "12000 XCR per document",
      "arrangement": "per_task",
      "minimum": 50,
      "does_from": "card"
    }
  ]
}

inputs carries name, media_type and when (per_task or standing). deliverables splits into per_task, the artifacts attached to each completed task, and interim, the engagement-level obligations the provider owes on a schedule whether or not the client asked. minimum is a floor the offering's terms set; arrangement is the pricing arrangement the standing proposal declares. All of these are Agent SoW's own members and this specification does not redefine them: it quotes them, and where that standard changes, this one follows. Three things about this section: these are not descriptions, they are obligations (Agent SoW grades both enforced: a task arriving without a required input moves to input_required naming what is missing, and a task claiming completion without every named deliverable in the named media type is a failed task, so a reader is looking at what the runtime will hold the provider to, not at a brochure); form is enforced and quality is not, and an AgentDoc MUST NOT blur that, because nothing here says the deliverable will be any good, which is what reputation is for; and does is prose and is marked as such, sitting beside signed clauses without being dressed as one. An offering whose standing proposal names no inputs or no deliverables lists neither and names them in not_stated: an agent that has not said what it needs from you, or what you get back, has not promised either.

The access section, in full. It carries two different facts, and merging them is the mistake it exists to prevent: schemes is what a caller presents, admission is who gets in, both quoted from the subject's declarations (Section 6.9) and defined there, not here. statement is the free-text sentence beside the policy, carried as prose. Three rules govern it. Silence and "nothing required" are different, and both must be printed: schemes present and non-empty means the subject said what to present, an empty list means it said there is nothing to present, and an absent section means it never said, named in not_stated like any other silence; a renderer MUST NOT show the third as the second, because an agent that never described its door rendering as an agent with an open one is an invitation to send credentials to something nobody has checked. An AgentDoc carries shapes and MUST NOT carry bindings, even when a source does, and this binds the assembler and not only the subject: a directed Agent SoW proposal legitimately names a counterparty's real repository or endpoint, because it is a term between two identified parties, but an AgentDoc is a public document, and an assembler that reads such a source MUST NOT copy those values in, and MUST NOT do so on the grounds that the source was signed: a signature attests who said it, never that publishing it is safe. And a scheme list is alternatives: a renderer that presents it as a checklist tells a reader they need credentials they do not need.

What the agent needs granted is deliberately not a member of this section: it is per-offering, typed by Agent SoW as a shared-resource input with an access level and a via, and it rides in sells with the rest of what an offering asks for.

The remaining sections (identity, shape, role, refuses, reaches, handling, standing) are small. Four rules rather than preferences: interaction is the service-or-personal axis, not a description of the software, and whether one process answers or a fleet behind one identity does is fleet, separately optional. refuses.kind is prose, clause, or role, because a sentence in a description field, a term in a signed proposal, and a role's staked refusal are materially different strengths, and an AgentDoc that cannot tell which it has omits kind rather than guessing. handling members are quoted from Agent SoW, and promises is that standard's list; this one adds nothing to it. standing carries other people's documents and audits none of them: each entry says who published it, where it is, and what it was as of, and an AgentDoc MUST NOT summarise, average, or grade what it finds there, which would be the summary grade arrived at indirectly.

What is not stated. not_stated is an array of section or member paths the subject has published nothing about, for example ["role", "handling.retention_max_days"]. This exists because silence is the most common answer in this whole family and the easiest one to lose: a missing field renders as nothing at all, and nothing at all looks like a document that simply did not mention an unimportant detail. Naming it makes the reader see the agent declined, or never got round, to say where it processes your data.

9.6 Silence never resolves to the flattering value

An assembler MUST NOT substitute a default for a member the subject has not stated, and MUST NOT choose the reading that favours the subject. An agent that has said nothing about retention has not promised to delete anything. An agent with no published price is not free. An agent that has not declared an interface does not implement it, whatever its prose says. An unreadable or malformed member is not-stated, not the safe-sounding value: a typo must never manufacture a promise. Where a reader needs a default in order to act, the default belongs to the reader's own policy, applied by the reader, visibly. It does not belong in a document that describes somebody else.

9.7 What the subject controls

A subject MUST be able to correct an AgentDoc about itself, and the mechanism is already the design: change the signed source, and the next assembly changes with it. An assembler that continues to publish a section citing a source that has since changed, without re-fetching, is not conforming. A subject MUST NOT be able to compel an assembler to omit a source it lawfully holds, or to remove not_stated entries. An AgentDoc that a subject can edit directly is the hand-written file Section 9.1 exists to prevent.

9.8 The human rendering

An AgentDoc SHOULD be renderable as a page, from the same document, with no additional input. The rendering MUST show, for every section, which sources it came from, and MUST show not_stated as visibly as it shows what was stated: a renderer that hides absence produces exactly the flattering picture Section 9.6 forbids, by omission rather than by assertion. The rendering MUST show when the AgentDoc was assembled, and where stale_after is present it SHOULD show that too. The rendering MUST NOT introduce a badge, score, or trust mark that the document does not contain.

Three rules preserve differences that are invisible once lost. Undeclared reach is not an empty reach: where the reaches section is absent the rendering MUST show it as not stated and MUST NOT present the subject as touching nothing, because an agent that has said nothing about what it reaches has not promised it reaches nothing. A grant is not a file: where an offering's inputs include a shared resource, the rendering MUST show those separately from inputs the client simply sends, and within them MUST show standing grants above per-task ones, because a standing grant is the only thing on the page that is still true after the work is finished. An undeclared door is not an open one: where the access section is absent, the rendering MUST show it as not stated and MUST NOT render it as though nothing were required.

9.9 Relationship to the A2A Agent Card

The card is a source, and normally the first one. An AgentDoc restates card members in its sections and cites the card; it never contradicts it. Where the card carries family extensions, the terms extension in particular, the AgentDoc follows them to the documents they commit to and lists those as further sources. An AgentDoc is therefore a superset of a card's content and a subset of a card's reach: the card is fetched by tools that have never heard of this specification, and it MUST remain valid and useful on its own. Nothing here asks an operator to stop publishing a card, or changes what a card means.

9.10 Checking an AgentDoc

Mechanical, and unusually easy for a document of this kind, because an AgentDoc makes claims about its own construction. Given an AgentDoc and the ability to fetch its sources, a harness checks: that every section's from names sources that exist in the document; that every listed source is fetchable and, where a digest is recorded, matches it; that every fact in every section appears in one of that section's cited sources; that no member of the document is a summary grade; that assembled_at and per-source fetched_at are present; that a member absent from every source appears in not_stated rather than being silently missing; and that no not-stated member has been given a default. The one thing a harness cannot check is whether the subject's statements are true, and no version of this specification will claim otherwise.

9.11 The assembly signature

• agentdoc-assembly-v1: an assembler's statement that it gathered the listed sources at the stated time and reported them faithfully, signed under the family convention of Section 8.1, by being the assembler's own key.

An AgentDoc MAY carry more than one signature entry, and an entry whose tag a reader does not recognise is skipped, not treated as a failure: an unknown signature is somebody else's business. The subject signs nothing here. Its statements are signed in their own documents, which is where a reader should go to check them, and saying so is what the format is for.

10. The twenty attributes

The floor is mandated. Everything above it is earned, checkable, and deliberately not a score: each attribute is an artifact or a behavior a reader can fetch and verify, and an attribute's absence is a printed fact, never a deduction. Each attribute belongs to one of the three columns, which states how it is checked: an answered attribute is checked by asking, a declared one by verifying the authored document, an attested one by verifying an issuer's record.

Attributes and interfaces divide cleanly, and this section owns only one of the two. An interface, published at the roles registry, is a set of exchanges: what may be asked of an agent and what each answer must carry, named, versioned, and open-ended in number, because every trade can define its own. An attribute is a standing property with a truth mechanic, one of the closed set below, and an attribute never defines an exchange. Where an attribute's check is behavioral, the attribute names the test that backs it and the exchanges live only there: Askable is backed by the entryway (Section 4.4), and Candid is backed by the interview (Section 4.3). The bundles are parallel and never mix parts: a role bundles interfaces and obligations at the registry; a profile bundles attributes here. In a rendered view the two stay distinct the same way: attributes are the properties a page summarizes, interfaces are the exchange lists its asked section carries (Section 9.5), and a behaviorally backed attribute points at the exchanges that prove it rather than restating them.

Identity

Description

Conduct

Commerce

Standing

Profiles are how buyers actually read the attributes: "hireable by a stranger" decomposes into roughly named, described, doored, priced, and contractable; "safe to grant write access" into owned, mandated, candid, and reputable. A profile MUST always decompose into its attributes in any rendering; a profile presented as a single mark is a score wearing a costume, and scores are refused across this family.

11. Bindings

A binding connects an agent to a network. It supplies transport identity verification, message delivery, registration and discovery, and its network's delivery semantics; it spells the floor's exchanges as its own verbs and subjects; it pins the byte-level constants this document leaves symbolic (fence text, freshness windows, envelope formats); and it projects the agent's declarations into its own registration format, derived and never independently edited.

The AgentMesh protocol is the reference binding. Its specification is being narrowed to exactly this role: the network's transport, envelope, delivery, and platform services, with this document as the definition of the thing being connected. Its manifest is the registration projection of the Agent Descriptor. An agent conforming to this document on one binding conforms on any: nothing in Sections 4 through 10 names a transport.

12. How an agent travels: the Agent Package

An agent has an inside and an outside. The inside is what it is made of: skills, the scripts they run, the servers they reach. The outside is what a caller can rely on: what it does, what it refuses, what it needs, what it leaves behind, which is the Descriptor of Section 6. The inside has a portable format of its own, the Agent Plugin, whose standard says in its own words that distribution, installation, and permissions stay under each client's control. This chapter defines the thing that carries both halves from a description to a running agent with an identity: the Agent Package, what it contains, how the halves are joined, how it is published to and installed from a depot, and how a verifier can check that the agent answering on a network is the package that was built.

It is not a package format: Agent Plugins defines the layout and the manifest, and Agent Skills defines a skill folder; this chapter adds two files beside the manifest and one namespace inside it, restating neither. It is not a runtime, not a listing, and not a change to any wire.

12.1 Terms

These are the words this chapter uses for the things an install joins, and they are used in this sense throughout.

• Host: the machine an agent runs on. One host may hold many agents, each with its own home and its own identity.
• Harness: the program that does the thinking when a message arrives, whether a coding tool driven from a terminal, a model runner, or an agent framework. A harness is not an agent: it is what an agent runs on, and one harness may serve many agents on one host.
• Package: an Agent Plugin directory, or its archive, carrying a draft Descriptor and an install file at the paths in 12.2. A package is not an agent: it carries no subject, and until it is installed nobody can address it.
• Draft Descriptor: a Descriptor without a subject (6.2.1), inside a package. Bound Descriptor: the same document with its subject filled and signed, served by the running agent.
• Install file: the host-facing declaration of 12.4: what an installer must have and do.
• Agent: what exists after an install: a subject with a key and a handle, a home on a host, a harness configured to read the package, and whatever parts the binding requires to receive messages and answer them.
• Bare agent: an agent that carries no package and answers as its harness alone. It has a subject and a Descriptor like any other agent; what it does not have is offerings a package declared.
• Depot: where packages are published to and fetched from, by name, version, and digest. A depot is not a registry of agents (6.7): it holds packages, which contain drafts, and it never serves a draft as any agent's Descriptor.
• Installer: whatever performs 12.7; on a conforming deployment, an agent holding the deployment manager role of the roles registry.

An owner instructs a deploy; the installer installs the package; the result is an agent. The three words are not interchangeable: the deploy is the instruction, the install is the procedure, and the agent is what the procedure leaves behind.

12.2 Layout

A package is an Agent Plugin. Its portable parts are exactly what that standard says: plugin.json, skills/, and optionally mcp.json. Beside the manifest sit the two authored files this chapter adds, and one namespace directory holds the views generated from them.

<name>/
├── plugin.json                  the Agent Plugins manifest
├── descriptor.json              the draft Descriptor: every caller-facing fact
├── install.json                 the install file: every host-facing fact
├── skills/<offering-id>/        one skill per offering: SKILL.md, scripts/, references/
├── mcp.json                     servers by role, no vendor (optional)
└── net.agentdoc.package/        NOT.md, RECORDS.md, SYSTEMS.md, generated

The manifest's extension entry for the namespace net.agentdoc.package carries pointers and digests, never copies:

"extensions": {
  "net.agentdoc.package": {
    "descriptor": { "path": "descriptor.json", "sha256": "<digest>" },
    "install":    { "path": "install.json",    "sha256": "<digest>" },
    "built": true,
    "draft": true
  }
}

The namespace is the same for every conforming implementation, so any reader that knows this chapter finds the pointers under one key. A package MUST declare the Agent Plugins schema version that clients read, and an implementation SHOULD validate against a pinned copy of that schema rather than a fetched one, so that a moved or unavailable address cannot make a valid package unverifiable.

12.3 The draft Descriptor

The draft Descriptor is the only authored spelling of every caller-facing fact in the package. Every rule of Section 6 applies to it unchanged: no subject, shapes only and never an address, credential, or endpoint, an absent member means not stated, versioned by replacement with its digest over exact bytes. Its refusals member is prose, and a builder SHOULD write it as one sentence per line, because an evaluator turns each refusal into a probe and a line is the one boundary it can rely on.

Two members are added to the Descriptor by this chapter, both optional and both ignored by a consumer that does not know them, as 6.2.4 requires:

• records[]: what the agent must leave behind, each with a name, when (per_task or standing), and an optional file, a pattern relative to the records directory. A record is not an output: outputs are what a caller receives, records are what an operator and an auditor can inspect, and a caller reading outputs would be misled by a spend log listed among deliverables. An audit with the pattern is exact; without it, it falls back to the name.
• escalates[]: what always goes to a person, one sentence each.

A system in systems[] to which the agent sends a caller's material during the work SHOULD say so with leaves: true; a caller deciding whether to engage is entitled to know that their text leaves the agent.

12.4 The install file

The install file is the host-facing half. Everything in it is something an installer must have or do, and nothing in it is something a caller could act on. It MUST NOT contain a credential value, an address, an account identifier, or a host path outside the package: it names things, and the host resolves the names. Its format is "agent-install-v1", and it has five sections:

1. runtimes[] and binaries[]: what must be present on the host before install proceeds, each with a purpose a person can read. The installer MUST check each and MUST stop and escalate when one is missing, never substitute.
2. dependencies[]: what the skills' scripts need, per skill, as a lockfile with integrity hashes carried under the skill's own folder, and the lockfile's digest. The installer MUST install from the lockfile into the agent's own home, never system-wide, and MUST NOT execute install-time scripts or lifecycle hooks of any kind.
3. systems[]: one entry per role the Descriptor names, and no others; the two sets MUST be equal. Each entry says what kind of thing the role is bound to (directory, mcp, or service) and, for a service, the name of the credential the scripts expect, the environment variable they read it from, and whether the service spends and in what unit. Kind mcp binds the role to an entry in mcp.json, which names the server by the same role and carries no vendor address. A service whose scripts also read a non-secret value the host must supply, such as a billing project, lists it under settings by variable name and purpose; the instruction supplies the value at install, and the record names the variable.
4. ceilings[]: which spending systems need a ceiling and per what. The install file says a ceiling is required; the owner's instruction sets the number; the platform enforces it. A spending system with no ceiling entry does not conform.
5. directories[]: the working directories the installer creates and binds, including where records land.

{
  "format": "agent-install-v1",
  "runtimes":  [ { "name": "node", "version": ">=22" } ],
  "binaries":  [ { "name": "chromium", "purpose": "renders every step for the fit check" } ],
  "dependencies": [ { "skill": "check-the-fit", "lockfile": "skills/check-the-fit/scripts/package-lock.json", "sha256": "<digest>" } ],
  "systems": [
    { "role": "text-to-speech", "kind": "service", "credential": "tts-key", "env": "TTS_TOKEN", "spends": { "unit": "characters" } },
    { "role": "draft-host",     "kind": "service", "credential": "draft-host-writer", "env": "DRAFT_HOST_TOKEN" },
    { "role": "brand-assets",   "kind": "directory" }
  ],
  "ceilings":    [ { "system": "text-to-speech", "per": "task" } ],
  "directories": [ { "name": "records", "purpose": "every record the descriptor names" }, { "name": "work" } ]
}

12.5 Skills and the generated views

One skill per offering, named by the offering's id, and no skill without an offering. A skill folder is an Agent Skill and MAY carry scripts/ and references/; its instructions are the place for the long-form judgment an agent needs to do the job well, and this chapter places no limit on their length. A skill MAY ship an acceptance check, a script that reads the skill's declared outputs and answers pass or fail on their form; it judges form, never quality.

NOT.md, RECORDS.md, and SYSTEMS.md exist so that a harness which reads markdown has them, and for no other reason. They are projections of the two authored files, generated by the builder, MUST NOT be edited by hand, and a checker regenerates them and compares bytes.

12.6 The rules

1. One authored spelling. A caller-facing fact appears in the draft Descriptor and nowhere else in the package; a host-facing fact appears in the install file and nowhere else. The manifest points, the markdown projects, and neither restates.
2. The inside matches the outside. Every offering has exactly one skill and every skill an offering; every system role in the Descriptor has exactly one install entry and every entry a role; every mcp.json server is a role.
3. Shapes in the Descriptor, names in the install file, values nowhere. A package MUST NOT contain a credential value, an address, an endpoint, or an account identifier in any file, and a depot MUST refuse to publish one that does.
4. Nothing commercial. A package carries no price, no handling terms, and no claim about who may call the agent or whether a person attends it. Those attach at listing and at install, by whoever makes those decisions.
5. One digest. A package is published and installed as an archive, and its SHA-256 over the archive bytes is the package's digest. Every record that mentions the package names that digest.
6. The bound Descriptor is the draft plus a subject. The Descriptor a running agent serves MUST differ from the draft in its package only by the presence of subject and signatures and by the members the install decides: interaction, shape, and agent_version when the draft leaves it empty (rule 4 keeps those out of the package). The deployment record names which members the binding added or changed. Any other difference means the agent is not the package that was built, and a verifier reports it.
7. Nobody runs a package's code but the agent. The depot executes nothing. The installer executes nothing from the package. The agent's harness runs the skills' scripts, in the agent's own home, with the credentials placed for it and no others.
8. No hidden characters. A depot MUST scan every text file for zero-width characters, bidirectional controls, and the tag block before publishing, and refuse a package carrying one. Agent configuration has no gap between install and execution the way code does, so the check belongs at the door.

12.7 Publish, install, update, remove

Publish. A package is published to a depot by name and version, signed by its builder. A publish MUST carry the build record (8.2) whose package.sha256 equals the digest of the bytes being published, and a depot MUST refuse a publish without one or with a digest that does not match. A published version is immutable; a version can be withdrawn, which marks it and stops new installs, and is never deleted, because deploy records point at it. A depot serves bytes by digest and indexes the draft Descriptor and the install file, so a search can answer what a package does, refuses, needs, and spends; a package whose install file declares nothing is indexed as "not stated", never as needing nothing. A depot SHOULD expose list-versions, download, and publish over the registry HTTP API that Agent Package Manager clients speak, so the skills in its packages reach any client that installs plugins.

Install, on instruction from an owner and under the deployment manager's contract, in order: fetch by name and version and verify the digest against the build record and the manifest against the pinned schema; check every runtime and binary; create the agent's home and the declared directories; install the dependencies from each lockfile, executing nothing from the package; bind each system, a directory to a path under the home, an mcp entry to the address the instruction supplies, a service to the credential the instruction names, fetched from the owner's store and placed in the agent's environment, and refuse a request that contains a credential value before the value is used; set each required ceiling to the number the instruction gives, and stop when a spending system has none; translate the skills, views, and instructions into the form the target harness reads; mint the subject and bind the draft into the bound Descriptor by adding subject and the operator's signature, placed where the agent serves it; start the agent and check it with the grade stated, smoke or conformance; produce the deployment record (8.3) with the package digest, the bound Descriptor's digest, the credentials placed by name, the ceilings set, and the checks.

Update installs a new version under the same subject: agent_version MUST increase and the subject MUST NOT change; the old version's files are retained until the check passes, and a failed check restores them; the record names both package digests and both Descriptor digests. Rollback is an update to the previous version.

Remove lists what was removed and what remains, under remaining, which is empty only when the removal was complete; placed credentials are removed and named. The subject's Descriptor history at the registry is not removed (6.7).

The ledger. An installer MUST record every file it placed and each file's digest, in the deployment record or in a ledger it names, and answer "what is deployed" by rehashing those files and reporting every difference, so a hand edit to a running agent's instructions is detectable rather than invisible.

12.8 Provenance

Three records join by digest. The build record names the package digest, the draft Descriptor's digest, each lockfile's digest, and the checks the builder ran with their grade, unrun or acceptance, with draft always true. The deployment record names the package digest, the bound Descriptor's digest, the subject, the credentials placed by name, the ceilings, and the graded checks. The evaluation record (8.4) names the bound Descriptor's digest and the verdict.

A verifier fetches the package by the deployment record's digest and confirms the bytes hash to it; confirms the build record names the same digest and its signature verifies against the builder's key; fetches the draft from the package and the bound Descriptor from the agent and confirms they differ only by subject and signatures; confirms the bound Descriptor's signature verifies against the subject's key; and confirms the evaluation record names that digest. A verifier that completes all five knows what is running and who vouched for each step. It does not know that the work is good, which no document about an agent can say. The evaluation record is optional. A verifier without one knows what is running and who vouched for the build and the deploy, and nothing about whether the work is done; an AgentDoc prints that nothing has been evaluated rather than hiding it. An agent a person attends is not evaluated by probing, because the person would be answering; the deploy's own graded check is the check it carries.

12.9 What stays out of a package

The agent's identity, handle, admission list, and attendance, which are the owner's decisions at install. Price and handling terms, which attach at listing, and which the Descriptor points at rather than holds. Evidence: the three records are about a package and never inside one. The runtime: a package declares what a host must have and never carries the harness that runs it.

12.10 Conformance

A checker verifies a package mechanically: the layout of 12.2; the manifest validates against the pinned schema; the draft Descriptor conforms to Section 6 and carries no subject; the install file has its five sections with no values, addresses, or paths outside the package; one skill per offering and one offering per skill; the system roles in the Descriptor and the install file are the same set; every mcp.json server is a role with no address; the generated views match a fresh generation byte for byte; the manifest's digests match the files; and no text file carries a hidden character. A depot conforms when it refuses a publish without a matching build record, serves immutable versions by digest, marks rather than deletes on withdraw, indexes the two authored files, and scans for hidden characters. An installer conforms when it follows 12.7 in order, stops on a missing runtime, binary, credential, or ceiling, executes nothing from the package, produces a bound Descriptor that differs from the draft only by subject and signatures, keeps the ledger, and states the grade of its check.

13. Conformance

The floor is checked mechanically, and a conforming deployment ships the checker: a program that asks Section 4's exchanges of an agent and treats silence as failure, because absence of an error is not evidence of permission. The interview of Section 4.3 is the template. Descriptor checking is Section 6.8's; AgentDoc checking is Section 9.10's. Attribute claims are checked by fetching their artifacts. Behavioral conformance to interfaces and roles is the evaluator's territory, and its verdicts are Section 8.4 records.

Byte-exact obligations are pinned by conformance fixtures, under the family's fixture doctrine: the fixture is the authority, and when an implementation disagrees with it, the implementation is what changes; every case is checkable without a network or a clock, cases whose verdict depends on time carrying their own now; and a fixture contains cases that MUST be accepted as well as cases that MUST be refused, because a fixture of refusals alone is passed by an implementation that refuses everything. Fixture identities are test vectors and control nothing.

Nothing in this section produces a score.

14. Out of scope

The harness, the model, and everything about how the agent thinks. The quality of the work. The network wire: envelopes, subjects, delivery semantics, and transport credentials belong to bindings. Settlement and payment. Whether the subject is any good: the assembled view reports what was said and by whom, judgment is a matchmaker's job, and quality is the reputation bureau's. Discovery: finding agents is a directory's job. Human organizational structure beyond what the mandate chain proves. And any composite mark, badge, or level that does not decompose into checkable attributes.

Appendix A: the migration map

Where each section's text came from, and what stays behind. Transport-specific terms (subjects, endpoints, buckets, broker mechanics) were neutralized throughout; the sources keep the bindings. The sources were cut down on 2026-09-01: each affected section of AgentMesh SPEC.md, EXT-6, EXT-7, EXT-8, EXT-10, EXT-12, and the roles registry's entryway now carries a governing note naming its chapter here, and this document governs the agent's behavior. The sources remain authoritative for what stays behind: the bindings.

Changelog

0.5.0-draft (2026-09-05): the Agent Package. Section 12 defines how an agent travels from a description to a running party: an Agent Plugin carrying the draft Descriptor and an install file beside its manifest, under the namespace net.agentdoc.package; two proposed Descriptor members, records and escalates, and leaves on a system entry; the eight rules, the strongest being that a bound Descriptor differs from its draft only by subject, signatures, and the instance members the install decides; a service's non-secret settings named in the install file; publish to a depot gated on the build record, install in order with credentials by name and nothing executed from the package, update under the same subject, honest removal, and the deployed-file ledger; and the five-step provenance check across the build, deployment, and evaluation records. Former Sections 12 and 13 renumber to 13 and 14.

0.4.0-draft (2026-09-01): guest standing and the deployment environment. Section 6.9 gains the standing declaration: guest names an agent a platform provisions and operates on trial terms, and the declaration carries four obligations, a mandatory allowance covering everything the guest costs, buying never selling, commitments that fit inside the remaining allowance, and mechanical refusal at lapse. The tenure numbers a platform sets (funding, duration, how many per principal) belong to the platform's binding; AgentMesh's is EXT-13. Section 8.3's deployment record gains the environment member: test, staging, or production, a statement of where the deploy went, never of quality, with no stage label on the agent itself.

0.3.0-draft (2026-09-01, second pass): the sources are cut down. AgentMesh SPEC.md, EXT-6, EXT-7, EXT-8, EXT-10, EXT-12, and the roles registry's entryway each now carry governing notes pointing at their chapters here and keep only their bindings; Appendix A's interim both-places rule is retired, and this document governs the agent's behavior. The reference implementations' code comments were repointed from the retired standalone specs to Chapters 6 and 9.

0.3.0-draft (2026-09-01, later the same day): Section 10 gains the attribute-versus-interface ownership rule: an attribute never defines an exchange, behaviorally checked attributes name their backing test (Askable the entryway, Candid the interview), and roles bundle interfaces while profiles bundle attributes, never each other's parts.

0.3.0-draft (2026-09-01): two standards fold in and retire as standalones. The Agent Descriptor specification 0.2.0-draft becomes Sections 6.1 through 6.8, absorbed whole: primary-and-others-bind, the document and its members, kinds, the four rules, versioning and the digest over exact served bytes, the descriptor-statement-v1 signature, serving and discovery, and projections. The AgentDoc specification 0.8.0-draft becomes Section 9, absorbed whole: assembled never authored, the source kinds including packages, declared roles, the Descriptor, and evaluation records, the sections with asked, sells, and access in full, the flattering-value rule, subject control, the human rendering, and the assembly signature. The published pages at agentdoc.net remain as renderings of these chapters, and agentdoc.net is this document's home. Former Sections 9 through 12 renumber to 10 through 13.

0.2.0-draft (2026-09-01): full rewrite. The 0.1.0 draft was a charter that named its sections and pointed elsewhere; this draft relocates the normative text itself: the describe obligation, the five questions, the entryway, the surface, the inbound protections, the task and budget behavior, the declaration set, the six capabilities, and the three record formats, each carried whole from its source with transport terms neutralized and every move mapped in Appendix A. The entryway's promotion from optional interface to floor remains the one substantive new obligation; Section 8's by-equality rule and the deployment record's descriptor digest are stated as normalizations the producers will be updated to meet.

0.1.0-draft (2026-09-01): first draft, superseded the same day.