Agent 核心

这是一套写给应用开发者的 Agent 开发教程：默认你会写代码、懂基本的编程概念，但不要求机器学习背景。我们从「模型眼里的文字长什么样」一路讲到「如何交付一个值得托付的生产级 Agent」——原理讲直觉，实战给代码。

这套文档解决什么问题

市面上的 Agent 资料两极分化：一边是学术论文和模型原理，门槛高、离工程远；另一边是框架速成教程，教你调 API，但讲不清背后发生了什么。结果是很多人能跑通 Demo，却回答不了这些问题：

• 为什么模型有时"理解"不了我的指令，有时又表现出色？
• 温度（temperature）到底在控制什么？设成 0 是什么效果？
• 上下文窗口满了会发生什么？该怎么设计应对策略？
• Tool Calling 的原理是什么？为什么模型会"调用"工具？
• Skill、MCP、子代理分别在什么场景下使用？

这套文档的目标：让你从"会用"到"理解"，再从"理解"到"能造"。读完第三章，你可以不依赖任何框架，用几百行 Python 写出自己的 Agent；读完第五章，你知道怎么让它值得托付。

五个问题，十五章

与其罗列一堆知识点，不如用五个问题组织整个旅程——每一章都在回答其中一问，前一问的答案又是后一问的地基：

完整目录

第一章 · 它是什么（01-04）

第二章 · 怎么用好它（05-06）

第三章 · 怎么让它干活（07-09）

第四章 · 怎么扩展它（10-12）

第五章 · 怎么做得可靠（13-15）

三条阅读路线

完整路线（推荐第一次学习使用）：00 → 01 → … → 15 顺序阅读。第一章的数学直觉和第二章的消息体系会在后面反复出现。

快速路线（已有 ML 基础，想尽快上手 Agent）：从 05 开始 → 06 → 07 → 08 → 09，然后按需阅读 10-12。遇到理解不了的概念再回查第 1-4 章。

方法论路线（已会开发，想提升设计能力）：13 → 14 → 12 → 11 → 15。

环境准备

全部代码基于 Python 3.12+，依赖极少：

# 建议使用 uv 管理环境
uv init agent-lab && cd agent-lab
uv add numpy openai pydantic

# 安装 Ollama（第二章起需要）：https://ollama.com
# 拉取一个轻量模型用于练习
ollama pull qwen3:4b

代码约定：

• 第一章（01-04）只用 numpy，每个示例都可直接运行、打印结果
• 第二章起用 openai SDK 直连 Ollama，不引入任何 Agent 框架——目的是看清每一层
• 第四章按需引入 mcp 等标准库
• 所有代码完整可运行，不省略 import，方便你逐行敲一遍

开始之前：一个心态

第一章的数学可以用"直觉优先"的方式读：看不懂公式时，先读公式旁边的文字解释和代码示例，代码跑一遍再看公式，往往就通了。这套文档里每个数学概念都配了能运行的代码，因为对开发者来说，一段可运行的 numpy 代码比三页推导更有说服力。

从 01 开始吧。