AI Agent Engineering · Week 03
03-04|实战:让 Agent 查询订单与物流
完成 Support Agent V0.3:通过受控订单与物流 Tool 获取事实,覆盖授权、超时、空结果和畸形结果。
Business Goal
客户询问订单和物流时,Agent 要从受控业务能力取得事实,再用客户语言回复。当前使用教学 Mock 或项目已有安全数据源,不连接生产 Shopify,也不执行退款、取消或改地址。
完成后得到 Support Agent V0.3:至少能查询订单和物流,并在六类 Tool Failure 下安全停止、追问或升级。
Current Architecture
Customer → Intent V0.1 → Loop Runtime V0.2
├─ order mock
└─ tracking mock
模拟动作尚未形成正式 Tool Schema、授权边界和统一 Failure Contract。
This Lesson Change
Codex Task
把 V0.2 的 order/tracking mock actions 升级为两个正式查询 Tools:
get_order_summary 与 get_tracking_status。
要求:
- 使用严格参数 Schema;模型只传 orderId 或 trackingId。
- tenantId/customerId 从可信 Run Context 注入。
- 使用教学 Mock 或项目已有安全数据源;禁止连接生产 Shopify。
- 统一返回 ok/data 或 ok/error/source/requestId。
- 覆盖 invalid_input, not_found, unauthorized, timeout,
empty_result, malformed_result。
- timeout 最多重试一次;unauthorized 立即停止。
- Tool 失败后不得生成不存在的订单或物流事实。
- 保留 V0.2 的 max turns、Trace 和 Stop Reason。
实现前报告文件范围和数据契约;实现后运行全部验证。
Tool Definitions
get_order_summary
{
"input": { "orderId": "XB-1024" },
"serverContext": { "tenantId": "trusted", "customerId": "trusted" },
"success": {
"status": "shipped",
"trackingId": "TR-7",
"updatedAt": "2026-10-17T08:30:00Z"
}
}
返回中不包含付款卡、完整地址、其他客户信息或内部风控字段。
get_tracking_status
{
"input": { "trackingId": "TR-7" },
"success": {
"carrierStatus": "in_transit",
"eta": "2026-10-20",
"updatedAt": "2026-10-17T09:00:00Z"
}
}
如果事件为空,返回 empty_result;如果上游结构缺字段,返回 malformed_result,不能由模型补齐。
Expected Inputs / Outputs
XB-1024 → shipped → TR-7 → in_transit
STOP: completedorderId=null → ask customer
STOP: need_inputXB-404 → no authorized match
STOP: clarify / completedorder belongs to another customer
STOP: stoppedcarrier timeout twice
STOP: escalatedcarrier returns no events
STOP: completed with no-data explanationTest Cases
测试分成四层:
- Schema: 正确参数、缺参数、错误类型、额外字段、超长 ID。
- Authorization: 正确客户、其他客户、其他租户、缺可信会话。
- Tool Result: 正常、not found、timeout、empty、malformed。
- Agent Trace: 正常两工具路径、缺订单号、未授权停止、超时升级、失败后禁止猜测。
至少断言:
- Runtime 查询条件同时包含 tenantId、customerId 与 orderId。
- 模型无法通过 Tool 参数覆盖可信身份。
- 订单结果中的 trackingId 才能进入物流 Tool。
- timeout 计数与 max turns 都生效。
- final response 中的状态、ETA 和更新时间能追溯到 Tool Result。
not_found不透露订单是否存在于其他授权范围。
Failure Lab
把 Mock 数据写进 Prompt
为什么诱人: 不需要 Tool handler,也能让模型“查询”。
为什么失败: 数据与指令混在一起,无法测试权限、超时和动态更新。
更好的设计: Mock 仍通过正式 Tool 接口返回,后续替换数据源时保持契约。
先查物流,再验证订单归属
为什么诱人: 客户已经提供 trackingId。
为什么失败: 物流号也可能属于其他客户,绕过订单授权链。
更好的设计: 从授权订单取得可信 trackingId,或为直接物流查询设计等价授权机制。
Tool 失败后给一个“可能状态”
为什么诱人: 客户总能收到看似有帮助的回答。
为什么失败: 猜测会变成业务承诺,客服无法追溯来源。
更好的设计: 说明已知失败、最后可用更新时间和下一步,不补写事实。
Acceptance Criteria
- ☐ 两个 Tool 都有 strict Schema 和最小输出。
- ☐ 身份与租户由 Runtime 注入并在服务端强制校验。
- ☐ 正常路径按订单 Tool → 物流 Tool 顺序取得事实。
- ☐ 六类失败均有测试和预定恢复路径。
- ☐ unauthorized 立即停止;timeout 最多重试一次。
- ☐ empty 与 malformed 结果不会被当成正常物流状态。
- ☐ final response 的每项业务事实都能追溯到 Tool Result。
- ☐ Trace 区分 model decision、tool call、tool result 与 stop reason。
- ☐ 未连接生产 Shopify,未开放任何资金或订单修改动作。
- ☐ 类型检查、lint、测试与 production build 通过。
Architecture After This Lesson
Customer + Trusted Identity
↓
Intent V0.1
↓
Agent Loop V0.2
↓
Runtime Validation + Authorization
↙ ↘
Order Tool Tracking Tool
Mock / safe source Mock / safe source
↘ ↙
Verified Response + Trace V0.3
主动回忆
- V0.3 中四层职责分别是什么?
- 为什么身份不能由 Tool Schema 让模型填写?
- 正常订单查询为什么要先于物流查询?
- 哪六类失败必须有不同路径?
- 怎样证明最终回复没有猜测工具失败后的事实?
Week 03 完成。下一阶段将处理 API 与 MCP 的连接方式:Tool Contract 保持稳定,底层能力可以通过直接 API 或标准化协议接入,但任何连接都不会自动授予业务权限。
延伸阅读 / Sources
核查日期:2026-10-17。
- OpenAI API:Function calling。用于核对完整 Tool Calling 流程、严格参数 Schema 与工具设计原则。
- OpenAI Agents SDK:Tools。用于核对函数工具的定义、执行与错误处理。
- OWASP:Authorization Cheat Sheet。用于核对服务端授权、默认拒绝和每次请求校验原则。
长期有效的原理: Tool Contract 与数据源解耦,身份在服务端校验,失败后没有证据就不生成事实。当前实现方式: 本批使用安全 Mock;接真实平台前必须重新完成授权、字段映射、限流和沙箱验收。