Agents and runs

An agent is what carries out the operations in a deployed definition. It reads what came in, decides which operation applies, and performs it — subject to whatever rule governs that operation. An agent does not choose which operations exist; it works within the set the definition gives it.

Coordinators, delegates, and service agents

Every run starts on a coordinator. A coordinator is the Project Agent selected by the active Environment Deployment, and it is the Agent an incoming request addresses.

A coordinator can hand part of its work to a delegate. A delegate is a separate agent, defined and versioned on its own, that the coordinator names explicitly as something it can call on. When a coordinator does this mid-run, the run pauses while the delegate does its part and resumes once the delegate's result comes back — this wait is a distinct, visible state in the run's lifecycle, not something folded into ordinary execution. A delegate does not run on its own; it exists to be called by the coordinator that declares it, and a request cannot address a delegate directly.

A service Agent is different again: it is published at organization scope rather than attached to a Project Environment. It answers requests outside a process a Definition describes, and its reach is governed by organization policy separately from Project Agent revisions.

Agents are versioned

An Agent's content — the instructions and configuration it acts on — is published as an immutable revision. Publishing a change creates a new revision; the ones before it are not altered or discarded. A Release records the exact revision selected for an Environment, and the active Deployment keeps that pin for every run it starts. A run therefore never changes revision because a newer Agent revision was published. A coordinator's revision also pins the delegate revisions it is allowed to call.

Runs

A run is one unit of work: an Agent handling one invoice, one support ticket, or one incoming request, from the point it arrives to the point it finishes, waits, or is refused. A busy Environment has many runs happening at once, each independent of the others.

Runs are checkpointed as they go, and the checkpoint is what lets a run resume rather than start over. A run moves through a sequence of states: it is queued, then a runner is acquired for it, then it starts up, then it actually runs. From running it can pause — waiting on an interactive tool result, or waiting on a delegate it called out to — and pick back up from there. If someone cancels it, it moves through a winding-down state before stopping. Where it ends up is one of: completed, failed, canceled, or expired.

A run that is paused, whether for a tool result, for a delegate, or for a person to approve a step, is not stalled or lost. It sits at its last checkpoint until whatever it is waiting on arrives, then continues from exactly there.

What a run leaves behind

Every run leaves a record: what was requested, what the agent checked, what it committed, and why. This is true regardless of how the run ends. A run that completed cleanly, one that stopped to wait for approval, and one that was refused by a rule all leave a record with the same shape — only the ending differs.

The record is append-only. Nothing about a past run can be edited or removed after the fact; new information about a run is added as further entries, never by rewriting what is already there. This is what makes the record trustworthy as an account of what actually happened, including for a run that is still in progress.

To read through a run's record, see Reading the record. For runs currently waiting on a decision, see Approvals.