从零搭建你的第一个 AI Agent：2026 年最该学会的技能，小白也能 30 分钟上手

摘要

小白建议：2026 年被称为「Agent 元年」，AI Agent（智能体）已经从论文概念变成了开发者人人可上手的生产力工具。本文面向零基础读者，用大白话讲清楚 AI Agent 到底是什么、核心架构怎么运作，然后带你用 Python 从零写出一个真正能用的智能体——它能联网搜索、记住你的偏好、自动完成多步任务。全文包含完整可运行代码、框架对比选型、常见坑点排查和学习路线图，读完即可动手实战。

关键词

AI Agent；智能体；LangChain；ReAct；工具调用；RAG；Python；大模型应用开发；零基础入门；2026 技术趋势

---

目录

• 一、AI Agent 是什么？用最白的话讲清楚
  • 1.1 一个比喻：Agent 就是「有手有脚的 ChatGPT」
  • 1.2 Agent 和普通 ChatBot 的本质区别
  • 1.3 2026 年为什么人人都在聊 Agent
• 二、Agent 的核心架构：四个部件，一个都不少
  • 2.1 大脑：大语言模型（LLM）
  • 2.2 记忆：短期记忆与长期记忆
  • 2.3 工具：让 Agent 拥有「手脚」
  • 2.4 规划：ReAct 范式详解
• 三、动手实战：30 分钟写出你的第一个 Agent
  • 3.1 环境准备（5 分钟）
    • 3.1.1 安装 Python 与依赖包
    • 3.1.2 获取 API Key 与项目结构
  • 3.2 第一版：最简对话 Agent（10 分钟）
  • 3.3 第二版：给 Agent 装上「工具」（10 分钟）
    • 3.3.1 第一步：定义工具函数
    • 3.3.2 第二步：注册工具到大模型
    • 3.3.3 第三步：实现 ReAct 主循环
  • 3.4 第三版：加上记忆，让它记住你（5 分钟）
• 四、框架选型：LangChain vs LangGraph vs 手写，怎么选？
  • 4.1 三种方案对比表
  • 4.2 小白该选哪个
• 五、Agent 开发的 6 个常见坑（踩过才知道）
  • 5.1 坑一：模型幻觉导致工具调用失败
  • 5.2 坑二：上下文窗口爆炸
  • 5.3 坑三：无限循环停不下来
  • 5.4 坑四：API 费用失控
  • 5.5 坑五：工具描述写不好，Agent 不会用
  • 5.6 坑六：本地模型效果差
• 六、学习路线图：从今天到能上岗
  • 6.1 四阶段成长路线
    • 6.1.1 阶段一：入门（1-2周）
    • 6.1.2 阶段二：进阶（2-4周）
    • 6.1.3 阶段三：实战（1-2月）
    • 6.1.4 阶段四：深入（持续）
  • 6.2 推荐学习资源
• 七、写在最后：Agent 不是未来，是现在

---

一、AI Agent 是什么？用最白的话讲清楚

1.1 一个比喻：Agent 就是「有手有脚的 ChatGPT」

你平时用 ChatGPT、文心一言、Kimi，它们只能跟你聊天——你问它答，它不会主动去做任何事。

AI Agent 不一样。 它不仅能聊天，还能：

• 🔍 自己上网搜资料（不用你手动复制粘贴给它）
• 📁 帮你读写文件（比如自动整理你的文档）
• 🧮 调用计算器、查数据库（不用你算好再告诉它）
• 🔄 把一个大任务拆成多步，一步步自己完成（不用你一步步指挥）

一句话总结：ChatBot 是你的「顾问」，Agent 是你的「员工」。

1.2 Agent 和普通 ChatBot 的本质区别

