大多数 API 是为阅读文档、浏览示例并使用堆栈跟踪进行调试的人类开发人员设计的。但在 2026 年，增长最快的 API 消费者是 AI Agent，它们与 API 的交互方式截然不同。
这是关于我们如何围绕一个简单原则重新设计 LemonData 统一 AI API 的故事：不要自作聪明，要提供信息。其结果就是我们所说的 Agent-First API 设计，它为我们的用户减少了超过 60% 的 Token 浪费。
什么是 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，让它来决定。
四种 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 可以在下一次调用时切换到原生 Endpoint，从而获得诸如扩展思考（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 个 Endpoint 及其参数
- 用于模型发现的过滤参数
在第一次 API 调用之前阅读此文件的 Agent 很有可能在第一次尝试时就成功。
数据驱动，而非知识驱动
我们系统中的每一个建议都来自生产数据。did_you_mean 别名映射源自我们请求日志中 30 天内实际的 model_not_found 错误。模型建议按真实使用模式排序。llms.txt 中的“常用模型名称”是从我们的数据库生成的。
我们在 Redis 有序集合中跟踪每一次模型未命中。当某个拼写错误累积了足够的点击量时，它就会被提升到别名映射中。当模型下线时，它会自动从所有建议中消失。系统会自我完善。
让其发挥作用的设计约束
我们设定了一个规则：没有新的 Endpoint，没有新的 SDK，没有破坏性变更。一切都必须在现有的 OpenAI 兼容错误格式内运行。新字段是可选的，因此任何忽略它们的客户端都能获得与以前相同的体验。
这一约束迫使我们精确地确定哪些信息真正有助于 Agent 自我修正，而不是构建没人会采用的复杂新 API。
如何将 Agent-First 设计应用于你自己的 API
如果你正在构建供 AI Agent 使用的 API：
- 每个错误都应该是可操作的。包括出了什么问题、原因以及下一步该做什么。
- 建议替代方案，不要自动纠正。让 Agent 做出知情的决定。
- 使用结构化字段，而不是纯文本。
did_you_mean是可解析的；字符串中的 "Did you mean..." 则不是。 - 建议应基于真实数据。生产使用模式优于硬编码列表。
- 通过
llms.txt、OpenAPI 规范或结构化模型列表提供机器可读的发现机制。 - 保持向后兼容性。新的提示字段应该是增量的，绝不能是破坏性的。
如何在不重写一切的情况下开始
大多数团队不需要在一周内重新设计整个 API。
实际的起点更小：
- 为你访问量最高的错误添加一两个机器可读的提示字段
- 让
/v1/models或等效的模型发现 Endpoint 更加丰富和明确 - 发布一个机器可读的概览，例如
llms.txt - 使用一个 Agent 客户端测试整个循环，而不仅仅是使用 curl
如果你已经通过网关层进行操作，统一 AI 网关指南展示了为什么控制平面很重要。如果你仍在使用直接的 OpenAI 兼容集成，迁移指南是在添加更多 Agent 友好行为之前最简单的起点。
常见问题解答
什么是 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 字段是增量添加的，这意味着现有客户端可以忽略它们并继续照常工作。
LemonData 如何实现 Agent-First 设计？
LemonData 的 统一 AI API 网关 为所有 300 多个模型添加了结构化错误提示。每个错误响应都包含可操作的建议，并且 llms.txt Endpoint 提供了机器可读的 API 发现。
LemonData 通过单个 API 提供对 300 多个 AI 模型的统一访问。免费试用 以测试 Agent-First API，并获得 1 美元的启动额度。
