langgraph4rust ๐ฆ
English | ็ฎไฝไธญๆ | Deutsch | ๆฅๆฌ่ช
A powerful Rust implementation of a stateful workflow engine inspired by Python's LangGraph library.
langgraph4rust provides a flexible, type-safe, and async-first framework for building, executing, and managing complex workflow graphs with support for parallel execution and conditional routing.
โจ Features
- ๐๏ธ Declarative Graph Building: Define workflows using an intuitive builder pattern
- โก Parallel Execution: Multiple nodes can execute simultaneously when dependencies allow
- ๐ Conditional Routing: Dynamic path selection based on runtime state conditions
- ๐ก Streaming Execution: Real-time, push-based
StreamEventstream for observing workflow progress - ๐พ State Management: Built-in JSON-based state persistence with full type safety
- ๐ Extensible Architecture: Custom node implementations via traits
- โ Comprehensive Validation: Graph structure validation before execution prevents runtime errors
- ๐ฏ Async-First Design: Built on Tokio for efficient asynchronous operations
๐ฆ Installation
Add this to your Cargo.toml:
[]
= "0.2.0"
๐ Quick Start
Basic Example
use *;
use HashSet;
use Arc;
use async_trait;
// Define a custom node
;
async
Run this example:
๐ฏ Core Concepts
Nodes ๐ท
Nodes are the fundamental building blocks of your workflow. Each node implements the [AgentNode] trait and contains logic to process and modify the shared state.
;
Edges โก๏ธ
Edges define the control flow between nodes:
- Static edges: Always connect to fixed target nodes
- Conditional edges: Dynamically choose targets based on current state
// Static edge
builder.add_edge;
// Conditional edge: routers are *synchronous* closures that inspect the state
// and return the name of the next node. Multiple routers may be supplied;
// their returned targets are unioned into the next step.
builder.add_conditional_edge;
State ๐พ
The state is shared across all nodes and persists throughout execution:
let state = new;
// Set values
state.set.await?;
// Get typed values
let value: String = state.get.await?.unwrap;
Streaming Execution ๐ก
In addition to invoke(), a compiled graph can be executed as a push-based
event stream. This is ideal for progress reporting, logging, and live UIs:
use *;
use HashSet;
use Arc;
use async_trait;
;
async
The stream always terminates with either WorkflowFinished (success) or
WorkflowError (failure) as its final event โ errors are delivered as events
rather than via the return value.
๐ Examples
Explore the examples/ directory for complete working examples:
| Example | Description |
|---|---|
| hello_world | Simple linear workflow - perfect starting point |
| conditional_routing | Dynamic path selection based on state |
| parallel_execution | Concurrent node execution |
| custom_state | Implementing custom state backends |
| data_pipeline | Multi-stage data processing pipeline |
| error_handling | Robust error handling strategies |
Run any example:
๐๏ธ Architecture
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ StateGraphBuilder โ
โ (Declarative graph construction API) โ
โโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ compile()
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ StateGraph โ
โ (Validated, executable workflow) โ
โ โโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโ โ
โ โ Node A โโโโถโ Node B โโโโถโ Node C โ โ
โ โโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโ โ
โ โฒ โ โ
โ โโโโโโโโโโโ(state)โโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ invoke() / stream()
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ DefaultMemoryState โ
โ (JSON-based persistent state storage) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐ง API Reference
Core Types
StateGraphBuilder: Builder for constructing workflow graphsStateGraph: Compiled, executable graph instanceAgentNode: Trait for implementing custom nodesAgentState: Trait for state management backendsDefaultMemoryState: Built-in JSON-based state implementationLangGraphError: Error type for the libraryStreamEvent: Events emitted by the streaming API
Key Methods
// Building graphs
new // Create new builder
builder.add_node // Add a node
builder.add_edge // Add static edge
builder.add_conditional_edge // Add conditional edge (routers: Vec<Box<dyn Fn(&S) -> String>>)
builder.compile // Validate & build graph
// Executing workflows
graph.invoke // Run the workflow to completion
graph.stream // Run with a push-based StreamEvent stream
// Managing state
state.set.await // Store value
state..await? // Retrieve typed value
๐งช Testing
Run the test suite:
# Unit tests
# Run specific example tests
# Integration tests (if available)
๐ค Contributing
Contributions are welcome! Please feel free to submit Pull Requests.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Development Setup
# Clone the repository
# Build the project
# Run examples
# Run tests
๐ Requirements
- Rust: 2024 edition or later
- Tokio: Async runtime (included as dependency)
- Platform: macOS, Linux, Windows (tested)
๐ License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
๐ Acknowledgments
- Inspired by LangChain/LangGraph Python library
- Built with Rust ecosystem tools
- Async runtime powered by Tokio
๐ Support
- ๐ Check the examples for usage patterns
- ๐ Report issues via GitHub Issues
- ๐ฌ Discussions welcome in GitHub Discussions
Built with โค๏ธ using Rust's type system and async capabilities