对比维度	普通 ChatBot	AI Agent
交互模式	一问一答	给目标，自己规划执行
工具使用	不能调用外部工具	能搜索、读写文件、调 API
记忆能力	仅当前对话	短期+长期记忆，跨会话记住你
自主性	被动响应	主动规划、自我纠错
典型场景	“帮我写个请假条”	“帮我查最近一周的机票，选最便宜的，帮我订”
技术复杂度	调 API 即可	需要编排工具、记忆、规划

1.3 2026 年为什么人人都在聊 Agent

三个原因：

1. 大模型够强了。 GPT-4o、Claude 3.5、DeepSeek-V3 的推理能力已经足够支撑复杂的多步规划，这是 Agent 能用的前提。两年前的模型做不到。
2. 开源生态爆发。 GitHub 上 Agent 相关项目 Star 数疯狂增长——Hello-Agants 教程 13.2K Star、可视化 Agent 平台 sim 24.6K Star、开源编码代理 OpenCode 43.6K Star。生态成熟意味着你不需要从零造轮子。
3. 企业真金白银在招人。 搜索招聘平台，「AI Agent 开发」「大模型应用工程师」岗位需求在 2025 年增长了 300%+，薪资普遍 20K-50K。这不是泡沫，是实打实的技能需求。

---

二、Agent 的核心架构：四个部件，一个都不少

任何一个 AI Agent，不管多复杂，核心就四个部件。记住这四个，你就理解了所有 Agent 的本质。

2.1 大脑：大语言模型（LLM）

这是 Agent 的核心引擎。所有「思考」「理解」「决策」都靠它。

它的角色：

• 理解用户的自然语言指令
• 决定下一步该调用哪个工具
• 把工具返回的结果整合成最终回答

选型建议（2026 年版）：

模型	优势	劣势	适合场景
GPT-4o	推理最强，工具调用稳定	贵，需翻墙	生产环境、复杂任务
Claude 3.5 Sonnet	长文本理解强，代码能力好	国内访问不便	代码类 Agent
DeepSeek-V3	便宜，中文好，开源	复杂规划略弱	国内项目、成本敏感
Qwen2.5 (通义千问)	免费，中文强，本地可部署	推理上限一般	本地部署、学习练手

小白建议： 学习阶段用 DeepSeek API（便宜到离谱，百万 token 才 1 块钱）或 Qwen 免费额度，别一上来就烧 GPT-4o。

2.2 记忆：短期记忆与长期记忆

人没有记忆什么都干不了，Agent 也一样。

短期记忆（对话上下文）：

• 就是当前对话的聊天记录
• 比如你前面说了"我喜欢吃辣"，Agent 后面推荐菜就会记住
• 实现：就是一个列表，把每轮对话追加进去

长期记忆（跨会话记忆）：

• 窗关了再打开，Agent 还记得你是谁
• 比如它记住你的名字、职业、偏好
• 实现：用向量数据库存储，每次对话前先检索相关记忆

通俗理解：

短期记忆 = 你脑子里的"当前对话"     → 用 Python 列表存
长期记忆 = 你的日记本/笔记本          → 用向量数据库存（如 ChromaDB）

2.3 工具：让 Agent 拥有「手脚」

没有工具的 Agent 就是个嘴炮——只会说不会做。工具是 Agent 与真实世界交互的接口。

常见工具类型：

工具类型	作用	示例
搜索工具	联网查最新信息	DuckDuckGo API、Tavily Search
计算工具	精确数学计算	Python eval()、Wolfram Alpha
文件工具	读写本地文件	读写 txt/json/csv
API 工具	调用外部服务	天气 API、股票 API、发邮件
代码执行	运行代码	Python REPL、沙箱

工具的本质就是一个 Python 函数 + 一段描述：

# 这就是一个工具——一个普通函数
def get_weather(city: str) -> str:
    """查询指定城市的当前天气。
    
    Args:
        city: 城市名称，如"北京"、"上海"
    
    Returns:
        天气描述字符串
    """
    # 实际项目中这里调天气API
    return f"{city}今天晴，25°C"

