Versions & Execution

About

This page covers how Agent Playground handles versioning and execution. Versions let you iterate safely on your workflow. Execution is how the platform runs your graph and tracks results per node.

---

Version Lifecycle

Every graph manages its workflow through versions: immutable snapshots of the graph’s structure (nodes, ports, edges, and configuration) at a point in time.

Draft vs Non-Draft

There are two states a version can be in:

State	Editable	Executable
Draft	Yes	No
Non-draft	No	Yes

How Versions Work

1. Draft - When you create or modify a graph, you work in a draft. Drafts are auto-saved as you make changes. This is your workspace for experimenting and iterating freely.

2. Save - When a draft is ready, you save it. This finalizes the draft into a non-draft version, making it the version that runs when you execute the graph. The previous version is kept in your version history.

You can always view older versions in the Changelog tab and create a new draft from any of them to pick up where you left off.

Version Workflow

Create Graph → Draft v1
                 ↓ (save)
              v1 → Edit → Draft v2
                            ↓ (save)
              v1    v2 → Edit → Draft v3
                                  ↓ (save)
              v1    v2    v3

---

Execution Model

When you run a graph, the platform creates a graph execution: a record of that specific run with its own ID, status, timing, and results.

Execution States

State	Meaning
Pending	Execution created, waiting to start
Running	Nodes are actively executing
Success	All nodes completed successfully
Failed	One or more nodes encountered an error
Cancelled	Execution was stopped by the user

Node Execution

Within a graph execution, each node gets its own node execution record tracking:

• Start and end timestamps
• Status (pending, running, success, failed, skipped)
• Input data received from upstream nodes
• Output data produced
• Error details (if failed)

Nodes that cannot execute because an upstream node failed are marked as skipped.

---

Data Routing

The execution engine processes nodes in topological order: it determines which nodes can run first (those with no dependencies) and works forward through the graph.

How Data Flows

1. Graph inputs are injected into the exposed input ports (ports with no incoming edges)
2. Start nodes (nodes with all inputs satisfied) execute first
3. When a node completes, its output data is routed along edges to downstream nodes’ input ports
4. A downstream node becomes ready when all its required input ports have data
5. Ready nodes execute, and the process repeats until all nodes are done
6. Graph outputs are collected from exposed output ports (ports with no outgoing edges)

Each piece of data flowing through a port is validated against the port’s JSON Schema. Validation errors are recorded but do not block execution: you can inspect them after the run to identify data contract issues.

---

Next Steps

• Create a Graph: Create your first workflow and manage versions
• Build a Workflow: Add nodes, configure them, and connect them
• Run & Monitor: Execute workflows and inspect results