理论+代码双管齐下：手把手构建大模型智能体Agent

1. 为什么这本 Agent 教程值得从头啃到尾

1.1 “理论+代码”这条路，到底卡在哪儿

最近把一套叫《动手学大模型智能体》的教程完整刷了一遍，感受挺复杂。市面上讲 Agent 的资料实在太多了，但绝大多数可以归成两类：一类是纯概念科普，Chain of Thought、ReAct、Plan-and-Execute 这些词讲得头头是道，配上几张结构图，看完你觉得自己懂了，关上页面却写不出一行代码；另一类是纯 demo 搬运，丢一个仓库让你 clone 下来跑，跑完界面很炫，但你改一行逻辑都不知道该从哪里下手。

这套教程难得地把两条线并到了一起：理论负责回答“为什么这么做”，代码负责展示“到底怎么落地”。标题里那句“理论+代码双管齐下”不是营销话术，它确实是把 Agent 开发拆成了可学习、可复现、可迁移的模块，尤其适合那些已经被 Prompt 工程玩得比较熟、想往 Agent 开发方向走的人。

我自己的亲身经历是：理论学得再多，如果不亲手写一个带工具调用的循环，你永远理解不了“模型输出一个 JSON 并不等于调用了工具”这件事。反过来，如果只看代码不看理论，你可能连“为什么要 temperature 设低一些”“为什么要给工具加 description”都说不清楚。这套教程的价值，就是把这两条线拧成了一股绳。

1.2 谁适合学，学到什么程度算“学完能用”

先说结论：这套教程不是零基础入门课。你需要会 Python 基础语法，知道什么是函数、什么是装饰器、怎么用 requests 或 httpx 发 HTTP 请求，最好还自己调过大模型 API，哪怕只是写过一个最简单的“输入 prompt 返回补全结果”的脚本。满足这些条件，再去啃它会非常顺畅。

如果你连“system prompt 和 user message 有什么区别”都没搞明白，建议先补一轮大模型 API 基础再回来学，不然前两章还算轻松，到了工具调用和记忆管理部分会比较吃力。

“学完就能用”这件事，我的理解是这样的：不是说你学完就能立刻做一个生产级多智能体平台，而是你学完以后，自己心里有了一张 Agent 的完整地图——从模型接口、工具注册、循环编排到记忆管理、结果评估，每个环节都知道该写什么代码、该注意哪些坑。后续你再去看其他框架的源码，或者自己从头写一个定制 Agent，都不会再觉得无从下手。这是比“跑通一个 demo”重要得多的能力。

2. 内容整体设计与思路拆解

2.1 Agent 的最小骨架：模型、工具、编排

教程第一条主线，是把 Agent 拆成三个不可再拆的部分：模型、工具、编排。模型负责理解与生成，工具负责执行具体动作，编排负责把前两者串成一个循环。很多人一说 Agent 就想到 LangChain 这类框架，但教程没有一上来就上框架，而是先用最小代码实现了一个能跑的循环，这一点我非常认同。

先理解最小骨架，再看框架就会容易很多。你可以把 Agent 想象成一个实习生：模型是这个实习生的“脑子”，工具是他能操作的计算器、搜索引擎、数据库，编排则是“接收任务—思考—决定用哪个工具—执行—看结果—继续思考”的工作流程。没有编排，脑子再聪明也只是一个聊天机器人；没有工具，编排得再好也只能空想。

教程里反复强调一个原则：Agent 的本质不是“模型变强了”，而是“模型从一个只能输出的文本生成器，变成了一个能够调用外部资源的决策器”。这个视角转变很关键。以前写 Prompt 是在教模型“怎么说话”，现在写 System Prompt 是在教模型“什么时候该调用什么工具、怎么根据工具结果继续行动”。两者是完全不同的思维方式。

我比较欣赏的一点是，教程里没有把思维链、ReAct、Function Calling 这些概念当成玄学来讲。它明确告诉你：ReAct 是一种让模型先思考、再行动、再观察结果、循环往复的模式，其数学本质没有多复杂；Function Calling 则是模型输出结构化指令、由外部系统执行的一种协议。理论部分点到为止，但足够支撑你理解后面的代码。

2.2 理论板块选讲了哪几件事

这套教程的理论部分做了不少减法。它没有试图把大模型原理从头讲一遍，也没有堆砌几十个 Agent 相关论文，而是挑了几个“学完马上能用”的核心话题：上下文窗口与 token 计算、工具调用的协议设计、Agent 的记忆机制、多步规划与错误恢复。

每个话题都围绕一个实际问题展开。比如讲 token 计算，是因为 Agent 比普通对话更容易把上下文打满——每轮工具调用结果都会塞进历史，三轮之后就可能超窗；讲记忆机制，是因为 Agent 不能只靠“把全部历史塞进 Prompt”这种笨办法，得有摘要、滑动窗口、向量检索这些手段。

