Durable work and settlement

Most agents answer a request and are done. Some serve a piece of work that has its own identity: an invoice to reconcile, a case to close. Durable work gives that unit a record the platform manages, so a later session can continue it and its outcome is settled once.

Availability: Durable work and settlement are enabled per tenant. A settlement-mode version fails session activation where the boundary is unavailable rather than running without it. See What is available where.

At a glance

• settlement_mode in the manifest is standard, work, or settlement, in that order of strength. Missing means standard.
• In work and settlement modes, the first run in a new session declares the work it serves: work.subject to open new work, or work.work_id to continue existing work.
• The admitted run returns settlement_work_id. Store it if another session may continue the work.
• Work ends in one of two ways decided by the platform, never by a person editing its state.

Declare the mode

agent.yaml

settlement_mode: work

Mode	Behaviour
standard	The existing behaviour: runs are units of execution and nothing more.
work	The agent produces durable work records. Runs bind to work.
settlement	As work, and the session must establish the managed worker and proxy boundary or fail activation, so every effect the work dispatches is enforced through policy.

Open or continue work

POST /v1/sessions/{session_id}/runs

{
  "input": { "prompt": "Reconcile invoice INV-1842." },
  "work": {
    "subject": "invoice:INV-1842",
    "contract_ref": "billing/reconciliation",
    "contract_version": "2026-09"
  },
  "idempotency_key": "invoice-1842-attempt-1"
}

Send either subject or work_id, never both. When opening work, contract_ref and contract_version may name a contract and must be sent together; later requests may omit the pair or restate it exactly, but cannot add or change it. The response’s settlement_work_id is the handle another session uses with work.work_id.

A work item has at most one live run at a time; a second run against the same work while one is live returns 409 with work_has_live_run.

What settlement adds

In settlement mode the effects a run dispatches to other systems, not the messages it exchanges, are the things being settled. Each is authorized through the policy facade before it happens and recorded as it happens, and the work’s outcome is decided from those records. Work ends two ways: it settles, or it is abandoned by the platform’s rules. A person does not end it by hand, which is what makes the record trustworthy.

Where to go next

• Sessions and runs: where work sits beside sessions and runs.
• Start a run: the request fields.
• Agent manifest: the mode field.