Skip to content

README.md

Latest commit

 

History

History
423 lines (324 loc) · 14.8 KB

README.md

File metadata and controls

423 lines (324 loc) · 14.8 KB
Raw

Python License Steps PRs Welcome

🤖 Agent Builder

从零手搓 AI 智能体 · 6 步递进式教程

📖 English Version

不调包、不套壳、不抄 Demo。
带你亲手写出一个能思考、会调用工具、有记忆的命令行 AI Agent。

📖 目录

这是什么？

Agent Builder 是一个面向 AI 新手的递进式教程。5 个 Python 脚本，每个脚本聚焦一个核心概念，层层递进，最终组装出一个完整可用的命令行智能体。

🎯 目标读者：有一点编程基础、想理解 Agent 底层原理的开发者

⏱️ 预计耗时：2-3 小时跑完 5 步

💰 花费：调用 API 约 0.1-0.5 元（推荐使用 DeepSeek）

智能体的四块拼图

                         ┌──────────────────┐
                         │   🧠 大脑 (LLM)   │
                         │  API 调用 + 提示词 │
                         └────────┬─────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
         │                        │                        │
         ▼                        ▼                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  🔧 手脚 (工具)  │    │  💾 记忆 (上下文) │    │  🔄 引擎 (ReAct) │
│  Function Call  │    │  Messages 列表   │    │  思考→行动→观察   │
└────────┬────────┘    └────────┬────────┘    └────────┬────────┘
         │                      │                      │
         └──────────────────────┼──────────────────────┘
                                │
                     ┌──────────┴──────────┐
                     │    🤖 完整 Agent     │
                     │  可对话、会推理、能干活  │
                     └─────────────────────┘
拼图 对应概念 一句话解释
🧠 大脑 LLM 调用 发 HTTP 请求给大模型，拿到回复
🔧 手脚 工具系统 定义函数 + 描述 → LLM 决定什么时候调用
💾 记忆 对话历史 messages 列表不断追加，token 超了就裁
🔄 引擎 ReAct 循环 Thought → Action → Observation → 再 Thought

五步路线

# 文件 学什么 新增概念
1 step01_hello_llm.py 调用 LLM API system/user/assistant 角色、temperature
2 step02_tool_system.py Function Calling 工具定义 JSON Schema、工具注册与执行
3 step03_memory.py 对话记忆管理 messages 列表增长、token 预算、滑动窗口
4 step04_react_loop.py ReAct 思考循环 Thought→Action→Observation 循环
5 step05_full_agent.py 组装完整 Agent 全部组件 + 交互式 CLI
6 step06_plugin_system.py 插件系统 + 外部 API 热加载插件 + 万能 HTTP 工具

每步只引入 一个新概念，学完一步、跑通一步、再下一步。

快速开始

1. 克隆项目

git clone https://github.com/yourusername/agent-builder.git
cd agent-builder

2. 安装依赖

pip install -r requirements.txt

💡 遇到报错？查看 TROUBLESHOOTING.md

3. 配置 API Key

推荐使用 DeepSeek（国内直连、便宜）：

# Linux / macOS
export OPENAI_API_KEY="sk-你的DeepSeek-Key"
export OPENAI_BASE_URL="https://api.deepseek.com/v1"

# Windows PowerShell
$env:OPENAI_API_KEY="sk-你的DeepSeek-Key"
$env:OPENAI_BASE_URL="https://api.deepseek.com/v1"

💡 也支持 OpenAI 官方、通义千问、智谱等任意 OpenAI 兼容接口。 只要设置 OPENAI_BASE_URL 指向对应地址即可。

4. 按顺序跑

python step01_hello_llm.py     # ① 第一次跟 LLM 对话
python step02_tool_system.py   # ② 让 LLM 调用计算器
python step03_memory.py        # ③ 多轮对话不"失忆"
python step04_react_loop.py    # ④ 多步推理
python step05_full_agent.py    # ⑤ 跟你的智能体"小智"聊天！

项目结构

