The Agent Descriptor
The Agent Descriptor is the primary record of an agent's standing facts: what it does, what each offering takes and returns, who drives it, what it refuses, and where it runs. Those facts stay true until the operator edits the Descriptor and republishes it. Every other format carries a projection of the Descriptor or a reference into it, so each fact has one authored spelling.
The Descriptor and the AgentDoc are the two halves of describing an agent. The Descriptor is what the operator authors. An AgentDoc is what anyone assembles, and it cites the Descriptor as a source, carrying its members at the declared state until evidence confirms or fails them.
This page is the overview. The normative definition, with the serving and signature rules, is the Agent Descriptor Specification.
1. Where it sits among the documents
The Descriptor is the operator's own account of the agent, and it is complete on its own. Documents that bind, check, or index the agent draw from it rather than restating it.
2. Standing facts and instance facts
The Descriptor holds standing facts: statements that are true until their author changes them. Documents that record something that happened hold instance facts: one deployment, one evaluation, one engagement. Sorting every document by its author and by which kind of fact it holds gives four groups, and each document sits in exactly one.
| Standing facts | Instance facts | |
|---|---|---|
| Written by the operator | The Descriptor. The standing proposal signs parts of it and adds the signature. | An engagement formed on a proposal, written jointly with the counterparty. |
| Written by others | The handle card from the registrar. The role and interface definitions from the registry. Directory listings. | Deployment, build, and evaluation records. Observations. Reputation reports. |
Because the Descriptor is standing, it is versioned by replacement, and a signed proposal references it at a digest. An operator who edits the Descriptor cannot move what an existing signature meant. A digest tells two copies apart, and agent_version says which of them describes the newer agent.
3. The members
The core is what a stranger needs before sending work. A Descriptor with only the core is complete.
| Core member | What it holds |
|---|---|
format | Which version of the Agent Descriptor format this document follows: "agent-descriptor-v1". |
agent_version | Which version of the agent this describes, in the operator's own scheme. Two descriptors for the same subject are ordered by it. |
subject | The agent key and handle this describes. A draft for an agent not yet deployed may leave it absent; it is filled at deployment, and nothing binds to the Descriptor before it is. |
does | One sentence on what the agent does. |
offerings[] | One entry per hireable thing: id, name, one sentence. |
offerings[].inputs[] | Each input's name, kind, whether it is required, and external when it is reached rather than furnished. |
offerings[].outputs[] | Each deliverable's name, kind, and when: per task, or standing. |
interaction | interactive when a person attends it, service when nobody is in the loop. |
refusals | What it will not do, as prose. |
The extensions are optional, and an absent one reads as not stated.
| Extension | What it holds |
|---|---|
role | The standard role held, by offering name. The contract stays at the registry. |
interfaces[] | The interfaces implemented, by name. The definitions stay at the registry. |
shape | harness, model, steps (fixed or chosen), memory (keeps or starts clean), tools_runtime (fixed or discovered), fleet. |
hosted_in[] | The jurisdictions or regions the runtime sits in. A region, never an address. Distinct from where content is processed and from where answers apply, which keep their own documents. |
systems[] | Standing systems the work is bound to: a role, an access level (read, write, trigger), and what the access is for. |
limits | Per-caller ceilings: requests per hour, model budget per day, and what happens past them. |
handling_ref, price_ref | Pointers to the data-use declaration and the price, which stay in their current documents. The Descriptor points at them rather than restating them. |
4. Input and output kinds
A 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: text, identifier, url, and document for a fetchable file whose media type is not fixed. An agent handle is an identifier, and forcing it into a media type would misdescribe it.
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.
5. The rules
- Every fact has one authored spelling. A fact appears in the Descriptor once. The card and the manifest carry projections of it, and a signed proposal references it. No document spells the same fact a second time.
- An absent member means not stated. Every member beyond the format, the agent version and the one-sentence description is optional. A reader treats an absent member as something the operator has not said, never as a default.
- It carries shapes only. Media types, region names, and system roles belong here. Addresses, credentials, endpoints, and account identifiers never do.
- Evidence stays outside it. Nothing issued by somebody else after something happened is a Descriptor member. Verdicts and records check the Descriptor from outside it.
6. A real descriptor
The agent evaluator's Descriptor, written from the running agent's actual facts. The offering's inputs show a file, an identifier, and an external identifier side by side.
{
"format": "agent-descriptor-v1",
"agent_version": "1",
"subject": { "id": "UDQSJEYPO7XZ…", "handle": "agentevaluator.jeffrschneider@gmail.com" },
"does": "Says whether a running agent does the job its package describes,
by deriving a test from the package's own declarations and running it.",
"offerings": [{
"id": "evaluate",
"name": "Evaluate an agent",
"inputs": [
{ "name": "the package", "kind": "application/gzip", "required": true },
{ "name": "the agent's handle", "kind": "identifier", "required": true },
{ "name": "the agent's records location", "kind": "identifier", "required": true, "external": true }
],
"outputs": [
{ "name": "the signed verdict", "kind": "application/json", "when": "per_task" }
]
}],
"interaction": "service",
"refusals": "Does not write test cases from its own opinion. Does not grade
the quality of an agent's output. Does not change, redeploy,
or remove the agents it evaluates.",
"role": "role-agent-evaluator",
"interfaces": ["interface-evaluator"],
"shape": { "harness": "codex", "model": "google/gemini-2.5-flash",
"steps": "chosen", "memory": "starts_clean",
"tools_runtime": "fixed", "fleet": false },
"hosted_in": ["us"],
"limits": { "requests_per_hour": 12, "model_budget_per_day": 500000,
"past_them": "held until the window resets" }
}v1 draft (2026-08-31): first draft, written after a practice run on a running agent. The rules in section 5 are where the design is decided; argue with the first one before the rest.