🚀 nanoAgent：用100行Python代码理解AI Agent的本质
"想搞懂 AI Agent 的运行原理，面对那些动辄数万行代码的庞大框架，容易迷失在复杂的封装里。nanoAgent 用最原始的方式还原了 Agent 的核心逻辑——整个项目仅仅约 100 行 Python 代码，却完整实现了基于 OpenAI 函数调用的智能体循环。"
一、为什么需要 nanoAgent？
1.1 当前AI Agent开发的痛点
在2025-2026年，AI Agent技术呈现爆发式增长。从 LangGraph 到 CrewAI，从 OpenAI Agents SDK 到 AutoGPT，各种框架层出不穷。但对于初学者来说，这些框架往往存在以下问题：
- 封装过度：底层逻辑被层层包裹，难以看清Agent到底在做什么
- 学习曲线陡峭：需要同时掌握框架API、概念体系和最佳实践
- 调试困难：出现问题时，难以定位是逻辑错误还是框架bug
1.2 nanoAgent的设计哲学
nanoAgent 是由开发者 sanbuphy开源的一个极简Agent实现项目 。它的核心理念是：
"用最少的代码，展示Agent最核心的逻辑"
- ✅ 仅约 100行Python代码
- ✅ 零框架依赖，直接使用OpenAI API
- ✅ 完整实现 Agent Loop（智能体循环）
- ✅ 支持 Function Calling（函数调用）
- ✅ 包含基础系统操作工具（文件读写、命令执行）
正如技术博主评价："这是理解 Agent 本质的最佳入门项目" 。
二、AI Agent的核心概念科普
在深入代码之前，我们需要理解AI Agent的三个核心组成部分：
2.1 什么是AI Agent？
AI Agent（人工智能代理）是一个能够自主感知环境、做出决策并执行动作的系统。与传统的一次性问答不同，Agent具备以下特征：
| 特征 | 说明 |
|---|---|
| 自主性 | 能在没有人类干预的情况下持续运行 |
| 工具使用 | 可以调用外部工具（如搜索、计算、文件操作） |
| 记忆能力 | 能记住之前的交互历史 |
| 目标导向 | 围绕特定目标进行多步骤推理 |
2.2 Agent的核心架构
一个最小化的AI Agent包含四个关键组件 ：
2.3 什么是Function Calling？
Function Calling（函数调用） 是现代LLM（如GPT-4、Claude）的核心能力。它允许模型：
- 识别何时需要调用外部工具
- 生成符合预定义格式的调用参数
- 暂停文本生成，等待工具执行结果
- 继续基于工具返回结果进行推理
这就像是给LLM装上了"手"，让它从"只会说话"变成"能动手做事"。
三、nanoAgent代码深度解析
3.1 项目结构概览
nanoAgent的代码结构极其简洁：
nanoAgent/
├── agent.py # 核心Agent类（约100行）
├── tools.py # 工具定义（文件读写、命令执行）
├── config.py # 配置管理
└── main.py # 入口程序
3.2 核心Agent类实现
nanoAgent的核心是一个简单的循环结构，完美诠释了 "Agent = LLM + 工具 + 循环" 的公式 ：
class Agent:
def __init__(self, tools):
self.client = OpenAI() # 初始化OpenAI客户端
self.tools = tools # 注册可用工具
self.messages = [] # 对话历史（短期记忆）
def run(self, goal, max_turns=10):
"""Agent主循环"""
self.messages.append({"role": "user", "content": goal})
for i in range(max_turns):
# 1. 调用LLM进行推理
response = self.client.chat.completions.create(
model="gpt-4",
messages=self.messages,
tools=self.tools.schemas # 告诉模型有哪些工具可用
)
message = response.choices[0].message
# 2. 检查是否需要调用工具
if message.tool_calls:
# 执行工具并获取结果
tool_results = self.execute_tools(message.tool_calls)
# 将结果加入对话历史
self.messages.extend(tool_results)
else:
# 3. 直接输出结果，任务完成
return message.content
return "达到最大轮次限制"
3.3 工具系统的实现
nanoAgent定义了几个基础但实用的工具 ：
| 工具名称 | 功能 | 使用场景 |
|---|---|---|
execute | 执行系统命令（如ls、pwd） | 探索环境、运行程序 |
read_file | 读取文件内容 | 查看代码、配置文件 |
write_file | 写入文件内容 | 创建代码、保存结果 |
工具的定义采用OpenAI标准的JSON Schema格式：
tools = [
{
"type": "function",
"function": {
"name": "execute",
"description": "执行系统命令",
"parameters": {
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "要执行的命令"
}
},
"required": ["command"]
}
}
},
# ... 其他工具定义
]
3.4 Agent Loop的运行流程
让我们通过一个具体例子，看看nanoAgent是如何工作的：
用户输入： "请帮我查看当前目录下有哪些文件，然后创建一个名为hello.py的文件，写入print('Hello, nanoAgent!')"
运行过程：
第1轮：
LLM思考：用户想看文件列表，我应该调用execute工具执行"ls"
→ 调用工具：execute("ls")
→ 工具返回：["agent.py", "tools.py", "config.py", "main.py"]
→ 观察结果加入历史
第2轮：
LLM思考：现在我需要创建hello.py文件，使用write_file工具
→ 调用工具：write_file("hello.py", "print('Hello, nanoAgent!')")
→ 工具返回：文件写入成功
→ 观察结果加入历史
第3轮：
LLM思考：任务已完成，不需要再调用工具，直接回复用户
→ 最终输出：已完成！我查看了当前目录包含agent.py等文件，并创建了hello.py。
这个循环展示了Agent的自主决策能力：模型自己决定何时停止思考、何时调用工具、何时给出最终答案。
四、动手实践：从零运行nanoAgent
4.1 环境准备
# 克隆项目
git clone https://github.com/sanbuphy/nanoAgent.git
cd nanoAgent
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 安装依赖
pip install openai python-dotenv
4.2 配置API密钥
创建 .env 文件：
OPENAI_API_KEY=your_api_key_here
4.3 运行示例
from agent import Agent
from tools import Tools
# 初始化工具和Agent
tools = Tools()
agent = Agent(tools)
# 运行Agent
result = agent.run("创建一个简单的待办事项应用，包含添加和查看功能")
print(result)
4.4 实际应用场景
nanoAgent虽然简单，但能完成许多实用任务：
场景1：代码生成与调试
输入：帮我写一个Python脚本，计算斐波那契数列前20项
→ Agent会：创建文件 → 写入代码 → 执行验证 → 返回结果
场景2：文件管理与分析
输入：分析当前目录下所有.py文件的行数，并生成统计报告
→ Agent会：列出文件 → 逐个读取 → 统计行数 → 生成报告文件
场景3：自动化工作流
输入：检查系统磁盘使用情况，如果超过80%则记录到warning.log
→ Agent会：执行df命令 → 分析输出 → 条件判断 → 写入日志
五、总结与思考
7.1 nanoAgent的价值
nanoAgent的最大价值不在于它的功能强大，而在于它的教育意义：
- 去神秘化Agent：证明Agent并不复杂，核心是"循环+工具调用"
- 建立直觉：通过阅读100行代码，建立对Agent工作机制的直观理解
- 降低门槛：让初学者敢于动手修改和实验
正如Tessl.io播客中Yaniv Aknin所说："在100行代码中，你能得到一个真正工作的Agent。如果你让它做一个待办应用，它真的能做出一个能点击、能用的应用" 。
7.2 一些建议
- 先读源码，再跑程序：花30分钟逐行阅读agent.py，理解每一行的作用
- 动手修改：尝试添加新工具（如网络搜索、数据库查询）
- 对比学习：阅读后用LangGraph重写同样功能，体会框架的价值
- 关注本质：无论框架如何变化，Agent的核心始终是"观察-思考-行动"的循环
7.3 相关资源
- 📁 项目地址：github.com/sanbuphy/na…
- 📚 OpenAI Function Calling文档：platform.openai.com/docs/guides…
- 🎓 Anthropic Agent构建指南：docs.anthropic.com/en/docs/bui…
写在最后
在AI技术快速迭代的今天，框架和工具层出不穷，但底层原理往往比上层封装更持久。nanoAgent用最朴素的方式告诉我们：Agent的本质，就是给大模型装上"手脚"和"记忆"，让它能在循环中自主解决问题。
无论你是AI开发新手，还是经验丰富的工程师，花一小时深入研究这100行代码，都将帮助你建立对Agent技术的扎实理解。毕竟，正如那句老话所说： "如果你无法用最简单的代码实现它，说明你还没有真正理解它。"
本文基于 nanoAgent 开源项目及相关技术资料整理，部分技术细节参考了GitHubDaily、Tessl.io等来源 。如有疏漏，欢迎指正交流。
关注公众号【dev派】 ，回复 "agent" 获取完整源码和配置文件模板！
