读了一遍 GitHub 上 12K Star 的 AI Agent 开源书

去年年底，LLaMA 的老板说 2025 年是 AI Agent 元年。

我当时觉得他在画饼。

然后项目就来了。

---

我们组有个运维工具，本来接了个 LLM 做问答，挺简单的，效果也凑合。后来需求变了。不是一点一点变，是突然膨胀------要查数据库告警、要调监控 API、要能做多步排查。我那个脚本，就一个"调 API 返回结果"的逻辑，直接废了。

不是报错。是逻辑上根本兜不住。

举个例子。用户问 最近半小时哪个服务告警最多。模型得先调告警接口，拿结果，分析，再输出。如果第一步返回 50 条告警，它还得判断要不要再细化查询。每一步都可能挂。工具调失败了怎么办？返回的结果太长塞不进上下文窗口怎么办？模型在中间步骤开始胡说怎么办？

我的脚本，这些问题一个都没考虑。

然后就开始找资料。然后就掉进了一个坑。

资料太多了，但互相之间，没什么关系。

LangChain 文档我看了一周多。学会了定义 tool，学会了 AgentExecutor。但换个场景，换个工具组合，又不会了。就那种感觉------你学会了框架的语法，但没学会语法背后的语法。

ReAct 论文也看了。知道"思考-行动-观察"循环。但论文是论文，代码是代码，中间那条沟，自己填。

后来翻到了 ai-agent-book。

---

一个纠结了的问题

李博杰写的，华为诺亚方舟实验室。12K Star，Apache-2.0，401 个 commit，10 章，88 个项目。Python 占了 94.8%。

但我想说的不是这些数字。

我想说的是，它回答了一个我纠结了很久的问题。

LLM、上下文、工具。这三样东西的接口到底长什么样？

书里有个公式：

Agent = LLM + 上下文 + 工具

很常见，到处都有。但大部分资料的处理方式是：LLM 一章，上下文一章，工具一章，最后总结"三者结合即为 Agent"。

没了。

就没了。

这感觉像什么？你买了一大盒乐高，说明书上写着"拼起来就是城堡"。然后呢？哪个先拼？这块和那块用什么连接？说明书不说。

但书里不是这样。

它讲工具调用的时候，会同时讲工具结果怎么影响上下文。上下文变化了，LLM 的下一步推理会怎么变。ReAct 是那条线，从头穿到尾。你看完不是"哦 我知道了三个概念"，而是**"哦 原来数据是这么流动的"**。

这种讲法，我翻过的中文资料里，很少有。

---

再举个例子。工具调用，大部分教程就讲到这里：

# 定义函数 → 模型返回 tool_calls → 执行 → 结果塞回去

完。

但实际做的时候，烦人的问题全部还在后面：

• 工具描述怎么写模型才不容易误调用？太详细了模型会"想太多"，太简略了模型会乱调
• 工具返回的结果如果太长，是截断还是摘要？截断丢了关键信息怎么办？
• 模型连续调同一个工具三次都没拿到想要的，你要不要中途打断它？

这些，大部分教程不碰。

ai-agent-book 碰了。 而且不是碰一下就跑，是深入进去讲。

---

中间那几章

10 章不全部展开，挑几个我印象深的。

第二章：模型选型

不是那种列个表"GPT-4 参数多少、Claude 参数多少"的路子。它分析的是不同模型在做 Agent 时的行为差异。

• 有些模型推理强但指令遵循差------你让它调工具，它能给你分析半天为什么要调，但就是不调。你说急不急
• 有些模型反过来，指令遵循很准，但推理弱，碰到多步判断就卡

这个判断力，做多了自然有，但有人帮你提前捋一遍，真的省时间。

第四章到第七章：全书的脊梁骨

章节	内容	技术演进路径
第四章	上下文管理	滑动窗口 → RAG → 摘要压缩 → 分层记忆 → 结构化记忆
第五章	工具系统	Function Calling → MCP
第六章	推理框架	ReAct → Plan-and-Execute → Tree of Thoughts
第七章	多 Agent 协作	---

叙述方式挺合我胃口的。不是"方案 A 是 XXX，方案 B 是 YYY"。而是：

先有方案 A，解决了 X，但带来了 Y。于是有了方案 B。B 解决了 Y，又带来了 Z。所以有了方案 C。

你理解的不只是技术，是技术为什么要这样拐弯。

---

试跑了一下项目

我实际跑了 5 个项目。

环境很快：

Python 3.10+
pip install -r requirements.txt
# 配 .env，完事

没遇到依赖冲突。一个都没有。

