这是一套从零开始学习 Agent 工程的中文教程。我们不会先搬出一套庞大的框架，而是从一次最小的模型调用出发，亲手搭建一个 Inventory & Quote Agent（库存与报价助手），再一步一步为它加入工具、运行循环、校验、恢复、记忆、评估和可观测性。
大语言模型擅长理解上下文和生成文本，却不会自动知道公司的实时库存，也不能自己执行程序。Agent 是围绕模型建立的一套应用程序：模型判断下一步，程序调用外部工具并返回结果，双方在一个受控制的循环中协作，直到完成任务或安全停止。
整套课程想回答的不是"怎样尽快调通一个框架"，而是一个更基础的问题：
一个只会生成文本的模型，怎样逐步成长为能做事、会失败、可恢复，而且能够证明自己表现如何的可靠 Agent？
我们会做出什么
课程始终围绕同一个案例演进：一家工业设备公司的销售助手。它最终需要完成这样的任务：
检查 A100 的库存，为客户计算折扣价格，生成报价；遇到依赖故障时能够恢复，涉及高风险操作时等待人工批准，并为整个过程留下可追踪、可评估的记录。
这句话看起来像一个功能，实际包含许多彼此独立的问题：
- —模型怎样获得自己训练数据之外的实时库存？
- —模型选错工具或生成错误参数时，程序怎样拦住它？
- —网络超时、工具失败或程序重启后，任务怎样继续？
- —对话越来越长时，怎样控制延迟与成本，又不丢失关键信息？
- —我们怎样用测试、评估和指标证明一次修改真的让 Agent 变好了？
每一篇只解决其中一个足够小的问题。代码、测试和解释会沿着同一个项目持续生长，不会在每章重新换一个互不相关的示例。
这套课程怎样教
课程遵循一条简单原则：先看见问题，再引入解决问题的概念。
一篇文章通常会经历这样的过程：
- 1.提出一个真实的产品需求；
- 2.写出当前最小可运行实现；
- 3.如果条件允许，主动制造一次失败；
- 4.记录程序的真实输出，而不是凭想象描述结果；
- 5.分析失败边界，再完成最小修复；
- 6.用测试、数据或评估证明变化；
- 7.最后总结这一篇建立的核心心智模型。
因此，Error（错误）、Latency（延迟）和 Cost（成本）不会等到项目结束才补上。它们从最早期就进入系统，因为 Agent 后续的重试、停止、降级和继续执行，都依赖这些信号。
当前课程
第一课从 Hello LLM 开始，逐步走向第一个可调用的库存工具。
| 篇目 | 对应代码 Tag | 这一篇解决的问题 |
|---|---|---|
| 01. 先让程序和模型说上第一句话 | v0.0.1-basic-chat | 认识大语言模型、Chat Completion 和请求边界；看清"会生成文本"不等于"知道业务事实" |
| 02. 模型调用失败时，程序应该看见什么 | v0.0.2-error-handling | 真实触发认证、网络和请求错误，把 Provider 异常翻译成应用可以采取行动的错误类型 |
| 03. 一次回答到底花了多少时间和钱 | v0.0.3-cost-latency-tracking | 为每次模型调用记录 token、延迟和估算成本，建立最小可观测数据 |
| 04. 先给模型一份查库存的说明书 | v0.1.1-inventory-tool-schema | 写出真实库存函数和 Tool Schema，分清可执行实现、模型可读契约与运行时校验 |
| 05. 模型提出调用，程序执行工具 | v0.1.2-single-tool-call | 走完一次完整工具调用：模型提出请求、程序执行函数、结果送回模型生成最终回答 |
| 06. 查不到商品时，模型会不会编一个数字 | v0.1.3-hallucination-guard | 确认程序能把"没有查到"正确传给模型，再用真实调用观察模型是否会编造库存数字 |
| 07. 让销售助手学会入库和出库 | v0.2.1-multi-tool-registry | 加入 add_inventory 和 remove_inventory，用工具注册表让调用代码不随工具数量增加分支 |
文章中的 Tag 是某个代码版本的固定标记。切换到表格里的 Tag，就能看到文章写作时使用的完整代码状态，不必猜测示例来自哪个版本。
两种阅读方式
如果你想先建立完整理解，可以按上表顺序阅读长文。每篇都会补充背景、术语、图解、真实运行结果和练习，不要求你预先了解 Agent 框架。
如果你更喜欢边写边学，可以打开配套代码仓库 agent-from-zero，切换到文章对应的 Tag：
git clone https://github.com/sleepworm/agent-from-zero.git
cd agent-from-zero
git checkout v0.0.1-basic-chat
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest项目要求 Python 3.11 或更高版本。测试使用模拟响应，不需要真实 API Key；只有亲自调用 DeepSeek API 时，才需要复制 .env.example 为 .env 并填写 DEEPSEEK_API_KEY。
还可以用 Git 比较相邻版本，观察这一篇究竟改变了什么：
git diff v0.0.2-error-handling v0.0.3-cost-latency-tracking后续路线
后续内容会随着真实代码逐步完成，大致包括以下内容。
| 学习阶段 | 主要内容 | 最终要回答的问题 |
|---|---|---|
| 1. 模型调用与第一个 Tool | Chat Completion、错误、成本、库存查询、Tool Schema | 模型怎样可靠地接触业务数据？ |
| 2. Agent Loop 与工具可靠性 | 多工具、运行循环、参数校验、故障注入、重试、超时、幂等和熔断 | Agent 怎样行动，并在失败时安全恢复？ |
| 3. 上下文与执行轨迹 | 对话记忆、长期记忆、上下文裁剪、Tracing 与 Trajectory | Agent 怎样记住必要信息，并解释自己走过的路径？ |
| 4. 规划、评估与安全 | 多步骤报价、Golden Dataset、回归测试、权限、人工审批、Checkpoint 和 Metrics | 怎样证明它做对了，并限制它不能做的事？ |
| 5. 系统化与生产部署 | Multi-Agent、企业系统、MCP、框架对照和生产可靠性架构 | 一个教学 Agent 怎样演进成可运营的系统？ |
关于进阶主题与生产环境
这条主线首先是一套 Agent 入门教程。它会带你认识模型调用、Tool、Agent Loop、错误处理、评估和安全边界，帮助你建立一副完整但尽量简单的骨架。真正深入以后，Context Engineering（上下文工程）、Memory（记忆） 和 RAG（检索增强生成） 都是足以单独展开的主题：上下文工程研究应该在什么时候把哪些信息交给模型，Memory 研究如何保存并再次使用过去的信息，RAG 则让系统先从外部知识库检索资料，再让模型依据检索结果回答。
这些能力会在主线案例需要时出现，但这里不会假装用几篇入门文章就能讲透。后续我们会考虑为它们分别设计更完整的专题，从最小问题出发，继续通过代码、失败实验和评估逐步展开。
Agent 真正进入生产环境后，最重要的课题之一是可靠性。不过，可靠性不是一张可以原样复制到所有项目里的功能清单：只读知识问答可能更关心资料是否准确、是否过期；库存和报价系统还要关注参数校验、权限与审计；能够修改数据或执行交易的 Agent，则需要更严格的幂等、审批、状态恢复和风险控制。
本教程会讲解这些通用机制，以及怎样主动发现失败、限制影响并验证改进。但最终采用哪些措施、做到什么程度，仍然必须结合具体业务的错误代价、外部依赖、数据敏感度、响应时间和合规要求来设计。生产级 Agent 的可靠性来自对真实场景的持续验证，而不是简单堆叠框架和组件。
适合谁
这套课程适合已经能读懂基础 Python，希望真正理解 Agent 怎样工作的人。你不需要提前使用过 LangChain、LangGraph 或其他 Agent 框架；课程前半段会先手写关键机制，后面再用成熟框架重做并比较取舍。
如果你只想找到一个可以复制粘贴的聊天机器人示例，这条路线可能显得太慢。但如果你想知道系统为什么失败、怎样恢复，以及如何用证据判断它是否可靠，那么从最小调用开始会让后面的每一层复杂度都有来处。