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

AI Agent Engineering · Week 03

03-04|实战:让 Agent 查询订单与物流

完成 Support Agent V0.3:通过受控订单与物流 Tool 获取事实,覆盖授权、超时、空结果和畸形结果。

实战 · Tool Calling · V0.3

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

1Customer → Agent“Where is order XB-1024?”
2Agent → Runtimerequest get_order_summary(orderId)
3Runtime → Order Toolinject tenant/customer; validate; execute
4Order Tool → Business Dataquery authorized order scope
5Result → Agentstatus=shipped, trackingId=TR-7, source=order_mock
6Agent → Tracking Toolget_tracking_status(TR-7)
7Result → Agentin_transit, ETA, updatedAt, source=carrier_mock
8Agent → Customerreply with verified facts and source time
图 1|模型选择调用;Runtime 注入可信身份并执行;业务数据产生事实。

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

Normal

XB-1024 → shipped → TR-7 → in_transit

STOP: completed
Missing ID

orderId=null → ask customer

STOP: need_input
Not found

XB-404 → no authorized match

STOP: clarify / completed
Unauthorized

order belongs to another customer

STOP: stopped
Timeout

carrier timeout twice

STOP: escalated
Empty

carrier returns no events

STOP: completed with no-data explanation
图 2|“成功结束”可以是明确说明没有数据;它不等于每次都查到物流。

Test Cases

测试分成四层:

  1. Schema: 正确参数、缺参数、错误类型、额外字段、超长 ID。
  2. Authorization: 正确客户、其他客户、其他租户、缺可信会话。
  3. Tool Result: 正常、not found、timeout、empty、malformed。
  4. 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

图 3|V0.3 能查询事实,但权限仍由 Runtime 和业务系统掌握;退款等动作尚未开放。

主动回忆

  1. V0.3 中四层职责分别是什么?
  2. 为什么身份不能由 Tool Schema 让模型填写?
  3. 正常订单查询为什么要先于物流查询?
  4. 哪六类失败必须有不同路径?
  5. 怎样证明最终回复没有猜测工具失败后的事实?

Week 03 完成。下一阶段将处理 API 与 MCP 的连接方式:Tool Contract 保持稳定,底层能力可以通过直接 API 或标准化协议接入,但任何连接都不会自动授予业务权限。

延伸阅读 / Sources

核查日期:2026-10-17。

长期有效的原理: Tool Contract 与数据源解耦,身份在服务端校验,失败后没有证据就不生成事实。当前实现方式: 本批使用安全 Mock;接真实平台前必须重新完成授权、字段映射、限流和沙箱验收。