# 关键点：函数的 docstring 就是给大模型看的"说明书"
# 大模型通过读 docstring 来决定"什么时候该用这个工具"

核心认知： 大模型不会直接执行代码，它只会输出"我觉得该调用 get_weather 工具，参数是 city=‘北京’"。你的程序负责真正执行这个函数，然后把结果喂回给大模型。

2.4 规划：ReAct 范式详解

ReAct = Reasoning（推理）+ Acting（行动）。这是目前最主流的 Agent 规划范式，几乎所有框架都在用。

ReAct 的工作流程：

用户提问 → Agent 思考(Thought) → 选择行动(Action) → 执行得到观察(Observation) → 再思考 → ... → 最终回答

用一个例子讲透：

用户问：“今天北京天气怎么样？适合穿什么？”

Agent 的内部过程：

第1轮：
  Thought: 用户想知道北京天气和穿衣建议。我需要先查天气。
  Action: 调用 get_weather(city="北京")
  Observation: 北京今天晴，25°C

第2轮：
  Thought: 北京25°C晴天，比较舒适。应该建议穿薄外套或长袖。
  Action: 不需要再调用工具，直接回答
  Answer: 北京今天晴，25°C，比较舒适。建议穿薄外套或长袖衫，早晚可能稍凉，可以带一件薄外套备用。

ReAct 的精妙之处： Agent 不是一次性给出答案，而是「想一步、做一步、看结果、再想下一步」。这就像人类解决问题的方式——先想想需要什么信息，去查，查到了再继续推理。

---

三、动手实战：30 分钟写出你的第一个 Agent

声明： 以下代码全部可运行。用 DeepSeek API（最便宜），你也可以替换成 OpenAI/Qwen。

3.1 环境准备（5 分钟）

3.1.1 安装 Python 与依赖包

第一步：安装 Python

去 python.org 下载 Python 3.10+，安装时勾选 “Add to PATH”。

第二步：安装依赖包

打开终端（Windows 用 PowerShell，Mac 用 Terminal），执行：

pip install openai python-dotenv

就这两个包，不需要装一堆框架。我们先从最原始的方式开始，理解原理。

3.1.2 获取 API Key 与项目结构

第三步：获取 API Key

去 DeepSeek 开放平台 注册，创建 API Key。新用户有免费额度。

第四步：创建项目文件

my-first-agent/
├── .env          # 存放 API Key
├── agent.py      # 主程序

.env 文件内容：

DEEPSEEK_API_KEY=sk-你的key填这里

3.2 第一版：最简对话 Agent（10 分钟）

先写一个能对话的 Agent，不加工具。这一步的目的是跑通大模型调用。

# agent.py
import os
import json
from dotenv import load_dotenv
from openai import OpenAI

# 1. 加载环境变量
load_dotenv()

# 2. 创建大模型客户端（DeepSeek 兼容 OpenAI 接口）
client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"  # 换成 OpenAI 就删掉这行
)

# 3. Agent 的"大脑"——系统提示词
SYSTEM_PROMPT = """你是一个智能助手。你可以回答问题、提供建议。
请用简洁、友好的语气回答用户。"""

# 4. 短期记忆——对话历史
messages = [
    {"role": "system", "content": SYSTEM_PROMPT}
]

# 5. 对话循环
def chat():
    print("🤖 Agent 已启动，输入 '退出' 结束对话\n")
    
    while True:
        user_input = input("你: ").strip()
        if user_input.lower() in ["退出", "exit", "quit"]:
            print("👋 再见！")
            break
        
        # 把用户消息加入记忆
        messages.append({"role": "user", "content": user_input})
        
        # 调用大模型
        response = client.chat.completions.create(
            model="deepseek-chat",
            messages=messages,
            temperature=0.7  # 0=最稳定，1=最有创意
        )
        
        # 获取回复
        reply = response.choices[0].message.content
        
        # 把回复也加入记忆（这样它才记得之前说过什么）
        messages.append({"role": "assistant", "content": reply})
        
        print(f"🤖 Agent: {reply}\n")

