Weavegraph

Graph-driven, concurrent agent workflow framework for Rust.

Pre-1.0 Status
Weavegraph core APIs are stable and production-ready. However, as we approach 1.0, minor versions may introduce targeted refinements to APIs or behaviors. See MIGRATION.md for upgrade guidance between releases.
Your feedback shapes the future—please report issues and suggest improvements as you use the framework.

Weavegraph lets you build robust, concurrent, stateful workflows using a graph-based execution model. Ideal for AI agents, data pipelines, and any application needing versioned state and rich diagnostics.

Features

Concurrent graph execution with dependency resolution
Type-safe, role-based message system
Versioned state with snapshot isolation
Structured error handling and diagnostics
Built-in event streaming and observability
Flexible persistence: SQLite or in-memory
Conditional routing and dynamic edges
Ergonomic APIs and comprehensive examples

Install

Add to your Cargo.toml:

[dependencies]
weavegraph = "0.3"

Note: Examples and instructions in this README are current as of 0.3.x. For upgrading from 0.2.x, see MIGRATION.md.

Dependency Compatibility

Weavegraph targets Rust 1.90+ (MSRV). The following table shows compatibility with key dependencies:

Rust Version	Tokio	Serde	SQLx
1.90 (MSRV)	1.40+	1.0+	0.8+
Stable	1.40+	1.0+	0.8+
Nightly	1.40+	1.0+	0.8+

Optional dependencies: SQLx 0.8 (postgres/sqlite features), miette 7.x (diagnostics feature), rig-core 0.30 (rig feature).

See Cargo.toml for complete dependency versions and feature configuration.

Documentation

Quickstart - Fast path to building and running workflows
Operations Guide - Event streaming, persistence, testing, and production
Architecture - Core architecture and custom reducers
Documentation Index - Complete topic reference with anchor links
Examples - Runnable code for all patterns

Minimal Example

use weavegraph::{
        graphs::GraphBuilder,
        message::Message,
        node::{Node, NodeContext, NodePartial},
        state::VersionedState,
};
use async_trait::async_trait;

struct HelloNode;

#[async_trait]
impl Node for HelloNode {
        async fn run(
                &self,
                _snapshot: weavegraph::state::StateSnapshot,
                _ctx: NodeContext,
        ) -> Result<NodePartial, weavegraph::node::NodeError> {
                Ok(NodePartial::new().with_messages(vec![Message::assistant("Hello, world!")]))
        }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
        use weavegraph::types::NodeKind;
        let app = GraphBuilder::new()
                .add_node(NodeKind::Custom("hello".into()), HelloNode)
                .add_edge(NodeKind::Start, NodeKind::Custom("hello".into()))
                .add_edge(NodeKind::Custom("hello".into()), NodeKind::End)
                .compile()?;
        let state = VersionedState::new_with_user_message("Hi!");
        let result = app.invoke(state).await?;
        for message in result.messages.snapshot() {
                println!("{}: {}", message.role, message.content);
        }
        Ok(())
}

NOTE: NodeKind::Start and NodeKind::End are virtual structural endpoints.
You never register them with add_node; attempts to do so are ignored with a warning.

🧪 Testing

For testing and ephemeral workflows use the InMemory checkpointer:

// After compiling the graph into an `App`:
let runner = AppRunner::builder()
        .app(app)
        .checkpointer(CheckpointerType::InMemory)
        .build()
        .await;

Run the comprehensive test suite:

# All tests with output
cargo test --all -- --nocapture

# Specific test categories
cargo test schedulers:: -- --nocapture
cargo test channels:: -- --nocapture
cargo test integration:: -- --nocapture

Property-based testing with proptest ensures correctness across edge cases.

CI Parity

To minimize local/CI drift, this repository pins Rust with rust-toolchain.toml to 1.90.0 and runs required CI checks on that version.

Before opening a PR, run:

./scripts/ci-quick.sh

Before merging or cutting a release, run full local parity checks:

./scripts/ci-local.sh

ci-local.sh intentionally fails if required tools are missing (cargo-semver-checks, cargo-deny) so a local pass is a meaningful signal for CI.

Resources

Migration Guide - Upgrade paths between releases (0.2.x → 0.3.x and beyond)
Architecture Guide - Deep dive into core design and internals
Examples Directory - Runnable patterns: graph execution, scheduling, streaming, persistence, and more

Related Crates

wg-ragsmith - Semantic chunking and RAG utilities for Weavegraph nodes

Contributing

We welcome contributions! See CONTRIBUTING.md.

License

MIT — see LICENSE.

weavegraph 0.3.0