Files
orchestration_engine/docs/adr/0004-the-orchestration-engine-keeps-what-agents-deliver.md
Jonathan Boniface 6d32bc696d feat: keep what agents deliver and serve it at signed links (ADR-0004)
The Orchestration engine keeps every completed agent Execution it relays,
by tenant, Customer case and Execution, and serves its record and files at
signed, expiring links. A KAB workflow step, which takes one output per
step, is given one JSON document of links (`deliver: links`); other callers
still get each file, and what they are given is kept either way.

- store.py, links.py, delivery.py, serving.py; the relay keeps and links
- the card declares `deliver`, `sources` and an output schema
- image: STORE_DIR on a /data volume; PUBLIC_URL and LINK_SECRET settings
- option 1's tests replaced by tests of the links document

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 20:05:47 +01:00

3.6 KiB

status
status
accepted

The Orchestration engine keeps what agents deliver

An agent on the Execution engine delivers its work as named files: a guide, the data files behind it, infrastructure code. The KAB platform takes one output per workflow step and keeps it as one artifact; a set of named files reaches it as one unnamed string. Nothing delivered had an address of its own, so a guide could not be shared or cited, and a later request could not build on earlier work without the caller carrying its files.

We decide that the Orchestration engine keeps every file an agent delivers through it, and serves each at a stable address.

  • What is kept: the files of every agent's Execution that completes, as the agent delivered them, with a record: the work, the status the agent ended with, the request, when, the Customer case, and the tenant and project a platform step names.
  • Where: a store of its own, by tenant, Customer case and Execution. Files are copied in, not referred to in an agent's container, so they outlive any agent's deployment.
  • Never changed. An Execution's files are written once. A Change request is a new Execution. Only latest moves: the newest completed Execution of a kind of work in a Customer case.
  • Addresses: /tenants/{tenant}/cases/{case} lists a Customer case; …/executions/{id} is one Execution's record with links to its files; …/executions/{id}/files/{path} is a file with its media type; …/latest/{work} is the record of the newest completed Execution of that work.
  • Read only by signed link. Every address carries an expiring signature the Orchestration engine made, because the files name customers, people and suppliers. The base of every link is a setting, as the address a browser uses is not the one inside the platform's network.
  • A caller that takes one output per step is given links. A KAB workflow step, or any caller that asks (deliver: links), is given one JSON document of links to what was kept. A caller that asks for files is given them one by one, as before; they are kept either way.

This keeps ADR-0003's rule that the Orchestration engine produces nothing: it keeps what agents produced. It replaces ADR-0003's consequence that nothing outlives a restart for delivered work; tasks in flight are still held in memory.

Accepted by the owner on 2026-10-21, as option 3 of three ways to make agents' outputs available in the platform.

Considered Options

  • One JSON document with every file's content (option 1): rejected. Nothing has an address, a large architecture can pass the platform's inline limit, and earlier work is reusable only by wiring steps on a canvas.
  • The platform keeps each named artifact (option 2): not rejected, and not ours to make: a change to how the platform's worker treats every agent. Kept as the platform team's to consider; a shared object store later lets each kept file become a platform artifact without moving it.
  • Links into each agent's own deliverables folder: rejected. Those folders are private to a container and go with it.

Consequences

  • The Orchestration engine has a volume, a public base URL and a signing secret. Without a secret set, one is made at start-up and links stop working on a restart.
  • Links expire (LINK_TTL_SECONDS, 30 days by default; 0 for never). A record fetched with a valid link carries fresh links to its files.
  • A request may name earlier work by reference rather than carry its files (sources_from): the next step, with the sequence moved onto it.
  • Object storage, the platform's own sign-in and retention follow, in that order.