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

AI Agent Engineering · Week 02

02-03|实战:构建最小 Agent Loop

让 Codex 实现带动作白名单、Trace、max turns 与错误出口的最小 Agent Loop,完成 Support Agent V0.2。

实战 · Agent Loop · 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

Structured Intent
↓
Loop Runtime
Observe → Decide → Validate Action → Execute Mock → Append Result
↺
Stop Gate
final · need_input · escalated · error · max_turns
图 1|V0.2 增加运行机制和停止状态,不增加真实业务权限。

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

2 条 End-to-End Trace
6 条 Runtime / Stop Policy Tests
Action Schema · Error Mapping · Mock Result 单元测试
图 2|大部分测试锁定确定 Runtime;少量端到端测试验证模型与循环组合。

至少覆盖:正常四轮 Trace、缺订单号暂停、非法 action、参数缺失、未授权、一次超时后成功、连续超时、达到 max turns、重复动作检测、final response 引用不存在事实。

模型端到端结果可能有表达差异,Runtime 断言应关注动作类型、状态、来源和停止原因;不要用整段文本完全相等作为唯一测试。

执行 Trace 验收

  1. T1 observe order_tracking + orderId XB-1024 → lookup_order_mock
  2. R1 source=order_mock · status=ok · trackingId=TR-7
  3. T2 observe verified trackingId → lookup_tracking_mock
  4. R2 source=tracking_mock · status=ok · state=in_transit
  5. T3 goal satisfied → final_response
  6. STOP reason=completed · turns=3
图 3|Trace 中要能区分模型决定、Runtime 执行和模拟事实来源。

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

主动回忆

  1. V0.2 相比 V0.1 增加了哪三类工程责任?
  2. 为什么 Mock 也必须遵守正式 Tool 契约?
  3. Trace 至少要记录什么?
  4. 哪些停止条件由 Runtime 强制?
  5. 为什么端到端测试不能只比较最终文字?

下一课会比较手写 Loop 与 Agent SDK:SDK 可以接管许多 Runtime 工作,但边界、错误策略和验收责任仍要由工程师定义。

延伸阅读 / Sources

核查日期:2026-10-17。

长期有效的原理: 决策、执行、结果和停止原因必须可分辨、可测试。当前实现方式: 课程可用任意兼容 SDK 或手写 Runtime,接口细节以项目锁定版本为准。