if __name__ == "__main__":
    chat()

运行：

python agent.py

效果：

🤖 Agent 已启动，输入 '退出' 结束对话

你: 你好，我叫小明
🤖 Agent: 你好小明！很高兴认识你，有什么可以帮你的吗？

你: 我刚才说我叫什么？
🤖 Agent: 你说你叫小明。记住啦！

看到它能记住你之前说的话了？这就是短期记忆在起作用——messages 列表把所有对话历史都存着，每次调用大模型都带上。

但问题来了： 现在它只会聊天，不能搜索、不能算数、不能做任何实际操作。下一步，我们给它装上工具。

3.3 第二版：给 Agent 装上「工具」（10 分钟）

这是最关键的一步——让 Agent 真正能"做事"。

3.3.1 第一步：定义工具函数

工具的本质就是普通 Python 函数，关键是函数的 docstring 要写清楚，因为大模型靠读 docstring 来决定什么时候用这个工具。

# agent.py（完整版）
import os
import json
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

# ============================================================
# 第一步：定义工具（就是普通 Python 函数）
# ============================================================

def get_weather(city: str) -> str:
    """查询指定城市的当前天气。
    
    Args:
        city: 城市名称，如"北京"、"上海"、"广州"
    
    Returns:
        天气描述字符串
    """
    # 实际项目中这里调用真实天气API
    # 这里用模拟数据演示
    weather_map = {
        "北京": "晴，25°C，北风3级",
        "上海": "多云，28°C，东南风2级",
        "广州": "阵雨，30°C，南风2级",
        "深圳": "晴转多云，29°C，东风3级"
    }
    return weather_map.get(city, f"暂无{city}的天气数据")

def calculate(expression: str) -> str:
    """计算一个数学表达式并返回结果。
    
    Args:
        expression: 数学表达式，如 "1+2*3"、"100/4"、"2**10"
    
    Returns:
        计算结果字符串
    """
    try:
        result = eval(expression)  # 演示用，生产环境别用eval
        return f"{expression} = {result}"
    except Exception as e:
        return f"计算失败：{e}"

3.3.2 第二步：注册工具到大模型

定义好函数后，需要用 JSON Schema 格式把工具注册给大模型，告诉它"有哪些工具可用、每个工具的参数是什么"。

# ============================================================
# 第二步：把工具注册成大模型认识的格式
# ============================================================

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称，如'北京'、'上海'"
                    }
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "计算一个数学表达式并返回结果",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "数学表达式，如 '1+2*3'、'100/4'"
                    }
                },
                "required": ["expression"]
            }
        }
    }
]

# 工具名到函数的映射表
TOOL_MAP = {
    "get_weather": get_weather,
    "calculate": calculate
}

3.3.3 第三步：实现 ReAct 主循环

这是 Agent 的核心——一个 while 循环，不断让大模型「思考→调用工具→看结果→再思考」，直到大模型认为可以给出最终答案。

# ============================================================
# 第三步：Agent 主循环（ReAct 范式的实现）
# ============================================================

SYSTEM_PROMPT = """你是一个智能助手，可以查询天气和进行数学计算。
当用户问到天气时，调用 get_weather 工具。
当用户需要计算时，调用 calculate 工具。
不要猜测答案，不确定时一定要调用工具查询。"""

messages = [{"role": "system", "content": SYSTEM_PROMPT}]