agent-builder/
├── README.md                   ← 你正在看的
├── ARCHITECTURE.md             ← 深度架构讲解
├── CHEATSHEET.md               ← 概念速查表
├── LICENSE                     ← MIT 开源协议
├── requirements.txt            ← Python 依赖
├── .gitignore
│
├── step01_hello_llm.py         ← Step 1: LLM 调用
├── step02_tool_system.py       ← Step 2: 工具系统
├── step03_memory.py            ← Step 3: 记忆管理
├── step04_react_loop.py        ← Step 4: ReAct 循环
├── step05_full_agent.py        ← Step 5: 完整 Agent
├── step06_plugin_system.py     ← Step 6: 插件系统 + 外部 API
│
├── tools/                      ← 工具模块
│   ├── __init__.py             ← 工具注册中心
│   ├── calculator.py           ← 计算器工具
│   └── datetime_tools.py       ← 日期时间工具
│
├── plugins/                    ← 插件目录（丢 .py 文件自动加载）
│   ├── plugin_loader.py        ← 插件自动发现器
│   └── example_weather.py      ← 天气查询示例插件
│
├── exercises/                  ← 练习目录
│   ├── README.md
│   ├── step01_exercise.py
│   ├── step02_exercise.py
│   ├── step03_exercise.py
│   ├── step04_exercise.py
│   ├── step05_exercise.py
│   └── step06_exercise.py
│
└── outputs/                    ← 运行输出示例
    ├── step01_output.txt
    ├── step02_output.txt
    ├── step03_output.txt
    ├── step04_output.txt
    └── step05_output.txt

每一步详解

Step 1 · LLM 调用

核心问题：怎么让程序"说话"？

答案：构建 messages 列表 → 通过 HTTP 发给 OpenAI 兼容 API → 拿到 response.choices[0].message.content

关键代码：

from openai import OpenAI
client = OpenAI(api_key="sk-xxx", base_url="https://api.deepseek.com/v1")

response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "你是一个助手"},
        {"role": "user", "content": "你好"}
    ]
)
print(response.choices[0].message.content)

三种角色：

角色 谁说的 用途
system 开发者 设定 AI 的身份、行为规则、输出格式
user 用户 提问、指令
assistant AI 回复（多轮对话时需保留）

Step 2 · 工具系统

核心问题：LLM 不会算数、不知道时间——怎么让它"用"计算器？

答案：Function Calling。告诉 LLM "你有这些工具可用"，它自己决定要不要调、调哪个、传什么参数。真正执行工具的是你的 Python 代码。

关键流程：

用户："3的平方根是多少？"
    ↓
LLM 收到 tools 定义 → 判断需要 calculate 工具
    ↓
LLM 返回：{ name: "calculate", arguments: {expression: "sqrt(3)"} }
    ↓
你的代码：eval("sqrt(3)") → 1.732...
    ↓
把结果喂回 LLM → LLM："3的平方根约等于 1.732"

工具定义格式（JSON Schema）：

{
    "type": "function",
    "function": {
        "name": "calculate",
        "description": "执行数学运算...",       # ← 描述质量决定 LLM 调用准确率
        "parameters": {
            "type": "object",
            "properties": {
                "expression": {"type": "string", "description": "..."}
            },
            "required": ["expression"]
        }
    }
}

Step 3 · 记忆系统

核心问题：Agent 聊了三句就忘了第一句——怎么让它记住？

答案：messages 列表就是记忆。每次对话把历史消息全部带上发给 LLM。但上下文窗口有限（通常 4K-128K tokens），超了就得裁剪。

messages = [
    {"role": "system", "content": "你是助手"},
    {"role": "user", "content": "我叫小明"},          # ← 第 1 轮
    {"role": "assistant", "content": "你好小明"},
    {"role": "user", "content": "我喜欢蓝色"},         # ← 第 2 轮
    {"role": "assistant", "content": "蓝色很棒"},
    {"role": "user", "content": "我叫什么？我喜欢什么颜色？"}  # ← 第 3 轮，LLM 知道答案
]

Token 预算管理：

  • 计算当前消息总 token 数
  • 超过限制 → 从最早的非 system 消息开始删除
  • 保留 system prompt（Agent 的"人格"不能丢）

Step 4 · ReAct 循环

核心问题：复杂任务需要多步操作——怎么让 Agent"反复思考"？

答案：ReAct = Reasoning + Acting。一个 while 循环，直到 LLM 说"我完成了"。

用户："帮我查天气并推荐穿搭"
    ↓
