企业级 AI Agent 基础设施框架 - 双模式执行引擎（ReAct + IEL）
FastReAct 是一个支持双模式执行的 AI Agent 框架：
- 标准 ReAct 模式：适用于简单查询和单步任务
- 高级 IEL 模式：适用于复杂工作流和动态重规划
- 双模式执行: ReAct（轻量）+ IEL/ToolGraph（高级）
- 隐私优先: 支持完全离线部署，数据不离开本地环境
- 模型灵活: 支持任何 OpenAI-compatible API
- 成本可控: 通过智能上下文管理优化 Token 使用
- 可扩展: 支持自定义工具和 MCP 协议集成
版本: v1.1.0-alpha
- 核心功能可用
- 部分高级功能开发中
- 生产使用需谨慎
- 适合学习和原型开发
git clone https://github.com/atom32/FastReAct.git
cd FastReAct
pip install -e .# 方法 1: 使用用户配置（推荐）
mkdir -p ~/.fastreact
cp user_config.example.json ~/.fastreact/config.json
# 编辑添加你的 API keys
# 方法 2: 使用环境变量
export FASTREACT_API_KEY=your-api-key-here# 方式 1：标准 REPL（ReAct 模式）
python -m fastreact.cli.main shell
# 方式 2：GraphAgent REPL（智能规划）⭐ 新增
python scripts/run_graph_repl
# 单次查询
python -m fastreact.cli.main run "帮我计算 25 * 34"
# 启动 Gateway
python scripts/run_gateway.pyGraphAgent REPL 特点：
- ✅ 自动评估任务复杂度
- ✅ GraphAgent 自动生成执行计划
- ✅ 用户确认后再执行
- ✅ 实时进度反馈
详细指南: INSTALLATION.md | NEW_ENVIRONMENT_SETUP.md
FastReAct 支持通过环境变量控制执行模式和行为：
# 启用非阻塞 IEL 模式（渐进式交互执行）
# 特点：输入框始终可用，可随时输入 'stop' 中断执行
export FASTREACT_STEPPABLE=1
# Windows PowerShell: $env:FASTREACT_STEPPABLE="1"
# 强制文本模式（避免 ANSI 颜色码在旧终端显示为乱码）
export FASTREACT_TEXT_MODE=1
# Windows PowerShell: $env:FASTREACT_TEXT_MODE="1"
# 强制执行模式（禁用自动复杂度评估）
export FASTREACT_MODE=auto|react|graph_agent|iel
# Windows PowerShell: $env:FASTREACT_MODE="graph_agent"使用示例（Windows PowerShell）:
# 启用非阻塞 IEL 模式 + 文本模式
$env:FASTREACT_STEPPABLE="1"
$env:FASTREACT_TEXT_MODE="1"
python -m fastreact.cli.unified_repl使用示例（Linux/Mac）:
# 启用非阻塞 IEL 模式
export FASTREACT_STEPPABLE=1
python -m fastreact.cli.unified_repl详细技术说明: IEL_TECHNICAL_DEEP_DIVE.md
模式 A：标准 ReAct 循环
- 推理-行动-观察循环 (Thought → Action → Observation)
- 异步工具执行
- 错误处理和重试机制
- 会话管理
- 默认模式，用于简单查询
模式 B：IEL + ToolGraph（高级）
- IEL (Interactive Execution Loop): Plan → Execute → Reflect → Replan
- ToolGraph: DAG 工作流编排
- 动态图修改（插入/删除/替换节点）
- Human-in-the-loop（用户中断）
- 快照和回滚机制
- 可选模式，用于复杂工作流
- Memory Flush: 自动总结长对话（50k tokens 触发）
- Memory Retrieval: 向量检索历史对话（可选）
- Progressive Compaction: 多层压缩（已实现，未完全集成）
- 13 个内置工具（Calculator, Search, HTTP, Bash 等）
- MCP 协议集成（GitHub, Apollo Core）
- 工具策略控制（Allow/Deny 列表）
- 风险分级和审批机制
- 4 层配置优先级（ENV > USER > PROJECT > DEFAULT）
- 支持多租户场景
- 灵活的配置管理
- CLI REPL（交互式命令行）
- WebSocket Gateway（实时通信）
- Web UI（通过 FastReAct-web 项目）
- Progressive Compaction 完全集成
- 多 Agent 协作（规划 v2.0.0）
- Agent 编排（规划 v2.0.0）
- 自动工具发现（规划 v2.0.0）
- 完整的生产环境支持
┌─────────────────────────────────────────────────────────────┐
│ 用户输入层 │
│ CLI REPL / Python API / WebSocket Gateway │
└────────────┬────────────────────────────────────────────────┘
│
├──────────────────────────────────────────┐
│ │
▼ ▼
┌──────────────────────────┐ ┌──────────────────────────┐
│ 方式 A：直接使用 │ │ 方式 B：手动构建 Graph │
│ FastReAct.run_async() │ │ (高级用法) │
└──────────┬───────────────┘ └──────────┬───────────────┘
│ │
▼ ▼
┌──────────────────────────┐ ┌──────────────────────────┐
│ ReAct 循环引擎 │ │ ToolGraph 构建 │
│ (标准模式) │ │ - 定义节点和边 │
│ │ │ - 设置依赖关系 │
│ 1. LLM 推理 (Thought) │ │ - 声明式 API │
│ 2. 解析工具调用 │ └──────────┬───────────────┘
│ 3. 并发执行工具 │ │
│ 4. 观察结果 (Observation)│ ▼
│ 5. 循环或返回答案 │ ┌──────────────────────────┐
│ │ │ 执行引擎选择 │
│ 适合：简单查询、对话 │ ├──────────┬───────────────┤
└──────────┬───────────────┘ │ │ │
│ │ ▼ ▼
│ │ ┌──────────┐ ┌─────────────┐
│ │ │ToolRuntime│ │IELLoop │
│ │ │(DAG执行) │ │(交互式) │
│ │ │ │ │ │
│ │ │-拓扑排序 │ │-动态重规划 │
│ │ │-并行执行 │ │-用户中断 │
│ │ │ │ │-快照回滚 │
│ │ └────┬─────┘ └──────┬──────┘
│ │ │ │
└─────────────────────────────┴────────┴──────────────┘
│
▼
┌──────────────────────┐
│ 工具层 │
│ ┌────────────────┐ │
│ │ Builtin Tools │ │
│ │ (13 个工具) │ │
│ └────────────────┘ │
│ ┌────────────────┐ │
│ │ MCP Servers │ │
│ │ (GitHub, etc) │ │
│ └────────────────┘ │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 基础设施层 │
│ LLM / Config / Store│
└──────────────────────┘
from fastreact import FastReAct
agent = FastReAct(api_key="your-key")
result = await agent.run_async("帮我搜索最新的 AI 新闻")
# 内部流程：
# 1. LLM 推理：决定调用 TavilySearch 工具
# 2. 执行工具：调用搜索 API
# 3. 观察结果：获得搜索结果
# 4. LLM 总结：返回最终答案使用场景：
- 简单问答
- 单步工具调用
- REPL 交互
特点：
- 自动循环直到得到答案
- 无需手动规划
- 快速、轻量
from fastreact.graph import (
create_tool_node, ToolGraph, create_pipeline
)
from fastreact.graph import IELLoop, IELExecutionContext
from fastreact.graph import StepExecutor, Replanner
# 1. 定义工作流图
node1 = create_tool_node(id="search", tool=search_tool)
node2 = create_tool_node(id="analyze", tool=analyze_tool)
node3 = create_tool_node(id="report", tool=report_tool)
graph = ToolGraph("my_workflow")
graph.add_node(node1).add_node(node2).add_node(node3)
graph.connect("search", "analyze")
graph.connect("analyze", "report")
# 2. 选择执行方式
# 方式 B1：DAG 执行（简单）
from fastreact.graph import ToolRuntime, execute_graph
result = await execute_graph(graph, inputs={"query": "AI news"})
# 方式 B2：IEL 循环（高级，支持重规划）
context = IELExecutionContext(graph, initial_inputs={"query": "AI news"})
executor = StepExecutor(tools=tool_registry)
replanner = Replanner(llm_client=client)
loop = IELLoop(executor, replanner)
result = await loop.run(context)使用场景：
- 复杂多步骤工作流
- 需要动态重规划
- 需要 human-in-the-loop
- 需要快照回滚
特点：
- 完全控制执行流程
- 可视化工作流
- 支持失败恢复
| 特性 | ReAct 模式 | ToolGraph/IEL 模式 |
|---|---|---|
| 入口 | FastReAct.run_async() |
手动构建 ToolGraph |
| 规划 | LLM 自动决策（隐式） | 用户显式定义 DAG |
| 执行 | 循环直到答案 | 按图结构执行 |
| 重规划 | 无 | IEL 支持动态修改 |
| 中断 | 不支持 | 支持用户输入/中断 |
| 回滚 | 无 | 快照和回滚机制 |
| 适用 | 90% 的简单任务 | 10% 的复杂工作流 |
┌─────────────────────────────────────────┐
│ 用户接口层 │
│ CLI REPL / WebSocket Gateway / Web UI │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ 执行引擎层 │
│ ┌────────────────┐ ┌───────────────┐ │
│ │ FastReAct │ │ ToolGraph/IEL │ │
│ │ (ReAct Loop) │ │ (可选) │ │
│ └────────────────┘ └───────────────┘ │
│ - 上下文管理 (Memory Flush) │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ 工具层 │
│ ┌─────────┐ ┌──────────┐ ┌────────┐ │
│ │ Builtin │ │ Memory │ │ MCP │ │
│ │ Tools │ │ Retrieval │ │ Servers│ │
│ └─────────┘ └──────────┘ └────────┘ │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ 基础设施层 │
│ LLM 抽象 / 配置系统 / 存储层 │
└─────────────────────────────────────────┘
注意：
- FastReAct (ReAct)：用于 90% 的简单任务，REPL 的默认方式
- ToolGraph/IEL：用于 10% 的复杂工作流，需要手动构建
from fastreact import FastReAct
agent = FastReAct(api_key="your-api-key")
result = agent.run("2 + 2 * 3 = ?")
print(result['answer']) # 8# 在 REPL 中
>>> 计算 (25 + 35) * 2 - 10
>>> 搜索最新的 AI 新闻
>>> 在 atom32/FastReAct 创建一个 issue# 终端 1：启动 Gateway
python scripts/run_gateway.py
# 终端 2：启动 Web UI（需要 FastReAct-web 项目）
cd ../FastReAct-web
npm run dev
# 浏览器访问 http://localhost:3001- ReAct 循环: 轻量级、快速响应，适合简单任务
- IEL + ToolGraph: 复杂工作流、动态重规划、Human-in-loop
- 根据任务复杂度自动选择
- 两种模式可独立使用，也可组合
- Plan → Execute → Reflect → Replan 循环
- 动态图修改（运行时插入/替换节点）
- 快照和回滚机制
- 用户中断和输入处理
- 失败自动重试和修复
- 声明式工作流定义（
node1 >> node2） - DAG 执行和依赖解析
- 并行执行（
(node1 | node2) >> node3） - 条件执行和循环支持
- 触发阈值: 50000 (soft) / 55000 (hard) tokens
- 自动总结旧消息
- 压缩比约 70%
- 已实现并集成
- 标准化工具协议
- 支持 GitHub MCP、Apollo Core
- 100+ 社区 MCP servers 可用
- 已实现并可用
- ENV > USER > PROJECT > DEFAULT
- 支持多租户场景
- 敏感信息隔离
- 已实现并验证
- 风险分级（HIGH/MEDIUM/LOW）
- 执行审批机制
- 动态策略控制
- 已实现
- 测试覆盖不足: 缺少端到端集成测试
- 性能数据未验证: 部分优化效果未实际测量
- Progressive Compaction: 代码已写但未完全集成
- Alpha 版本: 不推荐直接用于生产环境
- 部分 MCP servers 在 Windows 上有兼容性问题
- 长对话场景需要更多测试
- 错误处理需要更健壮
- 学习 ReAct 架构
- 快速原型开发
- 小规模内部部署
- 需要本地化/隐私保护
- 需要自定义工具
- 大规模生产环境（目前）
- 需要完整功能（vs LangChain）
- 不想配置环境
- 需要开箱即用的完美体验
- ReAct 核心引擎
- Memory Flush
- MCP 协议集成
- 4 层配置优先级
- 工具系统
- Progressive Compaction 集成
- 完整的集成测试
- 性能基准测试
- 生产环境验证
- 错误处理增强
- 多 Agent 协作
- Agent 编排
- 自动工具发现
欢迎贡献！请查看 CLAUDE.md 了解开发规则。
# 克隆仓库
git clone https://github.com/atom32/FastReAct.git
cd FastReAct
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或
venv\Scripts\activate # Windows
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
python test_config_priority.py
python test_memory_flush_logic.py- Anthropic - Claude 模型
- ModelContextProtocol - MCP 协议
- LangChain - 灵感来源
- 作者: atom32
- 项目: https://github.com/atom32/FastReAct
- 问题反馈: https://github.com/atom32/FastReAct/issues
最后更新: 2025-02-05 版本: v1.1.0-alpha 状态: Alpha - 核心功能可用，持续改进中