AI Agent Engineering · Week 02
02-04|为什么有了 Agent SDK 还要理解 Loop
看懂 Agent SDK 接管的 Runtime 工作和仍需自行负责的业务边界,避免把框架默认值当成系统设计。
三行 SDK 代码背后运行了多少事
一个 Agent SDK 可能让你定义 instructions、tools,再调用 run()。表面上没有 while,循环依然存在:模型返回工具请求,Runtime 执行或交给你的处理器,把结果放回上下文,再次调用模型,直到最终输出或触发上限。
理解 Loop 能让你判断 SDK 的默认行为是否符合业务。否则,工具为什么重复调用、错误为什么被转成文本、Trace 为什么含敏感数据,都只能靠猜。
Manual Loop 与 SDK Runtime
- 自己组装每次模型输入
- 自己派发工具
- 自己追加结果
- 自己实现轮数、错误和 Trace
- 管理模型与工具往返
- 维护 run items / state
- 提供 max turns、tracing、hooks
- 统一部分异常与结果
SDK 通常替你接管什么
- 把 instructions、input、tools 发送给模型。
- 识别 final output、tool calls 或 handoff。
- 调用已注册的本地工具处理器。
- 把 tool output 与 call ID 放回下一轮。
- 管理 turn 上限和部分运行异常。
- 生成 Trace、用量和运行结果对象。
- 提供 session、guardrail、approval 等可选能力。
这些能力减少重复 Runtime 代码。它们属于当前实现方式,具体名称和默认值会随 SDK 版本变化。
SDK 不能替你决定什么
什么业务状态算完成
谁可以读取哪家店、哪位客户的数据
输入、输出、错误和副作用
哪些错误可重试、重试几次
哪些动作必须由谁批准
哪些测试和证据才允许上线
用 Loop 知识阅读 SDK
看到 SDK 文档时,按六个问题阅读:
| Loop 问题 | 要在 SDK 中确认 |
|---|---|
| 输入如何进入每轮? | instructions、input、history 的组合方式 |
| 工具请求怎样识别? | function/tool call 的结果类型 |
| 谁实际执行工具? | 本地函数、托管工具或远端服务 |
| 工具结果怎样返回? | call ID、result item、下一轮 Context |
| 什么让运行停止? | final output、stop-on-tool、max turns、异常 |
| 失败怎样暴露? | exception、error item、hook、Trace |
如果某项回答不出来,先用最小示例和 Trace 验证,避免把猜测带进业务代码。
从 V0.2 手写 Loop 迁移到 SDK
循环胶水、工具派发、结果封装、基础 Trace。
动作白名单、max turns、错误策略、事实来源、测试期望。
默认重试、Context 保存、敏感 Trace、并行工具与停止语义。
可以让 Codex 做一项对比实验:保持同一组 Mock Tools 和测试用例,分别运行手写 Loop 与 SDK Runtime。比较最终状态、调用次数、错误出口和 Trace。只有行为差异被解释后再选择实现。
Failure Lab
把 SDK 默认值当成业务策略
为什么诱人: 开箱即用,示例能跑。
为什么失败: 默认 max turns、工具错误行为和 Trace 数据可能不符合你的风险要求。
更好的设计: 列出关键默认值,显式配置并用失败测试验证。
SDK 抛错后统一回复“请稍后再试”
为什么诱人: 错误处理简单。
为什么失败: 未授权、超时、行为错误和模型拒绝需要不同的记录和恢复。
更好的设计: 在业务边界把 SDK 异常映射成稳定错误类型,保留安全诊断信息。
为了用 SDK 加入不需要的多 Agent
为什么诱人: 框架已经提供 handoff 和 agents-as-tools。
为什么失败: 项目尚未证明拆分收益,额外交接增加 Context 和调试成本。
更好的设计: 当前 V0.2 保持单 Agent;只有独立边界与评估证据出现后再拆分。
实践:制作 Runtime Responsibility Matrix
选择你准备使用的 Agent SDK,阅读其官方 Running、Tools 和 Errors 文档。把 V0.2 的每项责任标记为“SDK 管理”“应用管理”“共同管理”,并为共同管理项写一条验证方法。
Acceptance Criteria
- ☐ 能把 SDK 行为映射回 Observe / Decide / Act / Stop。
- ☐ 列出 SDK 接管的至少五项 Runtime 工作。
- ☐ 列出应用仍负责的至少五项业务边界。
- ☐ 明确 max turns、tool error 和 Trace 敏感数据配置。
- ☐ 使用同一测试集比较手写 Loop 与 SDK Runtime。
- ☐ 所有行为差异都有解释和接受决定。
- ☐ 没有因为 SDK 提供某功能就自动启用 Multi-Agent。
合上正文,试着回答
- SDK 隐藏
while后,Loop 为什么仍然存在? - SDK 可以管理工具执行,为什么仍不能决定工具权限?
- 迁移 SDK 时哪些 V0.2 约束必须保持?
- 怎样发现 SDK 默认错误行为与业务要求冲突?
- 什么时候直接使用 Responses API 更合适,什么时候 SDK 更合适?
Week 02 到这里完成。下一周把模拟动作升级为正式 Tool,先从最基础的问题开始:Tool 是给模型的能力描述、给 Runtime 的执行入口,还是业务系统本身?
延伸阅读 / Sources
核查日期:2026-10-17。
- OpenAI Agents SDK:Overview。用于核对 Agents、Tools、Guardrails、Sessions 与 Tracing 等 Runtime 能力。
- OpenAI Agents SDK:Running agents。用于核对 Runner 的 Agent Loop、max turns 和工具结果处理。
- OpenAI API:Agents。用于核对 Responses API、Agents SDK 与托管 Agent Runtime 的选型边界。
长期有效的原理: SDK 封装运行机制,业务责任仍由应用定义与验证。当前实现方式: 类名、异常和默认值会随版本变化,升级前需运行同一回归测试集。