大多數 API 是為人類開發者設計的，他們閱讀文件、瀏覽範例並使用堆疊追蹤（stack traces）進行除錯。但在 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: (搜尋網路以查找 "lemondata models list")
Agent: (獲取文件頁面，可能是錯誤的頁面)
Agent: (解析 HTML，找到模型名稱)
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 欄位使用了三層解析：來自生產數據的靜態別名映射、標準化字串匹配以及有界編輯距離（bounded edit distance）。所有候選模型都會根據即時模型列表進行驗證，因此我們絕不會建議目前離線的模型。
模式 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 中，而不是回應主體（body）中，因為主體遵循 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 規範或結構化模型列表提供機器可讀的發現機制。 - 保持向後相容性。新的提示欄位應該是附加的，絕不能造成破壞。
如何在不重寫一切的情況下開始
大多數團隊不需要在一週內重新設計整個 API。
實際的起點可以更小：
- 在最高流量的錯誤中添加一兩個機器可讀的提示欄位
- 讓
/v1/models或等效的模型發現端點更豐富、更明確 - 發佈一個機器可讀的概覽，例如
llms.txt - 使用一個 Agent 客戶端測試整個循環，而不僅僅是使用 curl
如果您已經透過網關層進行操作，統一 AI 網關指南展示了為什麼該控制平面很重要。如果您仍在使用直接的 OpenAI 相容整合，遷移指南是在添加更多 Agent 友好行為之前最簡單的起點。
FAQ
什麼是 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 端點 提供機器可讀的 API 發現。
LemonData 透過單一 API 提供對 300 多個 AI 模型的統一訪問。免費試用以測試 Agent-First API，並獲得 1 美元的入門額度。
