Versions & Execution

Versions and executions: two models

A version is a numbered snapshot of an agent’s graph. A version starts as a draft, the state you can edit; saving fixes it into an immutable snapshot. An execution is the record of one run of a version.

A run always executes one specific saved version, so the three stay linked: what you can currently change, what you saved, and what happened when it ran.

flowchart TD
accTitle: How support-triage's draft, versions, and runs relate
accDescr: support-triage has one draft plus a history of saved versions, and exactly one of those versions is the one that runs. Saving the draft adds Version 4. Running Version 4 creates an execution containing one record per node: classify, draft-reply, and summarize-step, each with its own status. Summarize-step is an Agent Node, so its record holds a nested execution for the agent it points at.
Agent["support-triage"] --> Versions
subgraph Versions["support-triage's versions"]
  History["Version 1, 2, 3 ..."]
  Draft["Draft"]
  Draft -->|"Save Agent"| V4["Version 4 (runs)"]
end
V4 -->|"Run"| ExecBox
subgraph ExecBox["Execution (one run)"]
  Classify["classify: success"]
  DraftReply["draft-reply: success"]
  Summarize["summarize-step: success"]
end
Summarize --> Nested["Nested execution"]

Drafts and versions

Every change you make, adding a node, editing a connection, rewriting an input, lives in a draft. A draft is marked with the Draft badge, and it is the only kind of version you can edit.

Save Agent turns the draft into a version: you write a commit message for it, and it becomes a numbered snapshot carrying that message. Saving validates the graph before that version can run:

• Exposed output names cannot duplicate
• Every node’s required inputs must be present

The save is blocked until both checks pass. Once it succeeds, that new version becomes the one the agent runs, replacing whichever version ran before it.

Older versions do not disappear. They stay available to read and preview, though only the draft can be edited. An agent always keeps at least one version, so there is never a state with nothing to run.

Executions and node records

Running an agent creates an execution: one record of that run as a whole, plus one record per node inside it. Each node record carries its own status, one of pending, running, success, failed, or skipped, along with the inputs it received and the outputs it produced.

A node whose upstream step failed is marked skipped rather than being run at all, so a failure does not silently propagate as if the node had executed. In a run of support-triage, for example, if draft-reply fails, summarize-step is skipped rather than run, since it depends on draft-reply’s output, while classify, which has no dependency on draft-reply, is unaffected.

Independent branches do not wait on each other: up to ten nodes run at the same time by default, so parts of the graph with no dependency between them finish in parallel instead of one after another.

Nesting closes the loop between the two models. summarize-step, for example, is an Agent Node: its record holds the nested run of the agent it points at. You can open a run inside a run and keep going as deep as the graph nests.

Why the version matters

A run doesn’t just execute “the agent”, it pins one specific saved version, and each execution stays tied to the version it ran. So two runs of the same agent differ only by what you changed between the versions they pinned.

Keep exploring