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:

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.

🔗 Links

• Documentation
• Crates.io
• Repository
• Issues