跳到主要内容
← 返回AI Agent Engineering|12 周从 Demo 到真实 Agent 系统

AI Agent Engineering · Week 02

02-04|为什么有了 Agent SDK 还要理解 Loop

看懂 Agent SDK 接管的 Runtime 工作和仍需自行负责的业务边界,避免把框架默认值当成系统设计。

Agent SDK · Runtime · Agent Loop

三行 SDK 代码背后运行了多少事

一个 Agent SDK 可能让你定义 instructions、tools,再调用 run()。表面上没有 while,循环依然存在:模型返回工具请求,Runtime 执行或交给你的处理器,把结果放回上下文,再次调用模型,直到最终输出或触发上限。

理解 Loop 能让你判断 SDK 的默认行为是否符合业务。否则,工具为什么重复调用、错误为什么被转成文本、Trace 为什么含敏感数据,都只能靠猜。

Manual Loop 与 SDK Runtime

Manual Loop
  • 自己组装每次模型输入
  • 自己派发工具
  • 自己追加结果
  • 自己实现轮数、错误和 Trace
透明、可定制,胶水代码更多。
SDK Runtime
  • 管理模型与工具往返
  • 维护 run items / state
  • 提供 max turns、tracing、hooks
  • 统一部分异常与结果
开发更快,仍需理解默认策略。
图 1|SDK 封装循环机制,没有替你定义业务完成、权限和风险边界。

SDK 通常替你接管什么

  • 把 instructions、input、tools 发送给模型。
  • 识别 final output、tool calls 或 handoff。
  • 调用已注册的本地工具处理器。
  • 把 tool output 与 call ID 放回下一轮。
  • 管理 turn 上限和部分运行异常。
  • 生成 Trace、用量和运行结果对象。
  • 提供 session、guardrail、approval 等可选能力。

这些能力减少重复 Runtime 代码。它们属于当前实现方式,具体名称和默认值会随 SDK 版本变化。

SDK 不能替你决定什么

Goal

什么业务状态算完成

Authority

谁可以读取哪家店、哪位客户的数据

Tool Contract

输入、输出、错误和副作用

Retry Policy

哪些错误可重试、重试几次

Approval

哪些动作必须由谁批准

Acceptance

哪些测试和证据才允许上线

图 2|框架拥有运行能力,业务系统拥有责任边界。

用 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、并行工具与停止语义。

图 3|迁移 SDK 的验收标准是行为等价或有证据的改进,不是代码行数变少。

可以让 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。

合上正文,试着回答

  1. SDK 隐藏 while 后,Loop 为什么仍然存在?
  2. SDK 可以管理工具执行,为什么仍不能决定工具权限?
  3. 迁移 SDK 时哪些 V0.2 约束必须保持?
  4. 怎样发现 SDK 默认错误行为与业务要求冲突?
  5. 什么时候直接使用 Responses API 更合适,什么时候 SDK 更合适?

Week 02 到这里完成。下一周把模拟动作升级为正式 Tool,先从最基础的问题开始:Tool 是给模型的能力描述、给 Runtime 的执行入口,还是业务系统本身?

延伸阅读 / Sources

核查日期:2026-10-17。

长期有效的原理: SDK 封装运行机制,业务责任仍由应用定义与验证。当前实现方式: 类名、异常和默认值会随版本变化,升级前需运行同一回归测试集。