Agent Descriptor Specification

The Agent Descriptor is 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. Every other format carries a projection of the Descriptor or a reference into it, so each fact has one authored spelling.

As of 0.3.0-draft, the Agent Descriptor is no longer a standalone standard: it is Chapter 6 of the Common Agent Specification, which defines the agent the Descriptor describes, and this page renders that chapter in its own numbering. Where this page and that document disagree, that document governs. The assembled view built on top of the Descriptor is AgentDoc, that specification's Chapter 9. It is transport-neutral; nothing here requires a particular network or vendor.

1. Motivation

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.

1.1 Primary, and others bind

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 (§6) rather than restating it. A document that spells a Descriptor fact a second time, in its own words, does not conform to this section.

1.2 What it is not

It is not a card: it carries no endpoint and no authentication, because those are connection facts and the Descriptor holds shapes only (§5). 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.

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.

• Descriptor: one document in the shape §3 defines, describing one agent.
• Subject: the agent a Descriptor describes.
• Operator: whoever runs the subject and authors its Descriptor.
• Draft: a Descriptor whose subject member is absent, describing an agent that does not exist yet.
• Bound: a Descriptor whose subject member is filled. From then on it describes exactly one agent.
• Projection: a copy of Descriptor facts carried in another format, derived from the Descriptor and never edited on its own.
• Reference: a pointer to a Descriptor, or into one of its members, at a digest.
• Consumer: anything that reads a Descriptor: an assembler, an intake check, a counterparty, a directory.

3. The document

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

3.1 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.

3.2 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 (§4), 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 §5.3.1's 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[], §3.4).

3.3 Interaction and refusals

interaction is "interactive" when a person attends the agent and "service" when nobody is in the loop. 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.

3.4 Extensions

Every member beyond the core is optional, and an absent one means not stated (§5).

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

4. 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.

5. 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 (§1.1, §9).
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. 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.

7. 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: signatures is an array of { "tag", "by", "sig" } entries, and the signed bytes are the ASCII tag, one newline, then the JCS (RFC 8785) canonical JSON of the document with signatures removed. 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 (§6) 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.

8. Serving and discovery

8.1 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.

8.2 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 (§8.4), 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 an AgentDoc assembler follows for drifted projections.

8.3 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 an entryway-class exchange: a question a stranger may ask, defined with the entryway interface at the roles registry. A consumer on the same network as the agent then needs no other serving at all.

8.4 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 (§8.2) 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.

8.5 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.

8.6 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.

9. 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 (§8.1) 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 an agent-descriptor source, prefers it over any projection of it, records its digest, and reports rather than merges when a projection has drifted. Its members enter at the declared state. This is AgentDoc §5.2.3.

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.

10. Conformance

A checker verifies a Descriptor mechanically: 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, and never by this document about itself.

v0.2.0-draft (2026-09-01): grant-shaped inputs MAY carry via, naming the grant mechanisms the operator accepts from Agent SoW §5.3.1's vocabulary, and the systems member's projection into the AgentDoc's reaches section is stated. Nothing else changes; the format marker stays agent-descriptor-v1, because a member a reader may ignore is not a new format.

v0.1.0-draft (2026-08-31): first published draft, promoted from the internal working draft after a practice run on a running agent. States the members with their required core, the draft-versus-bound subject rule, the kind vocabulary with value kinds beside media types, the four rules, versioning by replacement with the digest over exact served bytes, the detached-by-convention signature under the family's tag scheme, and serving and discovery: the well-known path and the registration pointer, the registry as store and history, the entryway exchange, hosted serving, and change announcement.