一个简洁的 ReAct 模式 AI Agent 学习项目
NanoAgent 是一个用于学习手搓 Agent 的轻量级项目，基于 ReAct（Reasoning + Acting）模式实现。
- ReAct 推理模式：Thought → Action → Observation → Final Answer
- 上下文压缩引擎：复刻 Hermes Agent 四阶段压缩算法，自动管理长对话上下文
- 资源消耗统计：每轮对话清晰展示 LLM 调用次数、Token 消耗等资源使用情况
- WhatsApp 集成：通过 neonize 协议级客户端（Go 底层 whatsmeow）实现，无需浏览器，扫码即用
- 多会话管理：手动切换会话，支持会话持久化
- 可扩展工具系统：支持加载自定义 Tools
- 中文优化：完善的 UTF-8 支持
pip install -r requirements.txt复制 .env.example 为 .env，然后在 .env 文件中设置你的 DeepSeek API Key：
cp .env.example .env编辑 .env 文件：
DEEPSEEK_API_KEY=your-api-key-here
从 DeepSeek Platform 获取 API Key。
# 终端模式
python nano_agent.py
# WhatsApp 模式
python whatsapp_gateway.pyNanoAgent/
├── nano_agent.py # 主程序（ReAct Agent + Session 管理 + 资源追踪）
├── context_compressor.py # 上下文压缩引擎（四阶段压缩算法）
├── whatsapp_gateway.py # WhatsApp 集成网关（neonize 协议级客户端）
├── requirements.txt # 依赖列表
├── .env.example # 环境变量模板
├── README.md # 项目文档
├── LICENSE # MIT License
├── tools/ # 自定义工具目录
│ └── your_tool/ # 每个工具一个文件夹
│ └── main.py # 工具入口
└── sessions/ # 会话存储目录
| 命令 | 说明 |
|---|---|
quit |
退出并保存会话 |
clear |
清空当前会话 |
new [名称] |
创建新会话 |
sessions |
列出所有会话 |
switch <id> |
切换到指定会话 |
compress |
手动压缩上下文 |
context |
查看当前上下文信息 |
你：北京今天的天气怎么样？
───────────────────────────────────────────────────────
🔄 推理中...
───────────────────────────────────────────────────────
📨 LLM原始响应:
Thought: 用户询问北京今天的天气...
Action: WebSearch
Action Input: 北京今天天气
🔧 执行工具: WebSearch
📥 输入: 北京今天天气
👁️ 观察结果: 北京今天晴，温度15-25度...
=======================================================
✅ Final Answer:
=======================================================
北京今天天气晴朗，温度15-25度，适合出行。
📌 使用工具：WebSearch
────────────────────────────────────────
📊 本轮资源消耗统计
────────────────────────────────────────
LLM 调用次数: 2 次
输入 tokens: 1,245
输出 tokens: 389
总计 tokens: 2,146
────────────────────────────────────────
复刻 Hermes Agent 的四阶段压缩算法：
| 阶段 | 说明 | 是否需要 LLM |
|---|---|---|
| Phase 1 | 清除旧工具结果 | ❌ |
| Phase 2 | 确定边界（头部/中间/尾部） | ❌ |
| Phase 3 | 生成结构化摘要 | ✅ |
| Phase 4 | 组装压缩后的消息列表 | ❌ |
压缩策略：
- 头部保护：始终保留前 N 条消息
- 尾部保护：按 token 预算保护最近的对话
- 中间摘要：对中间区域生成结构化摘要（目标/约束/进度/决策/文件/下一步）
- 迭代式重压缩：后续压缩时更新已有摘要，而非从零生成
触发条件：上下文 token 数达到阈值（默认 30%）时自动触发
每轮对话结束后输出详细的资源消耗统计：
- LLM 调用次数：包含推理调用和压缩调用
- Token 消耗：区分输入/输出 Token，单独统计压缩消耗
- 总计 Token：本轮所有 LLM 交互的 Token 总和
- 基于 UUID 的会话标识
- JSON 持久化存储
- 支持多会话切换
- 自动保存会话状态
通过 neonize 协议级客户端实现手机与 NanoAgent 的实时通信。
架构优势：
- 无浏览器、无 Selenium、无 DOM 爬取
- 直接 WebSocket 协议通信（Go 底层 whatsmeow）
- 扫码登录，稳定可靠
- 安装依赖：
pip install neonize segno - 代理配置（国内需要）：在
.env中配置代理
WA_PROXY=http://127.0.0.1:7890- 启动 WhatsApp 网关：
python whatsapp_gateway.py-
终端显示二维码 → 手机 WhatsApp 扫码登录：
- WhatsApp → 设置 → 关联设备 → 扫码
-
扫码成功后自动开始监听消息
在 .env 中配置：
WA_SELF_CHAT_MODE=true # 自对话模式（给自己发消息，Agent 自动回复）
# 或
WA_SELF_CHAT_MODE=false # 接收消息模式（回复他人消息）| 命令 | 说明 |
|---|---|
/help |
显示帮助信息 |
/new |
新建会话 |
/clear |
清空当前会话 |
/context |
查看上下文信息 |
WhatsApp 手机端 → neonize (WebSocket 协议) → whatsapp_gateway.py
↓
NanoAgent ReAct 推理
↓
回复消息 → neonize → WhatsApp 手机端
- 每个 WhatsApp 用户/聊天自动关联一个独立的 NanoAgent 会话
- 支持自动上下文压缩，长对话无压力
- 支持自对话模式（给自己发消息即可触发 Agent 回复）
在 tools/ 目录下创建文件夹，每个工具包含 main.py：
from langchain_core.tools import Tool
def hello_world(query: str) -> str:
"""问候工具"""
return f"你好，{query}！"
def register_tools() -> list[Tool]:
return [
Tool(
name="HelloWorld",
func=hello_world,
description="用于打招呼的工具"
)
]- LangChain - LLM 框架
- DeepSeek - 大语言模型
- neonize - WhatsApp 协议级客户端（Go 底层 whatsmeow）
- tiktoken - Token 估算
- Python 3.10+ - 运行环境
- ReAct 模式：理解 Thought-Action-Observation 循环
- Session 管理：多会话持久化和切换
- 上下文压缩：长对话场景下的上下文管理策略
- 工具系统：动态加载和调用工具
- 资源追踪：监控和优化 LLM 调用成本
- WhatsApp 集成：neonize 协议级客户端实现移动端通信
MIT License - 欢迎学习和改进！