The Agent Package
An agent that does not exist yet has to travel somehow: from the person who described it, to whoever builds it, to the host that runs it, to the caller who hires it. The Agent Package is the thing that travels. It is one folder, or its archive, and everything below is about what is in it, what is deliberately not, and who does what to it along the way.
Five words are used here in one sense each, defined in Chapter 12.1: the host is the machine, a harness is the program that thinks when a message arrives, a package is what travels, an agent is what exists after an install, and a bare agent is one that carries no package. The owner instructs a deploy; the installer installs the package; the result is an agent.
An agent has an inside and an outside
The inside is what an agent is made of: its skills, the scripts they run, the servers they reach. There is already a portable format for that, the Agent Plugin, shared by the makers of most coding agents, with Agent Skills underneath it for what a skill folder holds. The plugin standard says, in its own words, that distribution, installation, and permissions stay under each client's control. It packages the inside and stops there.
The outside is what a caller can rely on: what the agent does, what it refuses, what it needs, what it leaves behind. That is the Agent Descriptor, Chapter 6, which was written so a builder could describe an agent that does not exist yet: a draft Descriptor has no subject, and the subject is filled in when the agent gets its identity.
A package is the two halves together. It is an Agent Plugin, unchanged, with two files beside its manifest: the draft Descriptor, and an install file that says what a host must have and do to run it. The manifest points at both by digest and copies nothing. Everything a harness reads as markdown is generated from those two files, never written by hand.
The install file is the half nobody had written down
Every package that calls a paid service, needs a browser, or reads a credential has host-side needs, and until now they lived in whoever deployed it. The install file names them: the runtimes and binaries the host must have, the lockfiles the skills' scripts pin, each system the Descriptor names by role together with what kind of thing it is bound to, the name of the credential a service needs and the variable the scripts read it from, whether a service spends money and in what unit, which spending systems need a ceiling, and the working directories. Names, never values. A package that carries a credential value, an address, or an account identifier does not conform, and a depot refuses to publish it.
Who does what to a package
| Who | Does | Leaves behind |
|---|---|---|
| A developer, in whatever coding agent they use | Builds the working parts, then packs them, supplying the two things a pack cannot infer: what the agent refuses and what it must record | A package, and a build record signed with their own key |
| The agent builder role | The same, starting from a description rather than from working code | A package marked draft, and a build record |
| The depot | Accepts a publish only with a build record whose digest matches the bytes, keeps every version immutable, scans for hidden characters, and serves packages by digest | The versions, and their records |
| The deployment manager role | Installs on instruction: checks the host, installs from lockfiles, binds systems, places credentials by name, sets ceilings, gives the agent its identity, and checks it with the grade stated | The bound Descriptor the agent serves, a deployment record, and a ledger of every file placed |
| The agent evaluator role | Derives its test from the package's own declarations and runs it against the running agent | An evaluation record, case by case |
| Whoever offers the agent | Attaches a price and handling terms at listing, which a package never carries | The listing |
The three records join by digest, and a verifier can follow them: the bytes hash to what the deployment record names, the build record names the same digest and verifies against the builder's key, the bound Descriptor differs from the draft in the package only by its subject and signature, and the evaluation record names that Descriptor. That chain is the reason to have a package at all. It says what is running and who vouched for each step. It does not say the work is good, which no document about an agent can.
How it fits with the rest
- The Descriptor is inside the package as a draft and is the only authored spelling of every caller-facing fact. The bound Descriptor a running agent serves is that draft with a subject added and nothing else changed.
- The AgentDoc is assembled after the fact, from the bound Descriptor and the three records, and it cites the package by digest like any other source.
- The roles are the parties: the builder makes a package, the deployment manager installs it, the evaluator checks it. The package chapter owns the package's shape; each role owns its own judgment and its own signed record.
- Bare agents are what the words have to cover at the other end: an agent that carries no package and answers as its harness alone. It has a subject and serves a Descriptor like any other agent; it simply has nothing behind it that a depot could publish, so the chapter has nothing to say about it beyond naming it.
- The catalog lists what exists to be adopted: processes, roles, live agents, and abstract agents. An abstract agent's package lives in the depot behind its listing, with versions. The catalog is where people look; the depot is where tools publish and fetch.
- The protocol is untouched. Nothing about a package changes any wire, any SDK, or the network specification; it sits in the extensions tier above them.
- Agent Package Manager, the open tool that installs plugins for coding agents, can lay out the skills in a package for the harnesses it knows and keep its per-file ledger, and a depot can speak its registry API so the skills in any package reach any client that installs plugins. What that tool does not do, a package's identity, its Descriptor, its credentials by name, its ceilings, and its records, is exactly what this chapter adds.
What a package is not
It is not a listing: it carries no price and no terms, because the same package may be offered by different parties on different terms. It is not an identity: the subject, the handle, who may call the agent, and whether a person attends it are the owner's decisions at install. It is not evidence: the build, deployment, and evaluation records are about a package and are never inside one. And it is not a runtime: it declares what a host must have and never carries the harness that runs it.
The normative text is Chapter 12: the layout, the two files, the eight rules, publish and install and update and remove, provenance, and what a checker verifies.