Langgraph Adaptive Tool Middleware

LangGraph工具中间件

LangGraph的生产就绪工具执行中间件，具有自动重试、断路器和错误恢复功能。

  

处理导致工具调用崩溃的实际生产故障：网络超时、API错误、速率限制和瞬时故障。

安装

# From source (for now)
pip install -e .

# Once published to PyPI
pip install langgraph-tool-middleware

看 安装.md 了解详细的安装说明。

快速开始

from src.production_middleware import ProductionToolMiddleware

# Initialize
middleware = ProductionToolMiddleware(
    enable_circuit_breaker=True,
    enable_error_feedback=True,
    max_retries=3
)

# Execute a tool with automatic retry
result = await middleware.execute(
    tool_call={"name": "get_weather", "arguments": {"location": "NYC"}},
    user_query="What's the weather in NYC?"
)

为什么存在

98%的工具调用失败是执行失败，而不是验证错误。

此中间件侧重于生产中实际发生的故障：

• 网络超时（35%的故障）→ 使用指数回退重试
• API错误（28%的失败）→ 智能重试逻辑
• 速率限制（15%的故障）→ 断路器型式
• 瞬态故障（20%的故障）→ 智能重试

经过验证的结果

在多种故障场景中进行34000多次测试：

统计显著性： Z分数138.93（几乎可以肯定）

查看完整结果： test_results/TEST_SUMMARY.md

安装

pip install -r requirements.txt

在中设置OpenAI API密钥 .env:

OPENAI_API_KEY=your_key_here

LangGraph集成

插入式替换（3行！）

from src.production_middleware import ProductionToolMiddleware
from src.langgraph_integration import create_resilient_tool_node

# 1. Initialize middleware
middleware = ProductionToolMiddleware(max_retries=3)

# 2. Create your graph as normal
workflow.add_node("agent", call_model)

# 3. Use resilient tool node (ONE LINE!)
workflow.add_node("tools", create_resilient_tool_node(middleware))

# That's it! Your tools now have retry, circuit breakers, and recovery.

看 examples/langgraph_quickstart.py 举一个完整的例子。

独立使用

from src.production_middleware import ProductionToolMiddleware

# Initialize
middleware = ProductionToolMiddleware()

# Execute with automatic retry
result = await middleware.execute(
    tool_call={"name": "get_weather", "arguments": {"location": "London"}},
    user_query="What's the weather in London?"
)

if result['success']:
    print(f"✅ {result['result']}")
else:
    print(f"❌ {result['error']}")

建筑

核心组件

1. 弹性执行者 (src/resilient_executor.py)

- 使用指数回退重试 - 超时处理 - 速率限制检测

1. 断路器 (src/circuit_breaker.py)

- 防止级联故障 - 冷却后自动恢复 - 每个工具的运行状况跟踪

1. 误差反馈 (src/error_feedback.py)

- 将真实错误反馈给LLM - 根据实际故障进行纠正 - 不仅仅是预测

1. 可观测性 (src/observability.py)

- 每个工具的成功率 - 错误模式 - 延迟跟踪

1. 主中间件 (src/production_middleware.py)

- 协调所有组件 - 清洁API - 生产准备就绪

测试

快速演示（查看实际操作）

# Show 20 baseline failures vs middleware recovery
python test/compare.py 20

这将运行测试，直到基线失败，然后显示中间件的功能。典型输出：

• 基线： ❌ 失败（超时/速率限制/API错误）
• 中间件： ✅ 尝试2-3次后成功（恢复率90%）

完整测试套件

# Comprehensive test (34,000+ tests)
python test/comprehensive_test.py

# Scale test (custom size)
echo "5000" | python test/test_at_scale.py

# Quick validation
python test/test_production_middleware.py

配置

middleware = ProductionToolMiddleware(
    # Retry settings
    max_retries=3,              # Max retry attempts
    retry_delay=1.0,            # Base delay between retries
    max_retry_delay=60.0,       # Max delay (exponential backoff)
    timeout=30.0,               # Max execution time
    
    # Circuit breaker
    enable_circuit_breaker=True,
    failure_threshold=5,        # Failures before circuit opens
    recovery_timeout=60.0,      # Time before retry
    half_open_max_calls=1,      # Test calls during recovery
    
    # Error feedback
    enable_error_feedback=True,
    model="gpt-4o-mini",       # LLM for corrections
    max_correction_attempts=2,  # Correction retries
    
    # Observability
    enable_observability=True
)

何时使用

高价值：

• 网络状况不稳定
• 具有速率限制的第三方API
• 具有瞬态故障的微服务
• 生产失败率>20%

中等价值：

• 稳定的基础设施，偶尔会出现问题
• 10-20%的故障率

低值：

• 完善的基础设施（故障率\<5%）
• 完全可靠的API（罕见）

项目结构

├── src/                    # Production middleware
│   ├── production_middleware.py
│   ├── resilient_executor.py
│   ├── circuit_breaker.py
│   ├── error_feedback.py
│   ├── observability.py
│   ├── tools.py           # Tool definitions
│   └── test_dataset.py    # Test cases
├── test/                   # Test scripts
│   ├── test_production_middleware.py
│   ├── test_at_scale.py
│   └── comprehensive_test.py
├── test_results/           # Test results
│   └── TEST_SUMMARY.md    # Full 34K+ test results
├── README.md              # This file
├── USAGE.md               # Detailed usage
└── requirements.txt

关键见解

验证中间件（HiTEC、ToolCritic）解决了约2%的问题（模式错误）。

该中间件解决了约98%的问题（执行失败）。

现代LLM已经很好地处理了模式验证。真正的问题是网络故障、API错误、速率限制和瞬态问题。这就是它解决的问题。

许可证

麻省理工学院

贡献

PR欢迎！重点领域：

• 其他重试策略
• 更复杂的断路器
• 与LangGraph集成
• MCP协议支持