def chat():
    print("🤖 Agent 已启动（带工具版），输入 '退出' 结束对话\n")
    
    while True:
        user_input = input("你: ").strip()
        if user_input.lower() in ["退出", "exit", "quit"]:
            print("👋 再见！")
            break
        
        messages.append({"role": "user", "content": user_input})
        
        # Agent 循环：可能多轮工具调用
        while True:
            response = client.chat.completions.create(
                model="deepseek-chat",
                messages=messages,
                tools=TOOLS,
                temperature=0.3  # 用工具时温度低一些更稳定
            )
            
            msg = response.choices[0].message
            
            # 情况一：模型决定调用工具
            if msg.tool_calls:
                # 先把助手的工具调用请求加入记忆
                messages.append(msg)
                
                for tool_call in msg.tool_calls:
                    func_name = tool_call.function.name
                    func_args = json.loads(tool_call.function.arguments)
                    
                    print(f"  🔧 调用工具: {func_name}({func_args})")
                    
                    # 真正执行工具函数
                    func = TOOL_MAP[func_name]
                    result = func(**func_args)
                    
                    print(f"  📋 工具返回: {result}")
                    
                    # 把工具结果加入记忆
                    messages.append({
                        "role": "tool",
                        "tool_call_id": tool_call.id,
                        "content": str(result)
                    })
                
                # 继续循环，让模型根据工具结果继续思考
                continue
            
            # 情况二：模型决定直接回答（不再调用工具）
            else:
                reply = msg.content
                messages.append({"role": "assistant", "content": reply})
                print(f"🤖 Agent: {reply}\n")
                break  # 跳出工具循环，等待下一个用户输入

if __name__ == "__main__":
    chat()

运行后试试这些对话：

你: 北京今天天气怎么样？
  🔧 调用工具: get_weather({'city': '北京'})
  📋 工具返回: 晴，25°C，北风3级
🤖 Agent: 北京今天晴，气温25°C，北风3级，天气不错！

你: 那上海呢？再帮我算一下 25*4+100
  🔧 调用工具: get_weather({'city': '上海'})
  📋 工具返回: 多云，28°C，东南风2级
  🔧 调用工具: calculate({'expression': '25*4+100'})
  📋 工具返回: 25*4+100 = 200
🤖 Agent: 上海今天多云，28°C。另外 25*4+100 = 200。

关键理解： 看到了吗？Agent 自己决定"该调什么工具、传什么参数"，你的代码负责执行，结果再喂回去。这就是 Agent 的核心——大模型负责决策，你的代码负责执行。

3.4 第三版：加上记忆，让它记住你（5 分钟）

在前面的代码基础上，加一个简单的长期记忆功能——用 JSON 文件存储用户偏好。

在 agent.py 顶部添加：

import datetime

# ============================================================
# 长期记忆：用 JSON 文件存储用户信息
# ============================================================

MEMORY_FILE = "memory.json"

def load_memory():
    """加载长期记忆"""
    if os.path.exists(MEMORY_FILE):
        with open(MEMORY_FILE, "r", encoding="utf-8") as f:
            return json.load(f)
    return {"user_info": {}, "facts": []}

def save_memory(memory):
    """保存长期记忆"""
    with open(MEMORY_FILE, "w", encoding="utf-8") as f:
        json.dump(memory, f, ensure_ascii=False, indent=2)

def extract_and_save_info(user_input, memory):
    """简单提取用户信息存入记忆（实际项目中用大模型来提取）"""
    # 演示：检测"我叫xxx"的模式
    if "我叫" in user_input:
        name = user_input.split("我叫")[-1].strip().rstrip("。，！")
        memory["user_info"]["name"] = name
        save_memory(memory)
    
    # 检测"我喜欢xxx"的模式
    if "我喜欢" in user_input:
        like = user_input.split("我喜欢")[-1].strip().rstrip("。，！")
        memory["user_info"].setdefault("preferences", []).append(like)
        save_memory(memory)
    
    return memory

然后修改 SYSTEM_PROMPT 和 chat() 函数：

# 在启动时加载记忆，注入到系统提示词
memory = load_memory()

SYSTEM_PROMPT = f"""你是一个智能助手，可以查询天气和进行数学计算。

关于用户的信息：
{json.dumps(memory.get('user_info', {}), ensure_ascii=False, indent=2)}

请记住用户的信息，在回答时体现你的关心。
不要猜测答案，不确定时一定要调用工具查询。"""

