langgraph4rust π¦
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
- πΎ 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.1.0"
= { = "1", = ["full"] }
π 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 routing (see conditional_routing example)
builder.add_conditional_edges?;
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;
π 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()
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββ
β 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 library
Key Methods
// Building graphs
new // Create new builder
builder.add_node // Add a node
builder.add_edge // Add static edge
builder.add_conditional_edges // Add conditional edge
builder.compile // Validate & build graph
// Executing workflows
graph.invoke // Run the workflow
// 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