Broken Langgraph MCP

Broken LangGraph+MCP代理（演示）

此存储库演示了 破碎的 LangGraph代理通过stdio调用真正的MCP（模型上下文协议）服务器，以及 固定的 解决问题的版本。

概述

这个项目展示了构建与MCP服务器交互的LangGraph代理时的常见陷阱，以及如何修复它们。演示包括：

• broken_agent.py：一个故意有缺陷的代理，有几个bug
• agent_fixed.py：一个实现了正确的错误处理、重试逻辑和人在循环（HITL）审批门的更正版本
• mcp_server.py：提供文件系统和数据库操作的模拟MCP服务器

这个项目展示了什么

破坏行为（in broken_agent.py)

1. 无错误处理：工具错误导致整个代理运行崩溃
2. 脆弱的输入解析：模糊的命令（例如。， update user:123 无字段/值）原因 IndexError 崩溃
3. 无安全门：未经批准，立即执行破坏性操作（删除、更新）

固定行为（in agent_fixed.py)

1. 优雅的错误处理：工具故障被捕获和处理，而不会崩溃
2. 输入验证：模糊的命令提示澄清，而不是崩溃
3. 人在循环（HITL）：破坏性工具需要明确 APPROVE/DENY 确认
4. 重试逻辑：失败的操作会触发恢复策略（例如，如果 read_file 失败，尝试 search_files 寻找替代方案）
5. 更好的输出：清除错误消息和审计跟踪

MCP服务器工具

这 mcp_server.py 提供以下工具：

• read_file(path)：从模拟文件系统读取文件
• search_files(query)：按名称搜索文件
• delete_file(path)：删除文件（破坏性）
• get_record(key)：检索数据库记录
• update_record(key, patch)：更新数据库记录（破坏性）

设置

先决条件

• Python 3.8+
• macOS/zsh（或调整shell的命令）

安装

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

用法

运行破碎的代理

python3 broken_agent.py

尝试以下输入以查看错误：

• read /configs/missing.yaml -未找到文件中的崩溃
• update user:123 -因IndexError（缺少字段/值）而崩溃
• delete /configs/app.yaml -未经询问即删除

运行固定代理

python3 agent_fixed.py

尝试相同的输入，看看它们是如何处理的：

• read /configs/missing.yaml -优雅地处理错误并尝试恢复
• update user:123 -要求澄清
• delete /configs/app.yaml -执行前需要批准

示例会话（固定代理）

You> read /configs/missing.yaml
Agent> Recovered gracefully from a tool failure:
1) Tried read_file('/configs/missing.yaml') → File not found
2) Reflected and tried search_files('missing.yaml') → no matches
Outcome: I could not find an alternative file to read.
AUDIT: [{'tool': 'read_file', 'args': {'path': '/configs/missing.yaml'}, 'ok': False, 'error': 'File not found: /configs/missing.yaml'}, {'reflection': "read_file failed; trying search_files for 'missing.yaml'"}, {'tool': 'search_files', 'args': {'query': 'missing.yaml'}, 'ok': True, 'result': []}]

You> delete /configs/app.yaml
Agent> Approval required before running delete_file with args={'path': '/configs/app.yaml'}.
Type APPROVE or DENY.

You> APPROVE
Agent> OK: deleted
AUDIT: [{'tool': 'delete_file', 'args': {'path': '/configs/app.yaml'}, 'ok': True, 'result': 'deleted'}]

建筑

LangGraph状态图

固定代理使用具有以下节点的状态图：

1. plan：分析用户输入并创建工具执行计划
2. gate：检查计划的工具是否具有破坏性
3. approval_router：基于审批状态的路线
4. ask_approval：提示用户批准（结束运行，等待下一次输入）
5. call_tool：执行MCP工具调用
6. reflect_retry：实施故障恢复策略
7. finalize：格式化最终输出

MCP集成

两个代理都通过stdio与MCP服务器通信：

• 每次工具调用都会生成一个新的MCP服务器子流程
• 使用 mcp.client.stdio 客户端库
• 服务器通过FastMCP框架提供工具

主要学习内容

1. 始终优雅地处理工具错误 -不要让例外情况让你的代理崩溃
2. 验证用户输入 -解析前检查所需参数
3. 实施审批门 -要求明确确认破坏性操作
4. 添加重试逻辑 -当操作失败时，尝试其他策略
5. 提供明确的反馈 -包括审计跟踪和有意义的错误消息

许可证

这是一个演示/教育项目。