messages = [{"role": "system", "content": SYSTEM_PROMPT}]

def chat():
    global memory
    print("🤖 Agent 已启动（完整版：工具+记忆），输入 '退出' 结束对话\n")
    
    if memory.get("user_info", {}).get("name"):
        print(f"  （我记得你，{memory['user_info']['name']}！）\n")
    
    while True:
        user_input = input("你: ").strip()
        if user_input.lower() in ["退出", "exit", "quit"]:
            print("👋 再见！下次我还记得你。")
            break
        
        # 提取并保存用户信息
        memory = extract_and_save_info(user_input, memory)
        
        messages.append({"role": "user", "content": user_input})
        
        # ... 后面的工具调用逻辑和之前一样 ...
        # （省略，完全复用第二版的 while True 循环）

现在关掉程序再重新打开，试试：

🤖 Agent 已启动（完整版：工具+记忆），输入 '退出' 结束对话

  （我记得你，小明！）

你: 我喜欢打篮球
你: 退出
👋 再见！下次我还记得你。

重新运行：

🤖 Agent 已启动（完整版：工具+记忆），输入 '退出' 结束对话

  （我记得你，小明！）

你: 我喜欢什么运动？
🤖 Agent: 你之前告诉过我，你喜欢打篮球！🏀

这就是长期记忆。 实际项目中，你会用向量数据库（如 ChromaDB）替代 JSON 文件，实现语义检索——不是精确匹配，而是"意思相近"就能找到。但原理是一样的：存下来，下次取出来。

---

四、框架选型：LangChain vs LangGraph vs 手写，怎么选？

4.1 三种方案对比表

维度	纯手写（本文方式）	LangChain	LangGraph
学习成本	⭐ 最低	⭐⭐⭐ 中等	⭐⭐⭐⭐⭐ 高
灵活度	⭐⭐⭐⭐⭐ 最高	⭐⭐ 中等	⭐⭐⭐⭐ 较高
适合场景	学习原理、简单 Agent	快速原型、简单工具链	复杂多步 Agent、生产级
代码量	少，全看得懂	多，框架封装厚	适中，需理解图概念
调试难度	⭐ 简单	⭐⭐⭐⭐ 难（黑盒）	⭐⭐⭐ 中等
社区活跃	-	非常活跃	快速增长
GitHub Star	-	~100K	~12K

4.2 小白该选哪个

分阶段来：

1. 第一阶段（第 1-2 周）：手写。 就用本文的方式，纯 Python + OpenAI SDK。理解 Agent 的本质——工具调用循环、记忆管理、ReAct 范式。不碰任何框架。这一步最重要，框架换了一茬又一茬，原理永远不变。

2. 第二阶段（第 3-4 周）：LangChain。 当你手写烦了（比如要接 10 个工具、要管复杂记忆），就上 LangChain。它帮你把工具注册、记忆管理、文档加载都封装好了，几行代码搞定。但一定要先懂原理，否则出 bug 你完全不知道怎么调。

3. 第三阶段（第 5-8 周）：LangGraph。 当你的 Agent 需要复杂流程控制——比如"先搜A，如果A不够再搜B，搜完要人工确认才能执行C"——就上 LangGraph。它用「状态图」来编排 Agent 流程，是目前生产级 Agent 的主流方案。

一句话建议： 先手写理解原理 → 再用 LangChain 提效 → 最后用 LangGraph 做生产级项目。跳过第一步直接上框架，你会成为"调包侠"，遇到问题完全懵。

---

五、Agent 开发的 6 个常见坑（踩过才知道）

5.1 坑一：模型幻觉导致工具调用失败

现象： Agent 编造了一个不存在的工具名，或者传了错误的参数类型，导致代码报错。

原因： 大模型不是程序，它是在"猜"应该调什么工具。当工具描述写不清楚，或者工具太多，它就容易猜错。

