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

AI Agent Engineering · Week 04

04-01|API 在 Agent 系统中的真实位置

沿一次订单查询看懂 Agent、Tool、HTTP API 与业务系统的责任边界,以及认证、错误和限流如何进入运行时。

API · HTTP · External Integration

Tool 能被调用,事实从哪里来

V0.3 已经有 get_order_summary 与 get_tracking_status。教学 Mock 能验证 Tool Schema、Runtime 与失败路径,却不能回答真实客户的订单状态。生产系统最终仍要通过 Shopify、ERP、CRM 或承运商提供的接口取得事实。

API 是两个软件系统之间约定好的调用边界。Agent 不会因为“理解订单”就自动拥有订单数据;Runtime 必须把受控 Tool 转换成真实 API 请求,再把外部响应校验成稳定的 Tool Result。

Agent

选择 get_order_summary

Tool Contract

稳定业务输入输出

Runtime / Adapter

认证、超时、重试、映射

HTTP API

请求与响应协议

Business System

订单事实与权限

图 1|Tool 是 Agent 看见的业务能力;API 是 Adapter 连接真实系统的方式;事实仍由业务系统拥有。

一次 HTTP 请求最少要看懂什么

请求通常包含方法、地址、Headers 和可选 Body。GET /orders/XB-1024 表示读取资源;认证信息放在受控 Header 或连接层,不能让模型生成。响应包含状态码、Headers 与 Body,调用方还需要保存 request ID、耗时和数据来源。

Request|method + URL + auth header + timeout + request ID
↓ network / vendor boundary ↓
Response|status + body + rate-limit headers + source timestamp
↓ validate and map ↓
Tool Result|ok/data 或 ok/error/source/requestId
图 2|外部响应不能直接塞给模型;Adapter 要先验证状态、结构、授权范围与来源。

Authentication 与 Authorization 分开处理

Authentication 证明调用者或应用是谁,例如 OAuth access token。Authorization 决定这个身份能不能读取当前租户、客户和订单。拿到有效 token 只完成了身份验证,不等于拥有所有订单权限。

Error 与 Rate Limit 是接口契约的一部分

401、403、404、429 与 5xx 不能都映射成“查询失败”。它们分别可能代表需要重新认证、无权访问、授权范围内未找到、达到限流或上游故障。Retry-After、供应商限流 Header 和本地重试预算共同决定是否重试。

401

刷新或重新认证;不交给模型猜

403

立即停止;记录授权拒绝

404

返回范围内 not_found;不泄露其他租户

429

读取 Retry-After;在预算内退避

5xx / timeout

有限重试;耗尽后升级

图 3|模型可以组织安全回复;重试预算、凭证处理和授权拒绝由 Runtime 决定。

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。

主动回忆

  1. Tool 与 API 分别服务谁?
  2. 有效 token 为什么不等于有权读取某笔订单?
  3. 429 与 403 为什么不能使用相同恢复策略?
  4. Provider Adapter 为项目隔离了哪些变化?

下一课进入 MCP:当多个 AI Host 都想使用同一组订单能力时,怎样提供标准化发现、调用和结果交换,而不复制每个 Host 的集成代码。

延伸阅读 / Sources

核查日期:2026-10-18。

长期有效的原理: 稳定业务契约、服务端凭证、显式错误与最小数据。当前实现方式: 供应商 URL、认证流程、限流 Header 和 SDK 会变化,接入时必须以目标 API 当前文档与沙箱测试为准。