AI Agent Engineering · Week 02
02-03|实战:构建最小 Agent Loop
让 Codex 实现带动作白名单、Trace、max turns 与错误出口的最小 Agent Loop,完成 Support Agent V0.2。
Business Goal
V0.1 能识别 order_tracking,但缺订单号时只能返回一条结构化结果。本课让系统根据当前状态选择追问、模拟查询、回复或升级,并在明确边界内停止。
完成后得到 Support Agent V0.2:一个可运行、可追踪、不会无限执行的最小 Agent Loop。订单与物流仍使用模拟结果,真实 Tool 留到 Week 03。
Current Architecture
Customer Message
↓
Prompt Contract + LLM
↓
Schema Validation
↓
Structured Intent V0.1
This Lesson Change
↓
Loop Runtime
Observe → Decide → Validate Action → Execute Mock → Append Result
↺
Stop Gate
final · need_input · escalated · error · max_turns
Codex Task
在现有项目约定内实现最小 Support Agent Loop。
Goal:
对物流查询收集 orderId,执行模拟订单/物流动作,并生成有来源的结果;无法完成时显式停止。
Allowed actions:
- ask_for_order_id
- lookup_order_mock
- lookup_tracking_mock
- final_response
- escalate
Runtime requirements:
- 每个 action 使用结构化参数并校验。
- 只执行白名单动作。
- 工具结果带 source、status、data/error。
- 每轮记录 turn、decision、action、result、stop reason。
- 默认 maxTurns=6;重复同一失败动作两次后停止。
- unauthorized 立即停止;timeout 最多重试一次。
- 不接生产订单系统,不执行退款。
先检查仓库并报告最小文件方案;实现后运行测试、类型检查、lint 和 build。
最小 Loop 核心
下面是值得理解的接口轮廓,具体 SDK 调用由 Codex 按项目实现:
type RunState = {
turn: number;
observations: Observation[];
trace: TraceItem[];
status: "running" | "need_input" | "completed" | "escalated" | "failed";
};
while (state.status === "running" && state.turn < maxTurns) {
const decision = await decide(goal, state.observations, allowedActions);
const action = validateAction(decision);
const result = await executeMock(action);
state = appendAndCheckStop(state, decision, action, result);
}
这里没有展示模型供应商的全部请求字段,也没有把错误处理藏起来。关键责任是:Decision 先校验,Action 由 Runtime 执行,Result 进入 State,Stop Check 每轮发生。
Expected Inputs / Outputs
| 场景 | 输入 | 期望终态 |
|---|---|---|
| 缺订单号 | “Where is my order?” | need_input,追问订单号 |
| 正常查询 | “Track XB-1024” | completed,回复引用模拟物流事实 |
| 订单不存在 | “Track XB-404” | completed 或 escalated,明确未找到,不编状态 |
| 未授权 | 当前客户请求他人订单 | failed / escalated,立即停止 |
| 物流超时 | 模拟连续 timeout | 重试一次后 escalated |
| 行为错误 | 模型请求未知动作 | 有限重试后 failed |
Test Cases
至少覆盖:正常四轮 Trace、缺订单号暂停、非法 action、参数缺失、未授权、一次超时后成功、连续超时、达到 max turns、重复动作检测、final response 引用不存在事实。
模型端到端结果可能有表达差异,Runtime 断言应关注动作类型、状态、来源和停止原因;不要用整段文本完全相等作为唯一测试。
执行 Trace 验收
- T1 observe order_tracking + orderId XB-1024 → lookup_order_mock
- R1 source=order_mock · status=ok · trackingId=TR-7
- T2 observe verified trackingId → lookup_tracking_mock
- R2 source=tracking_mock · status=ok · state=in_transit
- T3 goal satisfied → final_response
- STOP reason=completed · turns=3
Failure Lab
为了测试方便绕过 Action Validation
为什么诱人: Mock 数据可信,直接执行更快。
为什么失败: 真实 Tool 接入后,同一个漏洞会允许错误参数进入业务系统。
更好的设计: Mock 与生产 Tool 共用动作和结果契约,测试从第一天覆盖校验边界。
只记录最终回复
为什么诱人: 日志更短。
为什么失败: 无法知道错误来自哪个决策、动作或结果,max turns 也无法解释。
更好的设计: Trace 记录必要元数据和脱敏结果;不要在日志里复制密钥或完整客户隐私。
超时后让模型决定重试次数
为什么诱人: 模型可以“灵活判断”。
为什么失败: 重试预算属于系统可靠性策略,可能导致成本失控。
更好的设计: Runtime 设置次数和退避,模型只在重试失败后选择安全回复或升级。
Acceptance Criteria
- ☐ 只存在五类批准动作,未知动作无法执行。
- ☐ 每个动作参数经过结构校验。
- ☐ 每个模拟结果带 source、status 和 data/error。
- ☐ 正常路径可输出完整 Trace,并在 Goal 满足后停止。
- ☐ 缺客户输入时状态为
need_input,不会后台空转。 - ☐ 未授权立即停止,timeout 最多重试一次。
- ☐ 达到 6 轮或重复失败动作时安全结束。
- ☐ 最终回复只引用 Trace 中有来源的事实。
- ☐ 自动测试、类型检查、lint 和 build 通过。
Architecture After This Lesson
Customer
↓
Intent V0.1
↓
Loop Runtime V0.2
├─ ask_for_order_id
├─ lookup_order_mock
├─ lookup_tracking_mock
├─ final_response
└─ escalate
↓
Trace + Stop Reason
主动回忆
- V0.2 相比 V0.1 增加了哪三类工程责任?
- 为什么 Mock 也必须遵守正式 Tool 契约?
- Trace 至少要记录什么?
- 哪些停止条件由 Runtime 强制?
- 为什么端到端测试不能只比较最终文字?
下一课会比较手写 Loop 与 Agent SDK:SDK 可以接管许多 Runtime 工作,但边界、错误策略和验收责任仍要由工程师定义。
延伸阅读 / Sources
核查日期:2026-10-17。
- OpenAI Agents SDK:Running agents。用于核对 Agent Loop、工具执行、结果回传和 max turns。
- OpenAI Agents SDK:Tracing。用于核对一次运行的 Trace 与敏感数据配置。
- OpenAI API:Function calling。用于核对工具调用的请求、执行和回传步骤。
长期有效的原理: 决策、执行、结果和停止原因必须可分辨、可测试。当前实现方式: 课程可用任意兼容 SDK 或手写 Runtime,接口细节以项目锁定版本为准。