首先完成“使用 NoSQL 与向量数据库”即可解锁本课程。转到上一课

介绍

当 AI 代理能够与外部世界交流时,它们才会变得有用。REST API 是系统暴露功能最常见的方式,因此代理必须能够按需调用它们。挑战在于大多数 API 设计时是面向人类驱动的客户端(仪表板、移动应用),并非为自治决策者设计。在代理能够使用 API 之前,需要将 API 合同翻译为代理能够理解和调用的形式。

将 API 封装为工具

从代理的角度看,一个工具是一个具有名称、描述和参数集的函数。你需要构建一个接收来自代理的结构化输入(例如城市名称)并返回结构化结果的薄包装。

python
import requests
def get_weather(city: str) -> dict:
url = "https://api.example.com/weather"
params = {"q": city, "units": "metric"}
response = requests.get(url, params=params, timeout=10)
response.raise_for_status()
return response.json()

包装器隐藏了 HTTP 的细节(头部、状态码、JSON 解析),并暴露了一个干净的函数签名。代理只看到函数名称、其文档字符串或描述,以及带类型的参数。

为代理结构化描述

描述是告诉代理何时以及如何调用工具。一个好的工具描述有三部分:工具所做的一行概述、一条关于何时使用它(同样重要,也包括何时不使用)的注记,以及对每个参数的格式和约束的描述。

json
{
"name": "get_weather",
"description": "Get current weather for a city. Use when the user asks about weather, temperature, or conditions outdoors. Do not use for forecasts beyond 24 hours.",
"parameters": {
"city": {
"type": "string",
"description": "City name in English, e.g. 'Hanoi' or 'Tokyo'"
}
}
}

保持描述的事实性。避免使用诸如“强大”或“高级”等夸张词汇——代理的调用决策基于实用性,而非营销语言。

流程图显示:代理接收用户查询,根据描述决定调用哪个工具,将参数发送给包装器,包装器调用 HTTP API 并将结构化结果返回给代理

处理速率限制、分页和错误

API 以可预测的方式失败。你的包装器必须处理这些失败,以便代理获得有用反馈,而不是原始的堆栈跟踪。

对于速率限制,在存在时遵循 Retry-After 头,并在重复的 429 响应上指数型回退。将调用包装在带有最大尝试次数的重试循环中,以避免无限等待。

python
import time
import requests
def call_with_retry(url, params, max_attempts=3):
for attempt in range(max_attempts):
response = requests.get(url, params=params, timeout=10)
if response.status_code == 429:
wait = int(response.headers.get("Retry-After", 2 ** attempt))
time.sleep(wait)
continue
response.raise_for_status()
return response.json()
raise Exception("Rate limited after retries")

对于分页,设计包装器使其接受一个 page 或 cursor 参数并在有更多页面时返回明确信号。让代理决定是否继续获取——比硬编码循环更能就成本和相关性进行推理。

对于错误,返回一个结构化对象,而不是盲目抛出异常。包括状态码、简短的可读原因,以及关于如何恢复的可选提示。这使代理能够使用修正后的参数重试、切换工具,或将问题报告给用户。

摘要

把每个 API 当作一个工具来对待,具有三层:干净的函数签名、代理用于选择的精确描述,以及处理 HTTP 的混乱现实(重试、分页和错误报告)的健壮包装器。包装器是易出错的外部服务与需要可预测输入以做出正确决策的推理代理之间的契约。

常见错误

在没有描述说明何时不应使用的情况下包装 API。让原始异常直接冒泡给代理,而不是返回结构化错误对象。将分页循环硬编码,使代理无法跳过页面或提前停止。忽略 Retry-After 头,使用固定延迟导致更快被封禁。

课后练习

课程检查点

巩固所学知识,获取作业反馈。

0/1
已回答 · 0/1