langgraph-rust

Rust 版 LangGraph 社区移植实现——有状态、图驱动的 Agent 工作流引擎。

免责声明：本项目为社区维护的独立实现，与 LangChain / LangGraph 官方无隶属关系。API 与 Python 版 LangGraph 保持概念对齐，但不保证完全兼容。0.1.x 版本视为早期预览，公共 API 可能在次要版本中调整。

安装

在 Cargo.toml 中按需引入：

[dependencies]
langgraph-core = "0.1"
langgraph-pregel = "0.1"
langgraph-checkpoint = "0.1"
# 可选
langgraph-prebuilt = "0.1"
langgraph-checkpoint-sqlite = "0.1"

CLI 与 HTTP 服务：

cargo install langgraph-cli   # 二进制名: langgraph
cargo install langgraph-http  # 二进制名: langgraph-http

快速开始

use langgraph_core::{StateGraph, State};
use langgraph_pregel::SequentialExecutor;
use std::collections::BTreeMap;
use std::sync::Arc;
use serde_json::json;

let mut graph = StateGraph::new();
graph.add_node("append_b", Arc::new(|state: &State| {
    let text = state.get("text").and_then(|v| v.as_str()).unwrap_or("");
    Ok(BTreeMap::from([(String::from("text"), json!(format!("{text}b")))]))
}))?;
graph.set_entry_point("append_b");
graph.set_finish_point("append_b");

let compiled = graph.compile()?;
let result = SequentialExecutor.invoke(
    &compiled,
    BTreeMap::from([(String::from("text"), json!("a"))]),
)?;
assert_eq!(result.get("text"), Some(&json!("ab")));
# Ok::<(), Box<dyn std::error::Error>>(())

更多示例见 crates/langgraph-pregel/examples/minimal_graph.rs 与 crates/langgraph-prebuilt/README.md。

当前进度

• Cargo workspace 初始化
• 创建 langgraph-core、langgraph-pregel、langgraph-checkpoint
• 最小 StateGraph builder + compile
• 顺序执行器 invoke
• {"text":"ab"} 最小示例测试
• 统一错误类型 GraphError 与 StateValue
• CheckpointSaver trait 草案 + InMemorySaver
• tests/compat/ 第一批 fixture
• channel 抽象（LastValue / BinaryOperatorAggregate / Topic）与 superstep 执行
• versions_seen / channel versioning 元数据链路
• checkpoint 恢复闭环（resume / resume_latest / pending_writes materialize）
• 显式中断与恢复（interrupt_thread）
• resume_latest 最新 checkpoint 选择修复（按数值版本，不依赖返回顺序）
• Phase 4 第一段：Command::Interrupt + runtime context 注入（兼容旧 add_node）
• Phase 4 第二段：节点触发中断时自动持久化 checkpoint（可直接 resume）
• Phase 4 第三段：Command::Goto + add_conditional_edges 条件路由衔接
• Phase 4 第四段：组合命令（GotoMany/命令链）与 command trace 可观测性
• Phase 4 第五段：命令策略层（CommandPolicy）+ bridge 审计钩子
• Phase 5 第一段：异步入口（ainvoke / aresume 等）与同步语义对齐测试
• Phase 5 第二段：astream 事件流模型（节点事件 / 状态片段 / 命令与中断事件）
• Phase 5 第三段：checkpoint bridge thread 维度 astream（流式执行 + 自动落盘 + resume 闭环）
• Phase 6：SQLite / Postgres checkpointer 及跨后端一致性测试
• Phase 7 第一段：langgraph-prebuilt 最小闭环（ToolNode / ValidationNode）
• Phase 7 第二段：ToolNode 高级能力（路由策略 / 错误策略 / 审计钩子）
• Phase 7 第三段：ValidationNode 结构化规则集 + 可组合验证器 + 最小 ReAct 编排 API
• Phase 7 第四段：默认 planner/tool-calling 模板 API（基于 ReactAgentBuilder 封装）
• Phase 7 第五段：默认模板多工具策略（主工具 + 选择器 + 回退工具）
• Phase 8 第一段：最小 langgraph-cli（JSON 输入 -> 执行 -> JSON 输出）
• Phase 8 第二段：CLI 执行元数据输出（--metadata）
• Phase 8 第三段：CLI 流式事件输出（--stream / JSONL）
• Phase 8 第四段：图预设可发现性与输入校验提示（--list-graphs + 预设级校验）
• Phase 8 第五段：thread/checkpoint 运行入口（invoke_thread / resume_latest）
• Phase 8 第六段：thread 精准恢复入口（resume by checkpoint_id）
• Phase 8 第七段：thread 显式中断入口（interrupt_thread + pending writes 注入）
• Phase 8 第八段：thread 异步 CLI 入口（--async 对齐 async bridge）
• crates.io 发布准备（LICENSE、元数据、crate 文档、字段稳定性约定）

目录

发布到 crates.io

按依赖顺序发布（每个 crate 执行 cargo publish -p <name>）：

1. langgraph-core
2. langgraph-checkpoint
3. langgraph-pregel、langgraph-prebuilt、langgraph-checkpoint-sqlite、langgraph-checkpoint-postgres
4. langgraph-cli、langgraph-http

发布前本地验证：

cargo test --workspace
cargo publish --dry-run -p langgraph-core
# ... 对其余 crate 重复

已知限制

• 无内置 LLM 提供商集成（需自行在节点中调用 LLM SDK）
• 与 Python LangGraph 的 compat fixture 仍较少
• HTTP 入口暂无 stream / SSE 模式

下一步

1. 评估 thread 模式下 --stream 的分阶段支持方案（含 checkpoint 落盘时机）
2. 为 HTTP 入口补充 stream 模式与 SSE/JSONL 输出选型评估
3. 扩充 tests/compat/ 与 examples/

License

MIT — 见 LICENSE。