00 从零手写 Agent 路线图

Agent 框架两年里冒了一茬又一茬：LangGraph、Claude Agent SDK、AutoGen……选型对比看多了，一个朴素的事实反而被盖住——Agent 的核心不依赖任何框架。一个模型 API、一份工具清单、一个 while 循环，三百行以内的 Python 就能写出一个能干活的 Agent。本系列共 13 篇，立场只有一条：不引框架，从裸 HTTP 请求开始，把 Agent 从零到一亲手写出来。

本文是第 0 篇路线图：先给 Agent 一个能落地的定义，盘清手写需要的全部零件并跑通第一个脚本，再把 13 篇的完整地图摊开，最后给出读法建议。

1、为什么从零手写

框架解决的是"快"，代价是"看不见"。用 SDK 三行代码调起大模型，用 LangGraph 十行代码建一张图，都很快；可一旦出问题——账单莫名暴涨、循环不终止、工具结果没进上下文——没读过协议层的人，只能在框架的配置项里挨个试。

框架的更替速度也值得一算：今天选定的框架，半年后大概率已在重写 API；协议层的 JSON 却稳得多——messages 数组、stop_reason、事件流，这些字段几年没有大变。把理解建立在协议上，框架的更替就只是换一层皮。

手写一遍的收益集中在三处：

• 排障：错误发生在 HTTP 层还是循环逻辑，一眼定位
• 选型：知道框架替你做了什么，才知道何时不需要它
• 成本：账单上的每一个 token 都能对上一行代码

这三条收益会在系列里反复兑现：第 2 篇算清记忆的账单，第 7 篇治理上下文膨胀，第 11 篇拿手写版与官方 SDK 对账——每一篇都在还这里许下的愿。

1.1、框架遮住了什么

剥到协议层，一切 Agent 框架都是同两样东西：一个 messages 列表装着全部历史，一个 while 循环驱动模型与工具交替工作。LangGraph 的图、Claude Agent SDK 的会话，最终都落回这对组合——这不是比喻，第 11、12 篇会拿框架逐项对账。

看不见这层的人，把框架当黑盒崇拜；看清这层的人，把框架当工具挑拣。差距不在天赋，在有没有亲手写过一遍。

2、Agent 的最小定义

扔掉所有营销词，Agent 可以落成一句话：接收任务后，循环执行"模型推理 + 工具调用"，直到任务完成并给出答案的程序。拆开是三个零件：模型是脑，工具是手，循环是心脏。

一轮工作的完整流向如下：

图里最要紧的是"结果写回历史"指向"模型思考"的那条回边：工具结果不是给用户看的，是写回对话历史、喂给模型做下一轮决策的。模型每一步都基于"任务加已发生的全部"重新决策，这是 Agent 与"一问一答"的本质区别。

2.1、循环是心脏

全系列的核心循环长什么样，先睹为快：

while response.stop_reason == "tool_use":
    results = execute_tools(response)      # 执行模型点名的工具
    history.append_tool_results(results)   # 结果写回对话历史
    response = call_model(history)         # 带着新历史再问模型

三行代码，是 Claude Code、LangGraph 以及一切 Agent 框架共同的心脏。stop_reason 等于 tool_use 表示模型说"我要用工具"，循环再转一圈；模型说完了，循环自然停止。第 5 篇会把这三行扩成完整实现，此处记住形状即可。

2.2、什么不是 Agent

定义的反面同样有用。单次调用不是 Agent——一问一答没有循环，谈不上"完成任务"；固定流程的管线也不是——步骤写死在代码里，模型没有决策权，只是一个贵一点的文本变换函数。判断标准就一条：下一步做什么，是代码写死的，还是模型看着历史决定的。前者是工作流，后者才是 Agent。

工作流并非低级——大量生产场景用固定管线更稳、更便宜、更好测试，硬套 Agent 反而是浪费。第 12 篇做选型收束时，这个区分会反复出现：先问任务需不需要模型决策，再决定要不要 Agent。

3、手写前的零件清单

手写 Agent 不需要 GPU，不需要机器学习基础，零件只有四样：Python 3.10 以上、httpx 库、一个兼容 Anthropic Messages 协议的端点、一把 API key。官方 API 与各家兼容网关（如智谱开放平台）均可，系列代码在两者之间不改一行。

安装依赖只要一条命令：

pip install httpx python-dotenv

httpx 负责发 HTTP 请求，python-dotenv 负责从 .env 文件读密钥——密钥永远不进代码、不进 git。.env 模板如下：

ANTHROPIC_BASE_URL=https://你的兼容端点地址
ANTHROPIC_API_KEY=你的密钥

零件是否齐全，用一个连通性自检脚本验证。这是全系列第一个能跑的程序：

import os
import sys
import httpx
from dotenv import load_dotenv

sys.stdout.reconfigure(encoding="utf-8")   # Windows 控制台中文防乱码
load_dotenv(override=True)                 # 防预设同名变量覆盖，第 1 篇展开