解决方案：

# ❌ 不好的工具描述
def search(query):
    """搜索"""
    ...

# ✅ 好的工具描述
def search_web(query: str, max_results: int = 5):
    """使用搜索引擎查询互联网上的最新信息。
    
    适用场景：用户询问实时信息、最新新闻、你不确定的事实。
    不适用场景：数学计算、天气查询（有专用工具）。
    
    Args:
        query: 搜索关键词，用自然语言描述
        max_results: 返回结果数量，默认5条
    
    Returns:
        搜索结果摘要列表
    """
    ...

原则： 工具描述写给大模型看，要像写给一个聪明但不了解你项目的新同事——把"什么时候用"“什么时候不用”"参数怎么填"都写清楚。

5.2 坑二：上下文窗口爆炸

现象： 对话几轮后，API 报错 “context length exceeded”，或者费用突然飙升。

原因： 每次调用都把全部历史对话发给大模型，对话越长，token 越多，直到超出模型的上下文窗口（通常 128K token）。

解决方案：

# 方案1：滑动窗口——只保留最近 N 轮对话
MAX_MESSAGES = 20

def trim_messages(messages):
    """保留 system 消息 + 最近 N 条对话"""
    system_msgs = [m for m in messages if m["role"] == "system"]
    other_msgs = [m for m in messages if m["role"] != "system"]
    return system_msgs + other_msgs[-MAX_MESSAGES:]

# 方案2：摘要压缩——把旧对话总结成一段话
def summarize_old_messages(messages):
    """用大模型把旧对话总结成一段摘要"""
    old_messages = messages[:-10]  # 旧的
    recent_messages = messages[-10:]  # 最近的
    
    summary = client.chat.completions.create(
        model="deepseek-chat",
        messages=[
            {"role": "system", "content": "把以下对话总结成关键信息，不超过200字"},
            {"role": "user", "content": str(old_messages)}
        ]
    ).choices[0].message.content
    
    return [
        {"role": "system", "content": f"之前的对话摘要：{summary}"},
        *recent_messages
    ]

5.3 坑三：无限循环停不下来

现象： Agent 反复调用同一个工具，或者陷入"思考→调用→思考→调用"的死循环，永远不出最终答案。

解决方案：

MAX_ITERATIONS = 10  # 最大工具调用轮数
iteration_count = 0

while True:
    iteration_count += 1
    if iteration_count > MAX_ITERATIONS:
        messages.append({
            "role": "user", 
            "content": "你已经调用了多次工具，请直接基于已有信息给出回答。"
        })
    
    # ... 正常的调用逻辑 ...

5.4 坑四：API 费用失控

现象： 一个复杂任务跑下来，API 费用几十块甚至上百块。

原因： 每轮工具调用都把完整上下文发给大模型，token 累积非常快。

解决方案：

策略	效果	实现难度
用便宜模型（DeepSeek/Qwen）	费用降低 90%+	⭐
限制最大轮数	防止无限循环烧钱	⭐
对话摘要压缩	减少 token 消耗 70%	⭐⭐
缓存工具结果	相同查询不重复调用	⭐⭐
小模型做路由+大模型做核心	综合降本 60%	⭐⭐⭐

5.5 坑五：工具描述写不好，Agent 不会用

现象： 你明明定义了工具，但 Agent 从来不调用它，或者该用 A 工具却用了 B。

原因： 大模型选工具全靠读 description。描述写得模糊，它就不知道什么时候该用。

黄金法则：

1. 写清楚"什么时候用"和"什么时候不用"
2. 给参数举具体例子
3. 工具数量别超过 10 个（超过就容易选错，考虑用路由 Agent 分发）

5.6 坑六：本地模型效果差

现象： 用 Ollama 跑本地模型（如 Llama 3 8B），Agent 完全不会调工具，或者乱调。