最让我意外的是，教程里专门有一节讲“Agent 的失败模式”。它在理论阶段就告诉你：Agent 会陷入循环、会调用不存在的工具、会被模型的幻觉带偏、会在工具返回异常后不知所措。这些内容通常在实战经验帖里才会看到，教程却把它放在理论部分提前预警，后面每一章节再逐个用代码演示怎么应对。这种编排明显是踩过坑的人做的课程，不是那种照着 PPT 念的学院派教程。

2.3 代码部分的设计思路：跟着能跑，跑完能改

代码部分的核心设计理念是“渐进式替换”：先用最简单的字符串解析版 Agent 跑通全流程，再升级为 JSON 结构化输出，再接入真正的外部工具，最后加入记忆模块和评估模块。每一步代码量都不大，但每一步都在前一步的基础上解决一个具体痛点。

我印象很深的是工具注册机制的设计。教程没有把工具列表写在代码里，而是用一个带装饰器的注册表来管理工具：

python复制TOOL_REGISTRY = {}

def register_tool(name, description):
    def decorator(func):
        TOOL_REGISTRY[name] = {
            "name": name,
            "description": description,
            "func": func,
        }
        return func
    return decorator

@register_tool("calculator", "对两个数字做四则运算，输入格式：数字1 运算符 数字2")
def calculator(expr: str) -> str:
    # 实际计算逻辑
    return result

这样的设计让新增一个工具只需要写一个普通函数加上一行装饰器声明，对初学者非常友好。后面接触 LangChain 的工具装饰器写法时，你会发现很多框架的思路都跟这差不多，因为这就是 Agent 工具管理的常见范式。

代码部分还有一个容易忽略但很值得学习的点：它刻意把“大模型调用”封装成一个单独函数，而不是在循环里直接写 SDK 调用。这样做的目的是让你后续可以随意替换底层模型，本地部署一个开源模型也好、接某个云厂商的兼容接口也好，只需要改这一个函数，其它代码一概不用动。这个思想影响了我后来很多项目——对模型的抽象隔离越早做，后期调整成本越低。

3. 核心细节解析与实操要点

3.1 环境准备与依赖选型

动手阶段，教程第一步是让你准备一个干净的 Python 环境，并安装最小依赖集：requests、python-dotenv、rich。没有引入任何重量级框架。这是一个刻意的选择——如果你一开始就用 LangChain，框架本身封装了大量细节，很多问题会被隐藏掉，出了问题也不知道去哪查。手写一个最小实现，每一步都是自己控制的，反而更容易建立正确的心理模型。

我实际操作时习惯先把虚拟环境建好：

bash复制python -m venv .venv
source .venv/bin/activate
pip install requests python-dotenv rich

接着准备一个 .env 文件，里面放模型 API 的地址和密钥。注意，这里的“模型服务”既可以是你本地起的一个开源模型服务，也可以是云厂商提供的兼容接口，教程在配方上写得比较通用，你只需要按自己的情况填 endpoint 和 key 就行。

我在学习时顺手做了一个小改造：把 call_llm 函数包了一层重试逻辑。原因是本地部署的模型服务不太稳定，偶尔高峰时会返回 5xx，加个指数退避式的重试，能让学习过程顺畅很多：

python复制import requests
import time

