AI Agent Engineering · Week 04
04-01|API 在 Agent 系统中的真实位置
沿一次订单查询看懂 Agent、Tool、HTTP API 与业务系统的责任边界,以及认证、错误和限流如何进入运行时。
Tool 能被调用,事实从哪里来
V0.3 已经有 get_order_summary 与 get_tracking_status。教学 Mock 能验证 Tool Schema、Runtime 与失败路径,却不能回答真实客户的订单状态。生产系统最终仍要通过 Shopify、ERP、CRM 或承运商提供的接口取得事实。
API 是两个软件系统之间约定好的调用边界。Agent 不会因为“理解订单”就自动拥有订单数据;Runtime 必须把受控 Tool 转换成真实 API 请求,再把外部响应校验成稳定的 Tool Result。
选择 get_order_summary
稳定业务输入输出
认证、超时、重试、映射
请求与响应协议
订单事实与权限
一次 HTTP 请求最少要看懂什么
请求通常包含方法、地址、Headers 和可选 Body。GET /orders/XB-1024 表示读取资源;认证信息放在受控 Header 或连接层,不能让模型生成。响应包含状态码、Headers 与 Body,调用方还需要保存 request ID、耗时和数据来源。
Authentication 与 Authorization 分开处理
Authentication 证明调用者或应用是谁,例如 OAuth access token。Authorization 决定这个身份能不能读取当前租户、客户和订单。拿到有效 token 只完成了身份验证,不等于拥有所有订单权限。
Error 与 Rate Limit 是接口契约的一部分
401、403、404、429 与 5xx 不能都映射成“查询失败”。它们分别可能代表需要重新认证、无权访问、授权范围内未找到、达到限流或上游故障。Retry-After、供应商限流 Header 和本地重试预算共同决定是否重试。
刷新或重新认证;不交给模型猜
立即停止;记录授权拒绝
返回范围内 not_found;不泄露其他租户
读取 Retry-After;在预算内退避
有限重试;耗尽后升级
V0.3 到 V0.4 的第一步
保留 V0.3 Tool Contract,在 handler 内新增 Provider Adapter:教学环境继续使用 Mock,集成测试使用 Stub Server,真实部署才配置供应商 API。这样 Agent 与测试不需要理解 Shopify 或承运商的原始字段。
Failure Lab
把 API Key 放进 Prompt
为什么诱人: 模型似乎能自己拼请求,开发速度快。
为什么失败: 凭证会进入模型 Context、日志和 Trace,模型还可能把它输出给客户。
更合理设计: 凭证由服务端 Secret Store 与 Adapter 管理,模型只提交业务参数。
对所有错误自动重试
为什么诱人: 临时故障常能靠重试恢复。
为什么失败: 403 不会因重试获得权限,429 无视等待时间会加重限流,写操作还可能重复执行。
更合理设计: 按错误类型、HTTP 语义与幂等性设置重试策略和总预算。
把供应商响应直接当 Tool Result
为什么诱人: 少写一层字段映射。
为什么失败: 上游字段会变化,内部数据可能过量暴露,Agent Contract 被供应商锁死。
更合理设计: Adapter 校验并映射为项目自己的最小稳定结果。
实践:画出订单 API Adapter
为 get_order_summary 写一份 Adapter Contract:请求需要哪些可信 Context、请求超时多久、五类状态怎样映射、哪些字段允许进入 Tool Result、request ID 如何进入 Trace。
Acceptance Criteria
- ☐ Agent、Tool、Adapter、API 与业务系统责任分开。
- ☐ 凭证不进入 Prompt、Tool 参数或客户日志。
- ☐ Authentication 与 Authorization 有不同检查点。
- ☐
401 / 403 / 404 / 429 / 5xx有不同策略。 - ☐ 重试受次数、时间和幂等性限制。
- ☐ 上游响应经过 Schema 与业务范围校验。
- ☐ Tool Result 保留来源、更新时间与 request ID。
主动回忆
- Tool 与 API 分别服务谁?
- 有效 token 为什么不等于有权读取某笔订单?
429与403为什么不能使用相同恢复策略?- Provider Adapter 为项目隔离了哪些变化?
下一课进入 MCP:当多个 AI Host 都想使用同一组订单能力时,怎样提供标准化发现、调用和结果交换,而不复制每个 Host 的集成代码。
延伸阅读 / Sources
核查日期:2026-10-18。
- IETF RFC 9110:HTTP Semantics。用于核对方法、状态码、认证与重试相关 HTTP 语义。
- IETF RFC 9457:Problem Details for HTTP APIs。用于核对结构化 API 错误表示。
- OWASP:Authorization Cheat Sheet。用于核对默认拒绝与每次请求授权原则。
长期有效的原理: 稳定业务契约、服务端凭证、显式错误与最小数据。当前实现方式: 供应商 URL、认证流程、限流 Header 和 SDK 会变化,接入时必须以目标 API 当前文档与沙箱测试为准。