Graphs and versions

A graph is a versioned definition of an agent workflow: nodes connected by edges. Two authoring surfaces produce the same definition — the visual canvas and the graph DSL — and the definition is the single source of truth for both.

Canvas ↔ code parity#

• The canvas renders the DSL; the DSL renders the canvas. There is no drift between what the diagram shows and what runs.
• Platform engineers who prefer text work in the DSL; compliance officers who need to read the workflow read the diagram or the diff — both show what production actually does.
• The DSL is git-friendly YAML. Graphs live in version control like any other code.

Immutable versions#

Every activation of a graph refers to an immutable version. Once published, a version cannot be edited:

• Editing a published graph produces a new draft, not a mutation.
• Publishing a draft creates the next immutable version.
• The version pin — the exact version a workspace or run uses — is recorded in the ledger with every run.

graph: refund-approval
version: v1.3
nodes:
  trigger: inbound_email
  triage: agent.refund_bot
  gate:   gate.policy baseline-security
  pay:    tool.payments.issue_refund
edges:
  trigger -> triage -> gate -> pay

The promotion path#

A version reaches production only through the eval gate:

1. Draft → run the regression evaluation suite
2. Suite passes → version is publishable
3. Publish → immutable version created, recorded in the ledger
4. Activate on a workspace (or let a run pin it)

Every activation is a ledger event. If an examiner asks which version ran on which date, the ledger answers.

Each node in a graph is documented in Nodes; the underlying YAML schema is the DSL reference.