def call_llm(messages, tools=None, max_retries=3):
    endpoint = "https://your-endpoint.example.com/v1/chat/completions"
    headers = {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"}
    payload = {
        "model": "your-model-name",
        "messages": messages,
        "temperature": 0.2,
        "tools": tools,
    }
    for attempt in range(max_retries):
        try:
            resp = requests.post(endpoint, json=payload, headers=headers, timeout=60)
            resp.raise_for_status()
            data = resp.json()
            return data["choices"][0]["message"]
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

这里的 temperature 降到 0.2 是有讲究的。Agent 场景下我们需要模型尽量稳定地输出结构化指令，而不是发挥创意，温度越高越容易在工具调用格式上出现随机错误。我自己后来做 Agent 时，temperature 基本都控制在 0.1 到 0.3 之间，极少超过 0.5。

3.2 实现一个带工具调用的 ReAct 循环

实操部分最核心的一个案例，是实现一个带工具调用的 ReAct 循环。教程先让模型输出“思考 + 行动 + 最终答案”的纯文本格式，代码用正则把行动指令解析出来，再执行对应工具。这一步虽然朴素，但把整个流程跑通了。

随后教程升级为更可靠的方案：利用模型服务自带的 tool 参数。许多大模型服务商都提供了原生工具调用接口，模型会返回一个结构化的 tool_calls 字段，里面包含工具名和参数，而不是把指令写在自然语言里。这样就不需要自己写正则去猜，稳定性大幅度提升。

一个简化版的核心循环大致是这个样子：

python复制def run_agent(user_query, max_steps=5):
    messages = [
        {"role": "system", "content": "你是智能助手，可调用工具解答问题。"},
        {"role": "user", "content": user_query},
    ]
    for step in range(max_steps):
        message = call_llm(messages, tools=list_tool_schemas())
        messages.append({"role": "assistant", "content": message.get("content"), "tool_calls": message.get("tool_calls")})

        if not message.get("tool_calls"):
            return message["content"]

        for tc in message["tool_calls"]:
            tool_name = tc["function"]["name"]
            tool_args = tc["function"]["arguments"]
            tool_func = TOOL_REGISTRY[tool_name]["func"]
            result = tool_func(tool_args)
            messages.append({
                "role": "tool",
                "tool_call_id": tc["id"],
                "content": result,
            })
    return "已达到最大步数，停止。"

这段代码看似简单，细节其实不少。第一，assistant 消息里必须把 tool_calls 原样回传给模型，很多服务端校验这个一致性，漏传会直接报错。第二，每一步工具调用的返回结果要用 role=“tool” 的消息回填，并且带上 tool_call_id，用来指明这条结果是针对哪次调用。第三，max_steps 是硬性防线，防止模型陷入“调用工具—观察结果—再调用工具”的死循环，这在后文排查部分还会展开。

我把这段代码在自己的环境里跑了几遍，然后把工具换成了真正的外部天气接口，试了“帮我查一下某城市今天适合穿什么”这类需要多步推理的问题。第一次跑通的时候特别有成就感，因为它是从零写出来的，而不是 import 一个现成 Agent 类——两者的心态完全不同。

3.3 给 Agent 加上基础记忆

Agent 跑通之后，教程引入的下一个问题是记忆。普通聊天机器人把所有对话记录塞进 messages 数组就行，但 Agent 场景下，光工具调用的中间结果就可能占掉几千 token，加上多轮对话历史，分分钟触发上下文超限。

常用方案是滑动窗口：只保留最近几轮消息，更早的内容压缩成一段摘要。教程里的实现思路很朴素：当消息总长度超过阈值时，触发一次模型调用，把前面所有内容用一个 prompt 总结成 200 字以内的摘要，然后再继续后续对话。代码如下：

python复制def summarize_messages(messages):
    summary_prompt = f"请将以下对话压缩为不超过200字的摘要，保留关键结论与任务进展：\n{messages}"
    summary = call_llm([{"role": "user", "content": summary_prompt}])
    return summary["content"]

def manage_memory(messages, max_tokens=4000):
    if estimate_tokens(messages) <= max_tokens:
        return messages
    summary = summarize_messages(messages[:-2])  # 保留最近两条完整消息
    return [
        {"role": "system", "content": "以下是之前对话的摘要：" + summary},
        *messages[-2:],
    ]

这个设计不复杂，但在学习阶段价值很高。它让你理解记忆方案的本质：不是造一个“记忆库”，而是管理“模型能看到的 token 配额”。后续你去读那些记忆框架的源码，会发现它们做的也是类似的事——压缩、筛选、检索，只是实现得更工程化。

我试过用向量数据库来做长期记忆，但很快就发现，如果用户的场景就是单轮任务型的 Agent，滑动窗口 + 摘要已经覆盖了绝大多数需求。向量检索更适合“从大规模历史中找精准信息”的场景，那是另一个复杂度层级。教程把先做减法再谈扩展的节奏控制得很好。

4. 常见问题与排查技巧实录

4.1 上下文规划：为什么总是在第三轮对话就截断

教程里我第一个碰到的问题是：多轮对话跑到第三、四轮，就出现“上下文长度超限”。排查后核心原因在于，每执行一次工具调用，它会往 messages 里追加两条甚至更多消息：一条是 assistant 的 tool_calls，一条或多条是 tool 返回值。一次任务三步工具调用，直接增加了六条消息和几千 token，普通人很难直观感受到这个膨胀速度。

解决办法有两个方向。一个是上面说的滑动窗口 + 摘要；另一个更激进——每轮只保留用户问题、最近一条 assistant 消息和最新工具结果，其余全部丢弃。后者会丢失中间推理过程，但在很多简单任务上完全够用。提示词里的系统消息也会占用上下文空间，尽量控制在一百多个字以内，别把大段背景资料塞进去。

判断 token 数量时，可以用一个近似估算函数：中文大概一个字对应 1 到 1.5 个 token，英文一个词约 1.3 个 token。精确计算可以用模型服务商提供的 tokenizer，但学习阶段近似够用。

4.2 模型输出不稳定：解析函数要做容错

模型输出工具调用时，偶尔会出现 JSON 格式不合法的情况，比如参数里带了注释、括号没闭合、字段名被改写。教程里花了很大篇幅讲容错解析，这是非常有用的实战内容。

容错解析分层处理：第一层是低级的字典转对象封装；第二层是字符串清洗；第三层是“解析失败后的重试机制”。具体来说，拿到 tool_calls 里的 arguments 字符串后，先尝试 json.loads，失败则去掉首尾多余空白和注释符号后再试，仍然失败就调用一次模型“修正 JSON”，返回修正结果。后一种方式会多花一次模型调用，但也多了一个修复机会。

我踩过的一个典型坑是：让模型返回“工具名 + 参数”时，它把参数写成了数组而不是对象，甚至把中文标点混进 JSON。后来我在工具调用 prompt 里明确添加了一句“参数必须是合法 JSON 对象，不要包含注释”，这类问题明显减少。说到底，模型不是按规范工作的，你的代码得具备“预期它可能出偏差”的防御意识。

4.3 工具调用失控：终止条件比想象中更重要

第一次跑多步 Agent 时，我遇到一个很经典的死循环：用户问“比较两篇文章的差异”，模型先调用了一次摘要工具，看到摘要后又决定再调用一次更详细的摘要工具，第三次决定调用“补充信息”工具，然后又回到摘要工具……如果没有 max_steps 限制，它理论上可以无限循环下去。

所以我在上面那段核心循环代码里专门加了 max_steps 参数。设定这个值时要考虑任务复杂度：简单问答 3 步就够，复杂分析任务可以放宽到 8 到 10 步，但一般不要超过 15 步。除了步数限制，还有一种做法是设定“重复检测”——如果模型连续两次调用同一个工具且参数相同，就强制中断并询问用户是否继续。这类防护机制在生产环境中尤其重要，不然一个失控循环可能带来大量 API 费用。

另一个容易被忽视的终止条件是“工具执行出错怎么办”。教程推荐的做法是把异常信息转成工具结果返回给模型，让模型自己判断下一步。例如工具里捕获异常后返回“工具执行失败：xxx”，模型看到这个信息后通常会重新规划或向用户确认，而不是整个流程崩溃。这个策略我沿用至今，非常实用。

4.4 别急着造轮子：框架复用与手写之间的取舍

学习过程中要守住一条原则：是为了理解而手写，不是为了手写而手写。初期把 Agent 循环手写一遍，是为了看清底层逻辑；但当你进入真实项目阶段，手写的一套东西可能在可靠性、并发处理、可观测性上都不如成熟框架。

以工具注册为例，手写装饰器简单直接，但真实场景里工具可能有参数校验、鉴权、重试、限流等需求，自己写要在这些边角上花掉大量时间。教程里给我的启发是：知道手写版是怎么工作的，再去用框架，你就会知道框架帮你解决了什么、它背后做了什么、它可能在哪些地方掩盖问题。

我做项目时的方法是：先用框架的 AgentExecutor 类跑通业务验证，再把关键路径上如果出现了框架解释不了的问题，就回到手写循环里做实验。这套“两条腿走路”的方式，比单纯依赖框架或单纯手写都稳妥。

5. 我实际用下来的体会与后续扩展方向

把整套教程学完之后，我最大的感受是：Agent 开发的门槛不像想象中的“需要懂强化学习”那么高，但也绝不是一个 Prompt 就能搞定的事。真正的工作量集中在工具协议设计、上下文规划、错误恢复这些工程细节上。

我个人最受益的一点，是养成了“先画循环图，再写代码”的习惯。动手之前先用文字或表格把“模型收到什么、能调什么工具、每一步可能发生什么异常、异常后怎么办”列清楚，再落代码，写出来的东西明显比凭感觉写稳得多。教程里的核心代码虽然短，但每一步都有清晰意图，这就是结构化的价值。

如果你学完以后还想继续深入，我建议按这个顺序扩展：先给 Agent 接入检索外部数据源，做成 RAG 形态；再加多轮对话管理和用户信息持久化；然后尝试让 Agent 调用多个工具联动，比如先查数据库再发消息；最后再考虑多智能体协作，把不同职责的 Agent 组合成流程。每一步都有公开资料可以参考，但前提是你已经具备了自行搭建最小系统的能力。

根据我的经验，一套教程能不能真正让你“学完就能用”，看的不是最后的项目有多炫，而是它有没有在一开始就把 Agent 的骨架掰开揉碎讲清楚。这套《动手学大模型智能体》在这方面做得比较难得，至少对我而言，它让我从一个“只会调 Prompt 的观众”，变成了一个“手里有完整实现地图的开发者”。