response = httpx.post(
    os.environ["ANTHROPIC_BASE_URL"] + "/v1/messages",
    headers={
        "x-api-key": os.environ["ANTHROPIC_API_KEY"],
        "anthropic-version": "2023-06-01",
        "content-type": "application/json",
    },
    json={
        "model": "glm-4.6",
        "max_tokens": 64,
        "messages": [{"role": "user", "content": "只回复四个字：零件齐全"}],
    },
    timeout=60,
)
print(response.status_code, response.json()["content"][0]["text"])

实测记录（一次真实运行）的输出如下：

200 零件齐全

状态码 200 加上模型回话，四样零件全部就位。脚本里两行防御性代码不是玄学：中文 Windows 的 GBK 编码与预设环境变量，是新手最先撞上的两个坑，第 1 篇的踩坑实录会完整解剖它们。整个系列写完，核心代码不过三百行——没有一处需要框架。

代码组织上，系列的全部代码都在一个 agent.py 里逐步生长：第 2 篇加历史管理，第 5 篇长出循环，第 6 篇挂上工具，第 7 篇接上持久化。每篇结束你手里都有一个能跑的完整版本——这比散落十几个互不相干的示例文件的教程，好维护也好复习得多。

开工前还有两笔账要心里有数。预算上，本系列每篇实验的开销在几分到几毛钱量级——用 max_tokens 卡住输出、用便宜模型跑通流程，是大模型开发的通用省钱姿势，第 1 篇会把这笔账算到字段级。安全上，密钥只放 .env 并确认它已进 .gitignore；到第 6 篇给 Agent 装上文件与代码执行工具后，安全边界会升级成一个专门话题。

4、十三篇路线图

13 篇各写一块拼图，完整地图如下：

4.1、协议层三篇

第 1 到 3 篇只做一件事：看清协议。请求体、响应体、错误体、事件流，全部用裸代码拆开看一遍。这三篇没有任何 Agent 功能，却是后面所有篇目的地基——第 4 篇之后的每一个"玄妙机制"，拆开都是这三篇里的 JSON 字段。

这三篇还顺手把开发环境里最常见的坑清掉：环境变量覆盖、Windows 编码、企业代理，后面所有篇目默认它们不再是问题。

4.2、Agent 核心四篇

第 4 到 7 篇把 Agent 组装出来：工具调用让模型长出手，循环让它连续工作，真实工具让它能碰文件系统，上下文管理让它干长活不死机。写完第 7 篇，你手里是一个完整可用的 Agent——它可能只有两百行，但每一个 token 的去向你都清楚。

这四篇也是系列里实验最密集的部分：你会亲眼看到模型点错工具、循环停不下来、上下文爆掉，修复它们的经验与生产环境的事故一一对应。

4.3、进阶与收官五篇

第 8 到 12 篇向外扩：子 Agent 解决上下文隔离，RAG 接上私有知识，结构化输出与评估补上工程化的两条腿；最后两篇请出 Claude Agent SDK 与 LangGraph，拿手写版逐项对账，回答"框架到底替你做了什么、值不值得用"。手写在先、对账在后，得出的选型结论才有分量。

评估篇值得工程背景的读者格外期待：它是把"感觉变好了"变成数字的唯一途径，没有它，前面所有优化都只是印象。

5、怎么读这个系列

三点读法建议。其一，按序读收益最大：每篇只引入一个新概念，跳读会撞上没铺垫的术语。其二，代码亲手敲一遍再跑：本系列所有脚本都在一个兼容端点上实测过，数字口径注明"实测记录"，换任何兼容端点结论不变。其三，把每篇的实验做掉：失忆实验、伪造历史、并行派工，这些破坏性操作建立的理解，比十遍正向演示都深。

前置知识只要两样：Python 基础语法，以及"HTTP 请求大致是什么"的常识。涉及框架的对比篇会给出官方文档入口，如 LangGraph 文档与 Claude Agent SDK 文档，不需要预先读过。

两个常见疑问先给定性答案。其一，需要多强的模型？协议层的篇目用任意能跑的模型即可；从第 4 篇工具调用起，模型能力开始影响成败——弱模型会点错工具、编错参数，这是实测里会反复撞上的现象，也正好是观察模型差异的窗口。其二，一共要花多少钱？跟着做完全部实验，成本大约等于一杯咖啡，前提是每篇先用小 max_tokens 跑通流程，再放大做实验。

6、总结

Agent 是模型、工具、循环三个零件的组合，核心代码三百行以内，不需要任何框架；手写一遍换来排障、选型、成本三方面的主动权。本系列 13 篇按"协议层、Agent 核心、进阶与收官"三段推进，每篇带可跑代码与实测记录。对于准备出发的读者，建议先把本文第 3 节的自检脚本跑通、确认零件齐全，再进入第 1 篇：大模型 API 的真相——丢开 SDK，用 httpx 裸发第一次请求。httpx 用法见 官方文档，端点与模型选型参考 智谱开放平台与 Anthropic 文档。