Agent-First API 设计：如何构建 AI Agent 真正理解的 API
大多数 API 是为阅读文档、浏览示例并使用堆栈跟踪进行调试的人类开发人员设计的。但在 2026 年，增长最快的 API 消费者不再是人类，而是 AI Agent。而且它们与 API 交互的方式截然不同。
这是一个关于我们如何围绕一个简单原则重新设计 LemonData 统一 AI API 的故事：不要自作聪明，要提供信息。其结果就是我们所说的 Agent-First API 设计——它将我们用户的 token 浪费减少了 60% 以上。
什么是 Agent-First API 设计？
Agent-First API 设计意味着构建你的 API 响应（尤其是错误响应），以便 AI Agent 能够理解出了什么问题并在没有外部帮助的情况下修复它。
传统 API 错误：
{"error": {"message": "Model not found"}}
Agent-First API 错误：
{
"error": {
"code": "model_not_found",
"message": "Model 'gpt5' not found",
"did_you_mean": "gpt-4o",
"suggestions": [{"id": "gpt-4o"}, {"id": "gpt-4o-mini"}],
"hint": "Use GET /v1/models to list all available models."
}
}
区别在哪里？使用传统 API，Agent 需要搜索网络、查找文档、解析 HTML 并进行猜测。而使用 Agent-First API，它只需一步即可完成自我修正。
为什么传统 API 会让 AI Agent 失败
看看当 AI Agent 第一次访问典型的 API 聚合器时会发生什么：
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (searches the web for "lemondata models list")
Agent: (fetches a docs page, maybe the wrong one)
Agent: (parses HTML, finds a model name)
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
六个步骤。多次网络请求。数百个浪费的 token。而这还是“理想路径”——Agent 猜对了文档 URL。
使用 Agent-First 设计：
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"did_you_mean": "gpt-4o", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
两个步骤。零网络搜索。Agent 仅凭错误响应就完成了自我修正。
核心原则：智能保留在模型端
诱惑在于构建“聪明”的 API——自动纠正模型名称、静默路由到类似模型、添加推荐引擎。我们拒绝了所有这些。
当 Agent 发送 model: "gpt5" 时，你并不知道它的意图。也许它在测试 GPT-5 是否存在。也许它有预算限制。也许它需要特定的功能。自动路由到 gpt-4o 会在 Agent 不知情的情况下静默改变成本、输出质量和功能。
正确的做法是快速失败并提供丰富的信息。把所有数据交给 Agent。让它来决定。
四种 Agent-First API 设计模式
模式 1：未找到模型 → 模糊建议
{
"error": {
"code": "model_not_found",
"did_you_mean": "gpt-4-turbo",
"suggestions": [
{"id": "gpt-4o"},
{"id": "gpt-4o-mini"},
{"id": "claude-sonnet-4-5"}
],
"hint": "Did you mean 'gpt-4-turbo'? Use GET /v1/models to list all available models."
}
}
did_you_mean 字段使用三层解析：静态别名映射（来自生产数据，而非猜测）、归一化字符串匹配和有界编辑距离。所有候选模型都会根据实时模型列表进行验证——我们绝不会建议当前离线的模型。
模式 2：余额不足 → 预算感知的替代方案
{
"error": {
"code": "insufficient_balance",
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gpt-4o-mini", "estimated_cost_usd": 0.02},
{"id": "deepseek-chat", "estimated_cost_usd": 0.01}
],
"hint": "Insufficient balance. Try a cheaper model or top up."
}
}
与其只说“钱不够”，我们不如确切地告诉 Agent 它有多少钱、需要多少钱，以及它能负担得起哪些模型。Agent 可以自主降级到更便宜的 AI 模型——无需人工干预。
模式 3：所有通道均失败 → 实时替代方案
{
"error": {
"code": "all_channels_failed",
"retryable": true,
"retry_after": 30,
"alternatives": [
{"id": "claude-sonnet-4-5", "status": "available"},
{"id": "gpt-4o", "status": "available"}
],
"hint": "All channels for 'claude-opus-4-6' temporarily unavailable. Retry in 30s or try an alternative."
}
}
alternatives 列表不是静态的——它是对我们通道健康数据的实时查询。Agent 可以获得关于当前哪些模型真正可用的实时信息。
模式 4：频率限制 → 精确的重试时间
{
"error": {
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"limit": "1000/min",
"remaining": 0,
"hint": "Rate limited. Retry after 8s."
}
}
无需猜测。没有从任意值开始的指数退避。Agent 知道确切的等待时间。有关如何有效处理频率限制的更多信息，请参阅我们的 AI API 频率限制指南。
成功响应也带有提示
当 Agent 使用 Claude 模型调用 /v1/chat/completions 时，响应包含：
X-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-LemonData-Native-Endpoint: /v1/messages
我们在告诉 Agent：“这可行，但有更好的方法。”Agent 可以在下一次调用时切换到原生端点——从而获得诸如扩展思考（extended thinking）和 prompt 缓存等在 OpenAI 兼容格式中无法使用的功能。
我们将此放在 header 中，而不是响应体中，因为响应体遵循 OpenAI/Anthropic 规范。Header 是安全的扩展点。
/v1/models 响应作为 Agent 的“小抄”
我们在 /v1/models 响应中的每个模型中添加了三个字段：
category— 聊天模型、图像生成器、视频模型还是音频？不再需要根据名称猜测。pricing_unit— 按 token、按图像、按秒还是按请求计费。这对于成本估算至关重要。cache_pricing— 上游 prompt 缓存价格加上平台语义缓存折扣。
结合现有字段（定价、功能、别名、最大 token 数），Agent 可以通过单次 API 调用做出充分知情的模型选择决策。
llms.txt：Agent 的首读文件
我们在 api.lemondata.cc/llms.txt 提供动态的 llms.txt——整个 API 的机器可读概览。它包括：
- 带有可用代码的首次调用模板
- 常用模型名称（从使用数据自动生成，而非硬编码）
- 带有参数的所有 12 个端点
- 用于模型发现的过滤参数
在第一次 API 调用之前阅读此文件的 Agent 很有可能在第一次尝试时就成功。
数据驱动，而非知识驱动
我们系统中的每一个建议都来自生产数据。did_you_mean 别名映射是从我们请求日志中 30 天的实际 model_not_found 错误中提取的。模型建议按实际使用模式排序。llms.txt 中的“常用模型名称”是从我们的数据库生成的。
我们在 Redis 有序集合中跟踪每一次模型未命中。当某个拼写错误积累了足够的点击量时，它就会被提升到别名映射中。当模型下线时，它会自动从所有建议中消失。系统会自我完善。
让它发挥作用的设计约束
我们设定了一条规则：不增加新端点，不增加新 SDK，不进行破坏性更改。 一切都必须在现有的 OpenAI 兼容错误格式内运行。新字段是可选的——任何忽略它们的客户端都会获得与以前相同的体验。
这一约束迫使我们精确地确定哪些信息真正有助于 Agent 自我修正，而不是构建没人会采用的复杂新 API。
如何将 Agent-First 设计应用于你自己的 API
如果你正在构建 AI Agent 将要消费的 API：
- 每一个错误都应该是可操作的 — 包括出了什么问题、原因以及下一步该做什么
- 建议替代方案，不要自动纠正 — 让 Agent 做出知情的决定
- 使用结构化字段，而非纯文本 —
did_you_mean是可解析的，而字符串中的 "Did you mean..." 则不是 - 基于真实数据提供建议 — 生产使用模式优于硬编码列表
- 提供机器可读的发现机制 —
llms.txt、OpenAPI 规范或结构化模型列表 - 保持向后兼容性 — 新的提示字段应该是附加的，绝不能是破坏性的
常见问题
什么是 Agent-First API 设计？
Agent-First API 设计是一种方法，其中错误响应包含结构化的、机器可读的提示，允许 AI Agent 在没有人工干预或外部文档查找的情况下进行自我修正。
Agent-First 与 Developer-First API 设计有何不同？
Developer-First API 针对人类可读性进行优化：清晰的错误消息、良好的文档、有用的示例。Agent-First API 增加了机器可以编程解析并执行的结构化字段（did_you_mean、suggestions、hint）。
Agent-First 设计会破坏现有客户端吗？
不会。Agent-First 字段是附加的——即 JSON 响应中的额外字段。不了解这些字段的客户端只需忽略它们即可。现有的集成将继续保持不变。
LemonData 如何实现 Agent-First 设计？
LemonData 的 统一 AI API 网关 为所有 300 多个模型添加了结构化错误提示。每个错误响应都包含可操作的建议，并且 llms.txt 端点 提供了机器可读的 API 发现。
LemonData 通过单一 API 提供对 300 多个 AI 模型的统一访问。在 lemondata.cc 尝试 Agent-First API。