┌──────────────────────────────┐
│ 🔄 循环 #1                    │
│   Thought: 需要先知道天气     │
│   Action: get_weather("北京") │
│   Observation: 气温 5°C       │
├──────────────────────────────┤
│ 🔄 循环 #2                    │
│   Thought: 5度很冷            │
│   Action: (直接回复)          │
│   → "北京今天 5°C，建议穿羽绒服"│
└──────────────────────────────┘

关键代码：

while loop < max_loops:
    response = client.chat.completions.create(
        messages=messages, tools=tools, tool_choice="auto"
    )
    if response.choices[0].finish_reason == "stop":
        return response.choices[0].message.content  # ← 完成
    # 否则执行工具，追加结果到 messages，继续循环

Step 5 · 完整 Agent

把前面四步全部组装，加上交互式命令行界面，就是你的第一个智能体——小智。

$ python step05_full_agent.py
============================================================
  🤖 小智智能体 v1.0
  模型：gpt-3.5-turbo | 工具：计算器、日期时间
  输入 exit 退出 | clear 清除记忆
============================================================

你：现在几点了？帮我算一下 2 的 10 次方
  🔧 调用工具：get_current_time({})
     → {"datetime": "2026-07-19 09:45:00", ...}
  🔧 调用工具：calculate({"expression": "2 ** 10"})
     → {"success": true, "result": 1024}

小智：现在是 2026 年 7 月 19 日 09:45。2 的 10 次方等于 1024。

Step 6 · 插件系统 + 外部 API

核心问题：每加一个工具都要改代码 → 能不能像手机装 App 一样"丢文件即用"？

答案：用 importlib 动态扫描 plugins/ 目录，自动发现和注册工具。再加一个万能 HTTP 工具，Agent 就能调任何 REST API。

关键代码：

# 插件热加载：遍历 plugins/ 下所有 .py 文件，动态导入
from plugins.plugin_loader import load_plugins
plugin_tools, plugin_executors = load_plugins()

# 万能 HTTP 工具：一个工具搞定所有 API 调用
def call_api(url: str, method: str = "GET") -> str:
    # 用 urllib 发请求，返回 JSON
    ...

插件约定（让 Agent 能识别你的文件）：

# 你的插件文件（如 plugins/my_tool.py）只需要两样东西：
TOOLS = [{"type": "function", "function": {...}}]  # 工具定义
def execute(**kwargs) -> str:                       # 执行函数
    return json.dumps({"result": ...})

常见问题

Q: 为什么不用 LangChain / LlamaIndex？

因为它们的核心逻辑和本教程一模一样。先理解底层，再用框架——你才能知道框架帮你省了什么、又坑了你什么。

Q: API 调用要钱吗？

要，但很少。DeepSeek 的价格大约 1 元 / 100 万 token，跑完 5 步总共不到 1 毛钱。OpenAI 稍贵，约几毛。

Q: 能用本地模型吗？

可以。用 Ollama 启动本地模型，设 OPENAI_BASE_URL="http://localhost:11434/v1" 即可。但 Function Calling 需要模型支持。

Q: 为什么不用 requests 直接发 HTTP？

可以，但 openai 库处理了流式响应、重试、错误处理等细节。理解了原理后可以用 requests 重写一遍练手。

下一步学什么

🚀 进阶项目：Agent Builder Pro —— 学完基础版后，在 Pro 版中继续学习 Shell 执行器、流式输出、RAG 知识库、多 Agent 协作、持久化记忆和 Web 界面。

学完这个项目，你已经掌握了 Agent 的核心原理。接下来可以：

方向 学什么 难度
🔧 加工具 给 Agent 加：天气查询、网页搜索、文件操作、SQL 查询 ⭐
🧠 换模型 试试 Claude、Gemini、Qwen，对比 Function Calling 能力 ⭐
💬 加界面 用 Gradio / Streamlit 做个 Web UI ⭐⭐
🔗 多 Agent 多个 Agent 协作：一个查资料、一个写报告、一个审核 ⭐⭐⭐
📦 做成 Skill 把你的 Agent 打包成 WorkBuddy Skill ⭐⭐

License

MIT © 2026

如果这个项目对你有帮助，请给个 ⭐ Star