大多数 API 都是为人类开发者构建的，他们会阅读文档、浏览示例并使用堆栈跟踪进行调试。到了 2026 年，越来越多的 API 流量来自 AI Agent，而它们与 API 的交互方式与人类完全不同。
这就是我们围绕一个原则重新设计 TokenLab 统一 AI API 的方式：不要试图耍小聪明，要提供信息。我们将此成果称为 Agent-First API 设计，它为我们的用户减少了超过 60% 的无效 token 消耗。
核心要点
- Agent-First API 设计在错误响应中添加了结构化的、机器可读的提示，以便 AI Agent 无需搜索网页或人工帮助即可实现自我纠正。
- 提供建议，而不是自动纠正。像
did_you_mean、suggestions和retryable这样的字段让 Agent 能够做出明智的决定，而不是替它们做决定。 - 每一条建议都基于生产数据，因此离线或已弃用的模型永远不会出现在候选列表中。
- 提示字段是附加的且向后兼容，因此现有的 OpenAI 兼容客户端可以继续正常工作，无需任何更改。
什么是 Agent-First API 设计？
Agent-First API 设计意味着构建你的响应（尤其是错误响应），以便 AI Agent 能够理解出了什么问题并在不离开对话的情况下修复它。
传统的 API 错误：
{"error": {"message": "Model not found"}}
Agent-First API 错误：
{
"error": {
"code": "model_not_found",
"message": "Model 'gpt5.5' not found",
"did_you_mean": "gpt-5.5",
"suggestions": [{"id": "gpt-5.5"}, {"id": "gemini-3.5-flash"}],
"hint": "Use GET /v1/models to list all available models."
}
}
使用传统 API，Agent 必须搜索网页、查找文档、解析 HTML 并进行猜测。而使用 Agent-First API，它只需一步即可自我纠正。
为什么传统 API 会让 AI Agent 受挫
看看当 Agent 第一次访问典型的 API 聚合器时会发生什么：
Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (搜索网页 "tokenlab models list")
Agent: (获取文档页面，可能是错误的页面)
Agent: (解析 HTML，找到模型名称)
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
API: 200 ✓
六个步骤，多次网络请求，浪费了数百个 token。而且这还是在 Agent 碰巧猜对了文档 URL 的理想情况下。
采用 Agent-First 设计后：
Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API: 400 {"did_you_mean": "gpt-5.5", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
API: 200 ✓
两个步骤，零次网页搜索。Agent 仅凭错误响应就完成了自我纠正。
核心原则：智能应保留在模型端
人们很容易倾向于构建“智能”API，自动纠正模型名称、静默重定向到类似模型，或者附加一个推荐引擎。我们拒绝了所有这些做法。
当 Agent 发送 model: "gpt5.5" 时，你实际上并不知道它的意图。也许它是在检查是否有更新的 GPT 版本发布。也许它有严格的预算限制。也许它需要某个特定模型才支持的功能。自动路由到 gpt-5.5 会在 Agent 不知情的情况下改变成本、质量和功能。
更好的做法是快速失败并提供详尽的信息。将所有数据交给 Agent，让它自己做决定。
四种 Agent-First API 设计模式
模式 1：模型未找到 → 模糊建议
{
"error": {
"code": "model_not_found",
"did_you_mean": "gpt-5.5",
"suggestions": [
{"id": "gpt-5.5"},
{"id": "gemini-3.5-flash"},
{"id": "claude-sonnet-5"}
],
"hint": "Did you mean 'gpt-5.5'? 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": "gemini-3.5-flash", "estimated_cost_usd": 0.02},
{"id": "deepseek-v4-flash", "estimated_cost_usd": 0.01}
],
"hint": "Insufficient balance. Try a cheaper model or top up."
}
}
我们不再只是说“余额不足”，而是告诉 Agent 它确切有多少钱、需要多少钱，以及它现在能负担得起哪些模型。Agent 可以自主降级到更便宜的 AI 模型，无需人工干预。在硬编码成本阈值之前，请在 TokenLab 模型目录上核实当前的各模型定价。
模式 3：所有通道失败 → 实时替代方案
{
"error": {
"code": "all_channels_failed",
"retryable": true,
"retry_after": 30,
"alternatives": [
{"id": "claude-sonnet-5", "status": "available"},
{"id": "gpt-5.5", "status": "available"}
],
"hint": "All channels for 'claude-opus-4-8' 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-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages
我们是在告诉 Agent：这次调用成功了，但有更好的方法。它可以在下一次调用时切换到原生端点，从而利用扩展思维（extended thinking）和提示缓存（prompt caching）等 OpenAI 兼容格式中未公开的功能。
这些提示位于 Header 中，而不是响应体中，因为响应体必须严格遵循 OpenAI 或 Anthropic 的规范。Header 是安全的扩展点，不会破坏任何现有的解析逻辑。
作为 Agent 备忘单的 /v1/models 响应
我们在 /v1/models 响应的每个模型条目中添加了三个字段：
category：聊天模型、图像生成器、视频模型或音频模型。不再需要根据名称猜测。pricing_unit：按 token、按图像、按秒或按请求计费。这是进行任何实际成本估算所必需的。cache_pricing：上游提示缓存价格加上平台的语义缓存折扣。
结合现有字段（定价、功能、别名、最大 token 数），Agent 可以通过单次 API 调用做出完全明智的模型选择。你可以在 TokenLab 模型目录中查看完整的实时目录（观察日期 2026-07-07），该目录目前列出了 300 多种涵盖聊天、图像、视频和音频类别的模型，包括 Claude Sonnet 5、GPT-5.5 和 Gemini 3.5 Flash 等当前的前沿选项。请在该页面核实当前的定价和可用性，而不是假设本文中的数字是最新的。
llms.txt：Agent 的首读文档
我们在 api.tokenlab.sh/llms.txt 提供了一个动态的 llms.txt，这是整个 API 的机器可读概览。它包括：
- 带有可用代码的首个调用模板
- 常用的模型名称，从使用数据自动生成，而非硬编码
- 所有 12 个带有参数的端点
- 用于模型发现的过滤参数
在第一次 API 调用前读取此文件的 Agent，更有可能在第一次尝试时就正确发出请求。
数据驱动，而非知识驱动
系统中的每一条建议都来自生产数据。did_you_mean 别名映射是根据 30 天内请求日志中实际的 model_not_found 错误生成的。模型建议按实际使用情况排序。llms.txt 中的“常用模型名称”列表是由我们的数据库生成的，而不是人工维护的。
我们会在 Redis 有序集合中跟踪每一个模型未找到的情况。一旦某个拼写错误积累了足够的点击量，它就会被提升到别名映射中。当模型下线时，它会自动从所有建议列表中删除。系统会随着时间的推移自我调整，而不是变得过时，这在 GPT-5.5、Claude Sonnet 5 和 Gemini 3.5 Flash 等新模型在重叠的时间线上发布时尤为重要。
使其成功的关键设计约束
我们设定了一条规则：没有新端点，没有新 SDK，没有破坏性变更。一切都必须符合现有的 OpenAI 兼容错误格式。新字段是可选的，因此任何忽略它们的客户端都会获得与以前完全相同的体验。
这一约束迫使我们精确地思考什么才是真正有助于 Agent 自我纠正的内容，而不是构建没人愿意采用的复杂新 API。
如何将 Agent-First 设计应用于你自己的 API
如果你正在构建 AI Agent 将要消费的 API：
- 让每个错误都可操作。说明出了什么问题、原因以及下一步该怎么做。
- 提供替代方案，而不是自动纠正。让 Agent 做出明智的决定。
- 使用结构化字段，而不是长篇大论。
did_you_mean是可解析的；埋在句子里的“did you mean...”则不是。 - 以真实数据为基础。生产使用模式胜过容易过时的硬编码列表。
- 通过
llms.txt、OpenAPI 规范或结构化模型列表提供机器可读的发现方式。 - 保持向后兼容。新的提示字段应该是附加的，绝不能破坏现有功能。
如何无需重写一切即可开始
大多数团队不需要在一周内重新设计整个 API。从小处着手效果很好：
- 在你最高频的错误中添加一两个机器可读的提示字段。
- 使
/v1/models或等效的发现端点更加丰富和明确。 - 发布一个机器可读的概览，例如
llms.txt。 - 使用实际的 Agent 客户端测试整个循环，而不仅仅是 curl。
如果你已经通过网关层进行操作，统一 AI 网关指南解释了为什么该控制平面至关重要。如果你仍然使用直接的 OpenAI 兼容集成，迁移指南是在加入 Agent 友好行为之前最简单的起点。
常见问题解答
什么是 Agent-First API 设计？
这是一种方法，其中错误响应包含结构化的、机器可读的提示（如 did_you_mean、suggestions 和 hint 等字段），以便 AI Agent 无需人工干预或查找文档即可实现自我纠正。
Agent-First 与 Developer-First API 设计有何不同？
Developer-First API 针对人类可读性进行了优化：清晰的消息、良好的文档、有用的示例。Agent-First API 在此基础上添加了结构化字段，以便机器可以解析错误并以编程方式采取行动，而无需阅读任何内容。
Agent-First 设计会破坏现有客户端吗？
不会。这些字段是附加的。不查找 did_you_mean 或 suggestions 的现有客户端只需忽略它们，并继续像以前一样工作。
TokenLab 通过在 模型目录中列出的单一 API，提供对 300 多种 AI 模型的统一访问，包括 GPT-5.5、Claude Sonnet 5 和 Gemini 3.5 Flash 等当前前沿模型。免费开始，使用 1 美元的入门积分测试 Agent-First API。
来源
价格观测于 2026-07-07
- TokenLab model directory观测于 2026-07-07
