Appearance
07 — 框架实战
这一章不把框架当成名词表，也不要求你先下载一个完整项目。我们选一个很小、但足以暴露真实问题的企业服务台案例，边读边写几段代码：先让模型回答，再让它调用工具，接着处理分支、失败和人工确认，最后分别用 LangGraph 和 Agent SDK 重写同一条流程。
你可以把每一小段代码复制到自己的练习目录中，手动运行后再改动它。文档会告诉你这一段要观察什么、为什么这样写，以及下一步可以故意改坏哪里。真正的目标不是记住某个框架的 API，而是知道框架替你接管了哪一段控制流。
先看路线
| 顺序 | 文章 | 这一篇要亲手写出的东西 | 开始前需要什么 |
|---|---|---|---|
| 1 | 裸 API 手写 Agent | 消息历史、工具 schema、工具调用循环、错误处理和流式输出 | 会发起一次模型调用，知道 JSON 和环境变量 |
| 2 | LangGraph | 把刚才的循环拆成状态、节点、条件边，并加入暂停与恢复 | 已跑通裸 API 版本，能说清每一轮消息怎么变化 |
| 3 | Agent SDK（官方框架） | 用 Agent、Runner、工具和 tracing 重写同一个任务 | 理解裸 API 和 LangGraph 各自负责什么 |
完整的阅读说明、练习顺序和带答案的学习清单，统一放在框架实践入口。
贯穿案例：企业服务台助手
三篇文章都围绕同一个小助手，不换题目，才能看出代码结构为什么变化。它只提供三个本地模拟能力：
- 知识库查询：回答“VPN 怎么配置”“报销发票有什么要求”这类制度问题，并返回文档标题和更新时间。
- 工单查询：根据用户编号查看自己的工单状态。
- 创建工单：提交问题摘要和优先级。这是有副作用的操作，必须先检查权限，再等待人工确认。
例如，用户先问“我连不上公司的 VPN，应该怎么办？”，模型可以直接根据知识库回答；用户接着说“顺便查一下我上周的工单”，模型需要调用查询工具；用户再说“帮我开一个高优先级工单”，程序必须停下来确认，而不是因为模型说了“请创建”就直接写入系统。
案例中的数据可以先用几条字典或 JSON 假数据代替。这样你能专注于控制流，等流程理解后，再把工具函数换成真实 HTTP 请求。文章不会把完整项目塞给你；你需要自己决定文件怎么拆、错误怎么返回，这正是练习的一部分。
每一篇都这样读
- 先读本节目标，只准备完成当前目标所需的最小代码，不要提前搭完整 Agent。
- 在自己的练习目录新建一个文件，例如
framework-playground/step-01.py。每完成一个明显的阶段就另存一个文件，方便比较“改动前”和“改动后”。 - 复制文档中的短代码片段，补上注释里要求你思考的部分，然后运行它。先看消息、工具参数和终止条件，再看最终答案是否漂亮。
- 按“动手改一改”里的问题改一次代码。改坏了也没关系，保留终端输出，回到上一份文件比较差异。
练习目录放在仓库外更合适，例如 ~/framework-playground；如果你想放在仓库里，也请单独建一个临时目录，不要把个人 API Key 写进文档或提交到 Git。每篇文章都会说明需要安装的最小依赖、环境变量名和可以使用的 Mock 方式，但运行位置由你自己决定。
这一章要形成的判断力
- 能画出“用户输入 → 模型 → 工具 → 工具结果 → 模型”的消息流，并指出代码真正执行工具的地方。
- 能把一段塞满
if/else的循环拆成节点和边，同时知道图结构也会增加状态设计成本。 - 能看懂 SDK 的 Agent、Runner、Session、handoff 或 tracing 分别替代了裸写版本的哪部分代码。
- 遇到模型乱调工具、工具超时、上下文过长或流程卡住时，先检查状态和控制流，而不是只改提示词。
选框架的起点
任务只有一个模型、几个只读工具、没有暂停恢复时，裸 API 往往最容易维护；流程出现多个分支、循环、人工审批或断点续跑时，再考虑 LangGraph；希望快速接入工具、交接和运行追踪时，可以评估 Agent SDK。顺序不是等级排名，而是从最少的隐藏行为开始，逐步增加抽象。