框架实践

这里是一条可以边读边写的教程路线。每篇文章只增加一个关键概念，代码片段保持短小，你需要把它们复制到自己的练习文件中运行，再根据输出做修改。不要把文章当成一个需要一次性复制完成的项目；保留每一步的文件和终端输出，比较它们的变化，才能看见框架到底省掉了什么。

统一案例

核心教程都围绕“企业服务台助手”，只使用三类本地模拟工具：查询知识库、查询当前用户的工单、创建工单。前两类是只读操作，创建工单会产生副作用，必须经过权限检查和人工确认。你可以把模拟数据写成几条字典，等流程跑通后再替换成真实服务。

建议在仓库外准备一个练习目录：

framework-playground/
├── step-01-basic-call.py
├── step-02-tool-loop.py
├── step-03-langgraph.py
└── step-04-agent-sdk.py

文件名不是硬性要求。关键是每完成一个阶段就留一份可以运行的版本，不要直接覆盖上一阶段。文章中的代码默认从环境变量读取模型地址和密钥；没有密钥时，优先使用文中给出的 Mock 返回值完成控制流练习。

阅读顺序

顺序	文章	你会逐步写什么	前置关系
1	裸 API 手写 Agent	从一次模型调用开始，加入工具 schema、调用循环、错误结果、日志和流式输出	无；先准备 Python 和模型客户端
2	LangGraph	把裸循环拆成 state、model 节点、tool 节点和条件边，再加入分支与人工确认	必须先完成裸 API 的消息流
3	Agent SDK（官方框架）	用 Agent、Runner、工具注册和 tracing 重写同一个服务台任务	先比较裸 API 与 LangGraph 的控制边界
4	同一个任务，三种 Agent 写法	把三份代码放在一起比较，观察控制流、状态、失败恢复和调试信息的差异	完成前三篇的最小版本
5	框架实战递进练习	在已有代码上增加检索、分支、重试、人工确认，再做一次迁移和选型	完成前三篇，建议先读比较篇
6	流式回复中断后的恢复	保存已收到的片段，区分重连与续写，处理工具调用中断、幂等和恢复测试	至少完成裸 API 的流式输出
7	流式响应的生产级恢复	把生成任务、后台 Worker、事件日志和 SSE 订阅拆开，练习重放、多实例并发和故障演练	完成流式恢复篇，了解基本的 HTTP/SSE

如果只想了解概念，可以直接浏览；如果希望真正掌握，至少把第一篇的“直接回答”和“需要工具”两条路径跑通，再进入下一篇。

每一步的验证方式

• 看输入和输出：打印本轮发送的消息类型、工具名称和结构化参数，不要只看最后一句自然语言。
• 看控制流：确认工具由你的代码执行，工具结果以正确的调用标识回传，达到终止条件后才结束。
• 看异常路径：主动让工具返回空结果、参数错误和超时，确认程序不会无限重试或直接崩溃。
• 看安全边界：创建工单前必须停在确认点；拒绝或越权时，真实工具不能被调用。
• 看改写差异：同一个问题分别运行三个版本，比较消息历史、状态快照、节点路径、日志和代码中需要自己维护的部分。

完成后的自测

当你能不看答案完成下面三件事，这一章才算真正读完：

1. 用裸 API 让助手分别完成知识库查询、工单查询和直接回答，并能解释每条消息的作用。
2. 用 LangGraph 画出同一任务的节点和条件边，说明一次工具失败或人工拒绝会走哪条路径。
3. 用 Agent SDK 跑通同一组输入，列出它替你接管的代码，以及仍必须由业务代码负责的权限、幂等和错误边界。