Pools and workers

Work does not staff itself. A stage is staffed by a pool, which leases tasks to a worker to be worked. This page explains the pieces the Fleet reference and the staffing guide assume.

Worker

A worker is a named agent, runner, or classifier that does work. An agent is driven by a model with a prompt and, optionally, skills; a runner executes a fixed command; a classifier is driven by neither a prompt nor a command — it asks a question-answering provider a fixed list of questions about one task and turns the answers into checks and properties on that task. A worker is just the identity and kind — its actual configuration lives in its versions.

Worker version

A worker version is a frozen, runnable configuration of a worker: for an agent, the image it runs in, its prompt and model, the skills it carries, and its environment; for a runner, the command it runs; for a classifier, two documents — an input document, naming the task attachments and questions it is handed, and an output document, naming the checks and properties its answers set on the task. You build a version as a draft and then publish it, which freezes it — a published version cannot change, so a change means a new version. Freezing a version means the work a pool runs is exactly what you published, not something edited underneath it. The full set of fields each kind carries is in the Fleet reference.

An agent version names the model it runs in three parts: the LLM vendor that sells the model, the model itself, chosen from the models defined for that vendor, and optionally the effort — how hard the model reasons, one of the efforts that model offers. A version cannot be published without a vendor and a model defined for it. See Choosing a vendor, model and effort.

Agent skill

A skill is a unit of instruction an agent can carry — a reusable piece of guidance, versioned the same way a worker version is. An agent version pins the skill versions it uses, so what an agent knows is as fixed as the version itself.

Pool

A pool pins exactly one worker version and staffs a stage with it. When a task enters a stage that an assignment rule routes to the pool, the pool leases the task to a worker running that version. The lease is that unit of running work: it is what you observe and can cancel while it runs (see Leases).

A pool has a size — how many workers it runs at once — and can be paused, which stops it taking new leases. What a lease may reach beyond its own task — a parent, dependencies, a whole workflow — is set by the pool's lease scopes.

A pool has no LLM vendor of its own: through the version it pins, an agent pool uses that version's vendor. Its workers are served a token from your space's account with that vendor, or, if the space has none, from one registered for the whole instance. To change vendor, repin the pool to a version that names another. Without a token to serve, an agent pool runs no work: its worker does not start, Cadence holds the task, and the task waits until a person fixes the token and clears the hold. See LLM providers.

The pieces connect in one direction: an assignment rule points a stage at a pool, the pool pins a worker version, and the worker version pins its image and skills. Assemble them in order in Staff a stage with a pool.