WeaveFlow

A Go-native graph runtime for building, running, inspecting, and recovering LLM agent workflows.

Website · Documentation · 中文文档 · Playground · Source

WeaveFlow makes workflow structure explicit: topology, state access, control flow, and runtime policies remain serializable and reviewable instead of disappearing inside an orchestration loop. Runs preserve Steps, Events, Checkpoints, and Artifacts so execution can be understood after it finishes.

Quick Start

The Codespaces button above opens a credential-free demo with a ready-to-run Graph Session. Select codespaces_demo, click Run, and inspect its State, Steps, Events, and Checkpoints. Keep forwarded port 8080 private unless WEAVEFLOW_MANAGEMENT_TOKEN is configured.

To run the same demo locally, install Go 1.26.6+ and start the bundled server and Workbench:

go run ./cmd/server -addr 127.0.0.1:8080 -data .local/server -graph examples/codespaces_demo/graph.json

Open http://127.0.0.1:8080. Bun is only required when developing the WebUI.

For model-free command-line examples:

go run ./examples/graph/conditional_routing.go
go run ./examples/graph/dynamic_map_reduce.go
go run ./examples/graph/human_approval.go

See examples/README.md for failure handling, fan-out/fan-in, planning, supervisor routing, agent handoff, and model-driven examples.

Key Features

• Declarative Graphs — Store, review, and reuse workflows as serializable definitions with registry-backed types and build-time validation.
• Explicit State Contracts — Declare reads and writes through State Ports, schemas, bindings, capabilities, and reducers; detect missing producers and unsafe parallel writes before execution.
• Powerful Control Flow — Combine conditions, bounded parallel waves, fan-out/fan-in, and explicit Goto, Send, Suspend, and Return commands without hiding orchestration in an opaque loop.
• Checkpointed Recovery — Persist meaningful execution boundaries for pause, resume, human input, failure routing, and recovery after interruption.
• First-Class Observability — Inspect Runs, Steps, Events, State, Checkpoints, and Artifacts during execution or after a Run finishes.
• Local-First Workbench — Edit Graphs, create immutable Sessions, control Runs, and configure extensible model and tool registries from one debugging environment.

These capabilities support non-trivial local workflows. WeaveFlow is still evolving and does not yet claim to be a complete multi-tenant control plane or a cross-worker durable execution service.

Core Model

Graph Definition  ->  Graph Session  ->  Run
      |                    |              |-- Steps
      |                    |              |-- Events
      |                    |              |-- Checkpoints
      |                    |              `-- Artifacts
      `-- Nodes, edges, State bindings, and runtime policies

• Graph Definition is the serializable workflow: nodes, edges, conditions, State Modules, bindings, and policies.
• Graph Session is an immutable, build-validated version of a Graph used to start Runs.
• Run is one execution with persisted lifecycle state and diagnostic records.
• Checkpoint captures state and control position for inspection, recovery, or resume.

Graph Definitions

Graph Definitions are versioned JSON documents that can be stored, reviewed, loaded by the Go runtime, and edited in the Workbench. Their most important rule is:

State paths belong in component state bindings, not in component config.

Node and Condition State Ports declare required reads, writes, schemas, capabilities, and merge behavior. Graph building rejects missing bindings, reserved paths, incompatible schemas, missing producers, and unsafe parallel writes before a Run starts.

Browse examples/dsl/, examples/state_operations/, and examples/README.md for complete definitions and runnable scenarios.

Debug Server and Workbench

cmd/server exposes the local debugging API and serves the Workbench. Together they support Graph upload, immutable Session creation, Run control, live Events, State inspection, Checkpoints, Artifacts, and Trigger-backed execution.

Useful server options:

• -graph <path> preloads a Graph Definition.
• -prefix /debug mounts API routes below a path prefix.
• -secret-dir <path> configures file-backed secret references.
• -cors-origins <origins> allows a separately hosted WebUI.
• A non-loopback -addr requires WEAVEFLOW_MANAGEMENT_TOKEN.

For WebUI development and deployment details, see internal/web/README.md. Keep generated runtime data under .local/, and never store credentials in Graph Definitions, Events, Artifacts, logs, or API responses.

Agent Skills

Repository-local skills under .agents/skills/ keep live API work separate from source changes:

• weaveflow-graph-create authors, validates, installs, and configures Graph Definitions and Sessions through the public Debug Server API.
• weaveflow-graph-debug reconstructs Run context and diagnoses persisted evidence through the public API; investigation is read-only by default.
• weaveflow-graph-code implements and validates repository source or documentation changes without mutating live runtime data.

The usual handoff is create -> debug -> code: create the Session, diagnose the Run, then change the repository only when the remedy requires it.

More

• Getting started
• Container and deployment scripts
• Contributing
• Capability gap analysis
• License

WeaveFlow is released under the MIT License.