这个体验在我跑过的 AI 开源项目里，真的稀有。之前跑某个 Agent 框架的 example，光解决依赖就耗了一个下午。太费时间了。

第四章：工具调用 Agent

核心代码就一百多行。骨架大概是这样：

import json
from openai import OpenAI

client = OpenAI()

def get_weather(city: str) -> str:
    """查询指定城市的天气"""
    # 实际项目中这里调气象 API
    return f"{city}：晴，22°C"

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市的天气情况",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"}
                },
                "required": ["city"]
            }
        }
    }
]

messages = [{"role": "user", "content": "北京今天天气怎么样？"}]

while True:
    response = client.chat.completions.create(
        model="gpt-4",
        messages=messages,
        tools=tools
    )
    msg = response.choices[0].message

    # 模型要调工具：执行工具，结果写回 messages，继续循环
    if msg.tool_calls:
        for tool_call in msg.tool_calls:
            args = json.loads(tool_call.function.arguments)
            result = get_weather(**args)
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": result
            })
        continue

    # 模型输出文本：结束循环
    print(msg.content)
    break

定义函数，while 循环，模型返回 tool_calls 就执行工具、结果写回 messages，返回文本就输出。干净。不套框架，就是最原始的调用逻辑。看完这个再看 LangChain 的 AgentExecutor，你就知道它底层在干什么了。

我改了几个参数，把 get_weather 换成公司内部的数据库查询，改改 prompt 和工具描述，通了。

第六章：ReAct 推理

书里用了一个很短的例子解释 ReAct 循环。比如问"2024 年诺贝尔物理学奖得主是谁"，模型不会直接猜，而是这样走：

Thought: 我需要查一下 2024 年诺贝尔物理学奖得主
Action: search("2024 年诺贝尔物理学奖得主")
Observation: John Hopfield 和 Geoffrey Hinton

Thought: 已经拿到结果，可以回答用户了
Answer: 2024 年诺贝尔物理学奖授予 John Hopfield 和 Geoffrey Hinton

每一步思考、行动、观察，三拍一个循环。不是"模型一次性输出答案"，而是"模型一边想一边做一边看结果"。这个概念本身不复杂，但书里把它拆成了可运行的代码，每个环节都配了示例，看一遍就懂了。

第八章：MCP 项目

MCP 是 Anthropic 提的，你可以把它理解成工具调用的 USB 协议。不管后端是什么------本地文件、SQLite、第三方 API------前端统一用一套接口调。书里带你搭一个 MCP Server，把各种数据源注册进去，Agent 通过 MCP 统一访问。

客户端连接 MCP Server 的代码大概是这样：

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    # 启动 MCP Server（这里以一个本地文件服务器为例）
    server_params = StdioServerParameters(
        command="python",
        args=["mcp_server.py"]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # 列出该 Server 提供的所有工具
            tools = await session.list_tools()
            for tool in tools.tools:
                print(f"工具名: {tool.name}, 描述: {tool.description}")

            # 调用具体工具
            result = await session.call_tool("read_file", {
                "path": "/data/report.txt"
            })
            print(result.content)

asyncio.run(main())

跑完这个项目，比看十篇科普文章都管用。

---

适合哪些？

判断很直接。

不适合：

• Python 都没写过？先别忙着看。先去看微软的 AI Agents for Beginners，或者黄佳老师的《动手做 AI Agent》。把基础的东西跑通再说。

适合：

• 用过 LangChain，调过 Function Calling，但总觉得在套模板，换个场景就不会了------这本书补的是模板下面的那层东西
• 已经在带 Agent 项目，要做架构设计和技术选型------第四章到第七章可以当参考手册翻
  

还有一点。开源书，迭代快。 AI Agent 变得太快了，纸质书从交稿到出版小半年，出来的时候有些内容已经过时了。GitHub 仓库没这个问题，PR 和 Issue 一直活跃。

---

怎么读

别从头到尾啃。

我的读法：

1. 第一章快速过
2. 直接跳重点第四章和第五章------工具调用和记忆机制，这两块是 Agent 跟普通 chatbot 真正拉开差距的地方
3. 搞懂了，回去补第二章 LLM 基础。这时候很多之前觉得模糊的东西，自己就清楚了
4. 后面按需选读

88 个项目也别全跑。挑 5-6 个跟你的场景相关的，跑通，读懂，改。

把示例的工具函数换成你自己的数据源。这个"改"的过程，学到的东西比跑通十个项目多得多。

---

项目地址：https://github.com/bojieli/ai-agent-book