API调用工具让Agent接入各种外部服务单个工具能力有限。真正的威力在于Agent可以调用各种第三方API接入外部服务。天气服务、地图服务、短信服务、支付接口、企业内部系统只要有APIAgent理论上都能调用。这一下Agent的能力边界就被大大推开了。这一篇我们讲怎么把API封装成Agent工具。怎么设计参数怎么处理认证怎么处理错误以及安全方面要注意什么。基本思路把一个API变成Agent工具其实就是三件事。第一写一个Python函数里面调用API。请求怎么发参数怎么传响应怎么解析都写在函数里。第二给函数加tool装饰器让它变成LangChain的工具。第三写好函数的文档字符串。告诉Agent这个工具是干什么的、参数是什么意思、什么时候该用。就这么简单。大部分API都能这么封装。一个完整的例子我们来封装一个天气查询的API。用wttr.in这个免费的天气服务不用注册直接就能用。fromlangchain.toolsimporttoolfrompydanticimportBaseModel,FieldimportrequestsclassWeatherInput(BaseModel):city:strField(description城市名称比如北京、上海、广州。支持中英文。)tool(args_schemaWeatherInput)defget_weather(city:str)-str:查询指定城市的实时天气情况。 返回天气状况、温度、体感温度、湿度、风力等信息。 当用户问天气怎么样、温度多少、会不会下雨、有没有风的时候可以调用这个工具。 例如用户说今天北京天气怎么样、上海冷不冷、广州会不会下雨。 try:# 调用天气APIurlfhttps://wttr.in/{city}?formatj1responserequests.get(url,timeout10)response.raise_for_status()dataresponse.json()# 解析返回结果currentdata[current_condition][0]weather_desccurrent[weatherDesc][0][value]tempcurrent[temp_C]feels_likecurrent[FeelsLikeC]humiditycurrent[humidity]windspeedcurrent[windspeedKmph]# 整理成自然语言resultf{city}当前天气 天气状况{weather_desc}温度{temp}度 体感温度{feels_like}度 湿度{humidity}% 风速{windspeed}公里/小时returnresultexceptrequests.Timeout:return天气服务请求超时了请稍后再试。exceptrequests.HTTPErrorase:ife.response.status_code404:returnf找不到{city}的天气信息请确认城市名是否正确。returnf天气服务返回错误状态码{e.response.status_code}。exceptExceptionase:returnf查询天气时出现错误{e}。这个例子包含了几个关键点。Pydantic定义输入参数类型和描述都写清楚。文档字符串详细说明功能和使用场景还举了例子。API调用有超时设置不会一直等。各种异常情况都有处理返回给Agent有意义的错误信息。返回结果整理成自然语言Agent好理解。照着这个模板基本上任何REST API都能封装成工具。认证怎么处理大部分API都需要认证。API密钥、Token、用户名密码各种方式都有。密钥不能写死在代码里更不能提交到Git。正确的做法是放环境变量里代码里读取。.env文件里配置。WEATHER_API_KEY你的密钥代码里用os.environ读取。importos api_keyos.getenv(WEATHER_API_KEY)或者用pydantic-settings来管理配置更规范一些。frompydantic_settingsimportBaseSettingsclassSettings(BaseSettings):weather_api_key:strsettingsSettings()api_keysettings.weather_api_key它会自动从环境变量和.env文件里读取配置。OAuth2认证的API会麻烦一些。需要获取Token、刷新Token、处理过期。这种情况建议封装一个客户端类把认证逻辑都包在里面工具函数只负责调用。不同类型的API怎么封装GET请求最简单。参数拼在URL里发GET请求就行。前面的天气例子就是GET。POST请求带请求体的POST请求稍微复杂一点。tooldefsend_sms(phone_number:str,message:str)-str:发送短信。 把指定内容的短信发送到指定的手机号码。 当用户要求发短信、通知某人的时候可以使用。 参数 phone_number: 手机号码11位数字 message: 短信内容不超过70个字 try:responserequests.post(https://api.sms.example.com/send,json{phone:phone_number,content:message,},headers{Authorization:fBearer{api_key},Content-Type:application/json,},timeout10,)resultresponse.json()ifresult.get(code)0:return短信发送成功else:returnf短信发送失败{result.get(msg,未知错误)}exceptExceptionase:returnf发送短信出错{e}跟GET差不多就是用post方法把参数放json里。文件上传下载有些API需要传文件或者返回文件。这种处理起来麻烦一点。上传文件用files参数。withopen(file.pdf,rb)asf:responserequests.post(url,files{file:f},timeout30,)下载文件的话拿到响应内容以后保存到本地。responserequests.get(url,timeout30)withopen(output.pdf,wb)asf:f.write(response.content)文件操作的工具超时时间要设长一点。文件大的话传输需要时间。安全注意事项让Agent调用外部API安全问题不能忽视。第一个API密钥保护。密钥不能泄露。别写在代码里别打印日志的时候打出来。用环境变量或者配置中心管理。第二个URL白名单。不能让Agent随便请求任意URL。要调用哪些API提前封装成工具。Agent只能调用你给它的工具不能自己构造请求。第三个输入校验。用户输入的内容可能有问题。调用API之前做一下校验比如手机号格式对不对参数长度有没有超限。第四个速率限制。别让Agent疯狂调用API把你的额度用完了。可以加调用次数限制或者加个成本上限。第五个幂等性。写操作的API比如创建订单、发送短信要考虑重复调用的问题。Agent可能因为各种原因调用多次接口最好设计成幂等的。第六个敏感数据。用户的个人信息、商业机密不要随便传给第三方API。传之前想一想数据出去了还能不能收回来。做Demo的时候不用考虑这么多。上生产环境这些都得想清楚。实用建议最后说几个实战经验。第一个工具粒度要合适。太大了Agent不知道什么时候该用。太小了Agent调用起来麻烦也容易搞错。一个工具完成一件相对独立的事差不多。第二个返回结果尽量用自然语言。别把原始JSON直接扔给Agent。它也能解析但整理成自然语言它理解得更好出错概率更低。第三个错误信息要有意义。告诉Agent哪里错了、可能的原因、建议怎么处理。它才能决定下一步怎么做。只返回错误两个字Agent也不知道该怎么办。第四个加日志。工具的调用时间、参数、返回结果、耗时都记下来。出问题的时候好排查。也能用来分析Agent的使用模式。第五个从简单的开始。先封装一两个只读的、安全的API试试水。跑通了没问题了再慢慢加。别一上来就把支付、下单这种高危接口给Agent。下一篇也就是工具篇的最后一篇我们聊一聊工具使用策略。Agent有很多工具以后怎么让它选对工具、用好工具、少走弯路。