Open in ClaudeOpen in ChatGPTOpen in Cursor
On this page

Executions and versioning

Two questions come up the moment something runs. What happened? — that is an execution. How do I change this safely, and get back if I am wrong? — that is versioning. They are on one page because in practice you ask them in that order, but they are separate mechanisms.

Executions

An execution is one run of an agent or a process flow, with its inputs, outputs and trace. It is the record of what actually happened, which is a different question from what the definition says should happen; both are worth being able to read, and only the execution answers the first.

Every run is asynchronous. Starting one — with run-agent or run-process-flow — returns an execution_id and finishes. Nothing about the run's outcome comes back from that call.

Retrieving one

get-execution takes one argument, the execution_id, and returns the record. Two fields on it carry the result, and they are not interchangeable.

  • conclusion is a human-readable Markdown summary of the run. It is always prose. Never parse it as structured data: the wording is for a reader, not for a program, and code that treats it as anything else breaks on the first run that phrases itself differently.
  • last_agent_output is the terminal agent's raw structured output — whatever that final step actually produced, under its own input and output fields. This is the field to read when a program needs the answer.

There is a neat consequence of the second field. If a run's terminal output is itself shaped like a process-flow manifest, it can be handed straight to create-process-flow as its manifest argument — one run's output becoming the next process flow's definition, with no translation step in between.

A run is scoped like everything else: an execution belongs to exactly one project, and which project is filled in from your credential rather than from your arguments.

Versioning

A version is a saved, immutable revision of an agent or a process flow. To promote a version is to make it the one that runs. To roll back is to make an earlier version the one that runs again.

Editing records nothing on its own. A process flow you have edited is simply the current process flow; there is no history entry for that edit, and nothing to return to. History exists because something was promoted.

Two separate tracks

Agents and process flows are versioned along separate tracks. This is the part that catches people, so it is worth being explicit about what each track captures.

A process-flow version is a snapshot of the whole process flow taken at the moment it was promoted: every agent in it, each agent's configuration, and the wiring between them. It is the only thing that captures structural change — an agent added, removed, or rewired — because no per-agent history can see the arrangement it sits in.

An agent version is a snapshot of one agent's own configuration, recorded with who promoted it, under what role, which version it replaced, and how its tests scored.

They move independently. Making a different version of an agent live changes what every process flow naming that agent does, without the process flow's own version changing. That is exactly why the two histories are kept apart rather than merged: merging them would make one of the two changes invisible.

Which version is live

Every version carries a status, and there are three: promoted, superseded and rolled_back. The live one is whichever is promoted.

The trap is assuming that is the highest number. It is not necessarily, because a rollback makes an earlier version live again and nothing is renumbered. Roll back to v1 while v2 was live and v2 stays in the history marked rolled_back; v1 is live again; and the next promote is v3, not v2. For a process flow the answer is given to you directly — the listing names the live version, and that field is authoritative. Read it rather than inferring it.

The tools, and how they differ between the two tracks

For a process flow:

  • promote-flow snapshots it exactly as it stands and records that snapshot as the next version, which becomes live. The previous live version becomes superseded, and numbers only ever go up.
  • flow-versions lists the versions newest first and says which is live. Snapshots are large, so it leaves them out unless you ask for them.
  • rollback-flow-version makes an earlier version live again.

For an agent:

  • agent-versions reads the promoted history, newest first, and can also return a field-level difference between two versions rather than the list.
  • rollback-agent-version makes an earlier version live again.

Note the asymmetry rather than assuming it away: the tool surface exposes a promote for a process flow, and for an agent exposes history and rollback. Promotion of an agent version is a step taken on a tested version, not a field you set on the agent definition.

Rolling back either one requires an admin role.

Not every deployment carries all of these. get-execution and the five versioning tools — agent-versions, rollback-agent-version, flow-versions, promote-flow and rollback-flow-version — are turned on separately, so a deployment can have one group and not the other. GET /v1/connection-info lists what yours has.

Where to go next