Mini ReAct Agent

一个简洁但功能完整的 ReAct Agent 执行引擎。项目重点关注执行过程的可观测性和分析能力，从零实现核心逻辑，不依赖现有框架。

📊 可视化展示

启动可视化界面

# 启动Web可视化界面
python visualization/run_visualization.py

# 或者直接启动Streamlit应用
streamlit run visualization/visualization_app.py --server.port 8502

# 访问 http://localhost:8502 查看轨迹分析

功能特性

• 📊 执行仪表板: 展示会话总数、平均执行时间、工具使用统计
• 🔍 会话详情: 查看具体会话的完整执行轨迹和步骤分解
• 📈 性能分析: 可视化API响应时间、执行效率趋势图表
• 🛠️ 工具分析: 各工具使用频次、成功率和平均耗时统计

界面截图

📊 执行仪表板

🔍 会话执行轨迹

📈 性能分析

🛠️ 工具使用分析

🚀 快速开始

1. 安装配置

# 克隆项目
git clone <repository-url>
cd mini-react-agent

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入你的API密钥

2. 运行示例

# 基础使用
python main.py "你好，请介绍一下自己"

# 启用观测模式（保存轨迹并可显示更详细分析）
python main.py --observe "搜索最新的AI技术发展"

# 启动可视化界面
python visualization/run_visualization.py

3. 环境变量配置

项目根目录已提供 .env.example 模板文件，使用时将其复制到.env文件 ，其中包含以下配置项：

# LLM Configuration
OPENAI_API_KEY=your_openai_api_key_here          # 必填：OpenAI API密钥
OPENAI_BASE_URL=https://api.openai.com/v1        # 可选：API基础URL，支持兼容服务
OPENAI_MODEL=gpt-3.5-turbo                       # 可选：模型名称，默认gpt-3.5-turbo

# Serper API Configuration (for web search)
SERPER_API_KEY=your_serper_api_key_here          # 可选：搜索API密钥，启用search工具需要

配置说明：

• OPENAI_API_KEY：必填，从 OpenAI 或兼容服务商获取
• OPENAI_BASE_URL：可选，支持使用兼容OpenAI API的服务（如SiliconFlow、DeepSeek等）
• OPENAI_MODEL：可选，指定使用的模型，默认为 gpt-3.5-turbo
• SERPER_API_KEY：可选，从 Serper 获取，用于启用网络搜索功能

4. 获取API密钥

• OpenAI API: https://platform.openai.com/
• Serper API: https://serper.dev/ - 搜索API（用于启用 search 工具）
• 兼容服务: SiliconFlow、DeepSeek等提供OpenAI兼容接口的服务商

🎯 使用方法

程序启动时会显示配置信息（以你的环境变量为准）：

🤖 ReAct Agent 配置信息:
   模型: <OPENAI_MODEL 或默认 gpt-3.5-turbo>
   Base URL: <OPENAI_BASE_URL 或 N/A>
   API Key: 已设置/未设置
   Serper API Key: 已设置/未设置

交互式模式

# 基础交互模式
python main.py

# 启用观测功能/分析报告
python main.py --observe
python main.py --analysis
python main.py --observe --analysis

进入交互式对话模式，支持连续对话：

💬 你好！我是你的智能助手，可以帮你搜索信息、进行计算等。请告诉我你需要什么帮助？

交互模式特性:

• 支持连续多轮对话，保持上下文
• 启用 observe/analysis 时，自动保存轨迹并可显示详细分析
• 输入 exit、quit 或按 Ctrl+C 退出

单次查询模式

# 基础查询
python main.py "搜索一下今天北京的天气"
python main.py "帮我计算 (25 + 15) * 3 - 8"

# 启用执行观测（显示详细执行轨迹）
python main.py --observe "搜索最新的AI技术发展"

# 启用分析报告（显示性能分析和决策过程）
python main.py --analysis "计算复合利息：本金10000，年利率5%，10年后的金额"

# 同时启用观测和分析
python main.py --observe --analysis "创建一个Python脚本来分析数据"

# 使用--query参数（等效于位置参数）
python main.py --query "search for latest news about OpenAI"

命令行参数说明:

• --observe: 启用深度执行观测，保存并展示执行轨迹
• --analysis: 启用执行分析报告，显示性能指标和决策分析
• --query: 指定查询内容（可选，也可直接使用位置参数）
• 位置参数: 直接在命令后跟查询文本，支持多个词组自动拼接

轨迹数据管理

# 运行观测功能测试
python -m tests.test_observation

# 查看轨迹数据
ls traces/sessions/
ls traces/analysis/

轨迹保存说明:

🔄 自动记录到traces的方法:

1. 交互式模式:

   • python main.py --observe - 启用观测模式，记录执行轨迹
   • python main.py --analysis - 启用分析模式，记录性能分析
   • python main.py --observe --analysis - 同时启用观测和分析

2. 单次查询模式:

   • python main.py --observe "查询内容" - 单次查询+观测记录
   • python main.py --analysis "查询内容" - 单次查询+分析记录
   • python main.py --observe --analysis "查询内容" - 单次查询+完整记录

📁 存储位置:

• 会话轨迹数据：traces/sessions/ (启用 --observe 或 --analysis 时)
• 分析报告数据：traces/analysis/ (启用 --analysis 时)
• 文件命名格式：查询内容_YYYYMMDD_HHMMSS.json

⚠️ 注意:

• 不使用 --observe 或 --analysis 参数时，不会保存轨迹数据
• 可视化界面需要已有会话轨迹数据才能正常显示分析结果

📋 实际会话轨迹样例

以下是一个简单计算任务的完整ReAct执行轨迹示例：

🔄 ReAct循环过程

# 执行命令
python main.py --observe "计算 15 + 27 等于多少？"

执行轨迹步骤:

1. 🤔 Think (思考)

   {
     "thought": "用户要求计算15 + 27，这是一个简单的加法运算。我可以使用calculator工具来执行这个计算。",
     "action": "calculator",
     "action_input": "15 + 27"
   }

2. ⚡ Act (行动)

   • 工具调用: calculator
   • 输入参数: "15 + 27"

3. 👁️ Observe (观察)

   观察结果: 计算结果: 15 + 27 = 42
   

4. 🎯 Final Answer (最终答案)

   {
     "thought": "计算结果显示15 + 27 = 42，这是一个正确的加法结果。现在我可以给出最终答案了。",
     "answer": "15 + 27 = 42"
   }

📊 性能统计

• 会话时长: 8.35秒
• 总Token消耗: 1,156
• API调用次数: 2次
• 工具使用: calculator × 1
• 错误次数: 0

💾 轨迹文件

完整轨迹数据保存在: traces/sessions/计算 15 + 27 等于多少？_20250902_171849.json

🔧 可用工具

• 🔍 搜索工具 (search): 网络信息搜索（需要 SERPER_API_KEY）
• 🧮 计算器 (calculator): 数学表达式计算，支持基本运算符
• 📁 文件工具 (file): 文件读写操作，支持创建、读取、列出文件

🏗️ 技术架构

ReAct执行循环

思考 (Think) → 决策 (Decide) → 行动 (Act) → 观察 (Observe) → 思考 (Think) ...

核心组件

• Agent核心 (agent.py): 完整ReAct循环逻辑实现
• 工具系统 (tools.py): 搜索（可选）、计算、文件操作工具
• 轨迹存储 (trace_storage.py): JSON持久化和会话管理
• 可视化应用 (visualization_app.py): Streamlit分析界面

---

📖 详细技术文档: 查看 技术报告 了解完整的架构设计和实现细节