AI Agent调用API的五大失败教训：服务300个客户端的实战总结

当你为AI Agent提供服务时，传统的API设计假设可能全部失效。Agent Commons在上线头两周就遇到了约300个独立客户端——其中大部分是爬虫和探测程序，少数是带有真实目标的AI Agent。本文整理自其官方笔记，总结了五个导致真实用户流失的失败教训。

教训一：Bot防护机制会静默拦截Agent

Cloudflare的浏览器完整性检查曾连续数天对所有使用Python默认urllib用户代理的请求返回403。问题在于：没有任何错误通知到达服务端，Agent只是从未出现。

这意味着你的监控面板可能显示一切正常，但实际上所有使用标准HTTP库的Agent都被挡在了门外。

解决方案： 每天用Python urllib、requests、httpx、Node和Go的默认用户代理，以及各大助手平台的fetch工具测试你的端点。不要假设"能通过浏览器访问"就等于"Agent能访问"。

教训二：许多Agent只能发起GET请求

助手类产品的fetch工具通常只允许GET方法，部分工具甚至只能打开对话中已出现的URL。这对需要POST、PUT等写操作的API来说是个硬伤。

解决方案： 为每个写操作提供GET形式的替代接口，配合幂等性request_id参数。同时，在llms.txt中放置现成的可点击链接，降低Agent的调用门槛。

什么是llms.txt： 这是一种约定俗成的、放置在网站根目录下的纯文本文件（路径通常为/llms.txt），用Markdown格式向大语言模型和AI Agent说明本站点有哪些资源、接口和推荐入口。它类似于面向搜索引擎的robots.txt或面向站点地图的sitemap.xml，但服务对象换成了LLM。由于许多Agent的fetch工具只能打开对话中已经出现过的URL，把可点击的接口链接预先写进llms.txt，就等于给Agent提供了一份"可探索的目录"，让它们无需猜测URL即可找到GET形式的替代接口和文档入口。

教训三：重定向会破坏Agent请求

大量HTTP客户端在遇到重定向时，会将POST转为GET或直接丢弃请求体。python-httpx默认甚至不跟随重定向。这类行为在浏览器场景下无关紧要，但对Agent来说意味着请求失败。

Agent Commons在迁移到新地址时，只对浏览器页面视图做了重定向，Agent请求仍在旧主机上应答。即便如此谨慎，一次批量重命名操作还是意外将旧主机从MCP白名单中移除，导致约20分钟的403错误。

解决方案： 通过添加新地址而非替换旧地址来完成迁移。每次部署后，在每个主机上测试所有协议。

MCP白名单的由来： MCP（Model Context Protocol）是一套让AI助手与外部工具、数据源通信的开放协议，Agent平台通常会维护一份允许访问的主机白名单，只有名单内的域名才能被Agent调用。因此当你迁移API地址时，除了DNS和HTTP层要正确，还必须同步更新MCP白名单，否则即使网络层面完全畅通，Agent侧仍会在协议层被拒绝。Agent Commons的20分钟403故障正源于此——批量重命名操作没有把新主机加入白名单，导致请求在Agent平台入口处被拦下。

教训四：Agent运行在沙箱环境中

多个Agent没有公网IP，且运行几分钟后就被回收。Webhook根本无法触达它们——这是传统API设计中很少考虑的场景。

解决方案： 提供一个固定URL，返回所有发给该Agent的消息。状态管理应以Agent名称为键，而非其运行时环境。

Webhook与轮询的差异： Webhook是一种"推"模式，服务端主动向客户端预先注册的回调URL发起HTTP请求，前提是客户端必须有一个长期可达的公网地址。而Agent运行在无公网IP、几分钟即被回收的沙箱里，根本收不到推送。所谓"拉取式固定URL"，就是让服务端暴露一个稳定的端点（如/agents/{name}/messages），由Agent在需要时主动GET拉取属于自己的消息。这样状态就不再绑定到某个短命的运行时环境，而是绑定到Agent的逻辑标识，即使沙箱被销毁重建，也能无缝续接。

教训五：Agent会直接提交模板内容

Agent曾将表单示例原封不动地提交——包括占位符姓名。这不是Agent"犯错"，而是它们缺乏对模板语义的理解。

解决方案： 拒绝未填充的模板提交，返回清晰的错误信息，而不是将其存入数据库。

为什么Agent会提交占位符： 模板中的"姓名：张三""邮箱：[email protected]"本是人类阅读时自动忽略的示意文字，但LLM在处理表单结构时，往往把整段HTML或JSON视为需要整体回传的字段内容，缺乏"这是示例不是真实值"的语义判断。加之部分Agent调用工具时只是机械复制页面上出现过的字符串，并不会主动追问"这里应该填什么"。因此服务端不能假设收到的数据一定经过用户意图过滤，需要在入库前检测关键词（如"示例""example""placeholder"）和典型占位符模式，并返回可读的错误提示，引导Agent重新填写。

核心原则：每一次失败的调用都是一个离开的用户

Agent Commons的经验可以浓缩为一句话：每天检查日志中的新客户端，重放它们发送的请求，修复它们遇到的问题。

这个原则背后是一个容易被忽视的现实——当你的API面向Agent时，你面对的是一个与人类用户截然不同的消费群体。它们不会提交工单，不会在社交媒体上抱怨，甚至不会触发你的错误监控。它们只是消失。

对于正在构建Agent友好型API的开发者来说，这五条教训指向同一个方向：为Agent设计API，需要重新审视那些面向人类用户的默认假设。 代理检测、请求方法限制、重定向行为、网络环境假设、输入验证逻辑——每一个环节都可能成为Agent静默失败的入口。