原因： 小模型的 function calling 能力远不如 GPT-4o/Claude。工具调用是个复杂任务，需要模型理解 JSON Schema、正确生成参数。

解决方案：

• 本地模型至少用 14B 以上参数（如 Qwen2.5-14B）
• 用专门支持 tool calling 的模型（看模型文档是否支持）
• 降低 temperature 到 0.1 以下
• 工具描述写得极其详细
• 实在不行，用 prompt 模拟 function calling（手动解析模型输出的 JSON）

---

六、学习路线图：从今天到能上岗

6.1 四阶段成长路线

6.1.1 阶段一：入门（1-2周）

阶段一：入门（1-2周）
├── ✅ 理解 Agent 四大核心组件
├── ✅ 手写一个带工具调用的 Agent（本文内容）
├── ✅ 理解 ReAct 范式
└── ✅ 学会 Prompt 工程基础

6.1.2 阶段二：进阶（2-4周）

阶段二：进阶（2-4周）
├── 📚 学习 LangChain 框架
├── 📚 接入向量数据库（ChromaDB/Faiss）
├── 📚 实现 RAG（检索增强生成）
├── 📚 多工具编排与路由
└── 📚 学习 MCP 协议基础

6.1.3 阶段三：实战（1-2月）

阶段三：实战（1-2月）
├── 🔨 用 LangGraph 构建复杂多步 Agent
├── 🔨 实现多 Agent 协作（Multi-Agent）
├── 🔨 接入真实 API（搜索/数据库/邮件）
├── 🔨 部署上线（FastAPI + Docker）
└── 🔨 做一个完整项目放到 GitHub

6.1.4 阶段四：深入（持续）

阶段四：深入（持续）
├── 🎯 Agentic-RL（强化学习优化 Agent）
├── 🎯 Agent 性能评估与 Benchmark
├── 🎯 Agent 安全与对齐
├── 🎀 A2A 协议（Agent 间通信）
└── 🎀 贡献开源项目

6.2 推荐学习资源

资源	类型	说明	链接
Hello-Agents	开源教程	Datawhale 出品，从零构建 Agent，13.2K Star	GitHub
LangChain 官方文档	文档	最权威的 LangChain 学习资料	python.langchain.com
DeepSeek API 文档	文档	便宜好用的大模型 API	platform.deepseek.com
MCP 协议文档	文档	Model Context Protocol 官方文档	mcp-docs.cn
AI Agent 实战速成	教程	从零到企业级落地	didilili.github.io
OpenCode	开源项目	43.6K Star 的开源 AI 编码代理，读源码学架构	GitHub

---

七、写在最后：Agent 不是未来，是现在

回到开头的那个比喻——ChatBot 是顾问，Agent 是员工。

2023 年，我们在学怎么跟 AI 聊天。
2024 年，我们在学怎么用 AI 写代码。
2025-2026 年，我们在学怎么让 AI 替我们干活。

这就是 Agent 的意义。它不是一个新名词，而是 AI 从"能聊天"到"能干活"的关键一跃。

这篇文章给你的不是空中楼阁的概念，而是一套你能今天就开始跑的代码。别光看，去运行它。改一改工具，加一个你自己的功能，比如：

• 加一个「发邮件」工具
• 加一个「查股票」工具
• 把 JSON 记忆换成真正的向量数据库
• 接入你公司的内部 API

改一行代码，胜过读十篇文章。

---

💬 有问题？评论区见！

这篇文章的代码全部经过验证，可以直接运行。但每个人的环境不同，如果你在搭建过程中遇到任何问题——装包报错、API 调不通、工具不触发、循环停不下来——不要犹豫，直接在评论区留言。我会逐条回复，帮你跑通。

如果这篇文章对你有帮助，点个赞👍让更多小白看到。你的每一个问题，都会帮助后来者少踩一个坑。

下一篇我会写**「用 LangChain + 向量数据库搭建一个能读 PDF 的知识库 Agent」**，想看的评论区扣 1。