neo-agent 🚀

一个轻量级、教学友好的 AI Agent 框架。从零开始构建，帮助理解 Agent 的底层工作原理。

✨ 特性

• 🎯 轻量级: 核心依赖仅 openai + pydantic + python-dotenv
• 🔌 多提供商: 支持 OpenAI / ModelScope / 智谱 / DeepSeek / Ollama / VLLM
• 🧠 四种 Agent 范式: SimpleAgent / ReActAgent / ReflectionAgent / PlanAndSolveAgent
• 🛠️ 万物皆工具: 统一工具抽象，内置计算器和多源搜索工具
• 📖 教学友好: 代码清晰注释，渐进式学习路径
• 🔍 自动检测: 智能推断 LLM 提供商，零配置即可运行

📦 安装

# 从 PyPI 安装（推荐）
pip install neo-agent-kit

# 带搜索工具支持
pip install "neo-agent-kit[search]"

# 从 GitHub 安装最新开发版
pip install git+https://github.com/user-hw/neo-agent.git

# 带搜索工具支持
pip install "neo-agent-kit[search] @ git+https://github.com/user-hw/neo-agent.git"

# 安装指定版本（基于 Git tag）
pip install "neo-agent-kit @ git+https://github.com/user-hw/neo-agent.git@v0.1.1"

建议后续每次发布都保持：

1. 更新 pyproject.toml / setup.py / neo_agent.__version__
2. 提交代码
3. 打 tag，例如 v0.1.2
4. 推送分支和 tag

🚀 快速开始

1. 配置环境变量

创建 .env 文件:

# OpenAI (默认)
OPENAI_API_KEY="sk-your-api-key"

# 或其他提供商
# MODELSCOPE_API_KEY="your-key"
# ZHIPU_API_KEY="your-key"
# DEEPSEEK_API_KEY="your-key"

# 本地模型
# LLM_BASE_URL="http://localhost:11434/v1"  # Ollama
# LLM_BASE_URL="http://localhost:8000/v1"   # VLLM

2. 基础对话

from dotenv import load_dotenv
from neo_agent import NeoAgentLLM, SimpleAgent

load_dotenv()

llm = NeoAgentLLM()  # 自动检测 provider
agent = SimpleAgent(name="AI助手", llm=llm, system_prompt="你是一个有用的AI助手")

response = agent.run("你好！请介绍一下自己")
print(response)

3. 命令行使用

安装完成后可以直接运行：

neo-agent ask "你好，请用一句话介绍一下你自己"

# 或者
python -m neo_agent ask "帮我总结一下 ReAct Agent 是什么"

4. ReAct Agent（工具调用）

from neo_agent import NeoAgentLLM, ReActAgent, ToolRegistry
from neo_agent.tools.builtin import CalculatorTool

llm = NeoAgentLLM()
registry = ToolRegistry()
registry.register_tool(CalculatorTool())

agent = ReActAgent(name="计算助手", llm=llm, tool_registry=registry)
result = agent.run("计算 (15 + 7) * 3 的结果")
print(result)

5. ReflectionAgent（反思优化）

from neo_agent import NeoAgentLLM, ReflectionAgent

llm = NeoAgentLLM()
agent = ReflectionAgent(name="写作助手", llm=llm)

result = agent.run("写一篇关于人工智能发展历程的简短文章")
print(result)

🏗️ 架构

neo_agent/
├── core/                    # 核心层
│   ├── agent.py            # Agent 抽象基类
│   ├── llm.py              # NeoAgentLLM 统一接口
│   ├── message.py          # 消息系统
│   ├── config.py           # 配置管理
│   └── exceptions.py       # 异常体系
├── agents/                  # Agent 实现层
│   ├── simple_agent.py     # SimpleAgent
│   ├── react_agent.py      # ReActAgent
│   ├── reflection_agent.py # ReflectionAgent
│   └── plan_solve_agent.py # PlanAndSolveAgent
└── tools/                   # 工具系统层
    ├── base.py             # 工具基类
    ├── registry.py         # 工具注册机制
    ├── chain.py            # 工具链管理
    ├── async_executor.py   # 异步执行器
    └── builtin/            # 内置工具
        ├── calculator.py   # 计算工具
        └── search.py       # 搜索工具

📄 License

MIT