以 Agent 為優先的 API 設計：如何打造 AI Agent 真正能理解的 API

大多數 API 是為人類開發者設計的，他們會閱讀文件、瀏覽範例並透過堆疊追蹤（stack traces）進行除錯。到了 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: (searches the web for "tokenlab 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-5.5"}
API:   200 ✓

六個步驟、多次網路請求、數百個浪費的 token。而且這還是順利的情況，前提是 Agent 剛好猜對了正確的文件網址。

使用 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 使用三層解析：來自生產數據的靜態別名映射、正規化字串比對，以及有界編輯距離（bounded edit distance）。每個候選項目都會對照即時模型清單進行檢查，因此我們絕不會建議目前離線的模型。

模式 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."
  }
}

無需猜測，無需從任意值開始進行指數退避（exponential backoff）。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：這雖然成功了，但有更好的方式。它可以在下一次呼叫時切換到原生端點，並使用 OpenAI 相容格式所未公開的擴展思考（extended thinking）和提示快取（prompt caching）等功能。

這些提示存在於標頭（headers）中，而不是回應主體（body），因為主體必須完全遵循 OpenAI 或 Anthropic 的規範。標頭是安全的擴充點，不會破壞任何現有的解析邏輯。

作為 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：

1. 讓每個錯誤都可採取行動。說明出了什麼問題、原因以及下一步該做什麼。
2. 提供建議，而非自動修正。讓 Agent 做出明智的決定。
3. 使用結構化欄位，而非散文。did_you_mean 是可解析的；埋在句子裡的「did you mean...」則無法解析。
4. 以真實數據為基礎。生產環境的使用模式勝過會過時的硬編碼清單。
5. 透過 llms.txt、OpenAPI 規範或結構化模型清單提供機器可讀的探索方式。
6. 保持向後相容。新的提示欄位應該是附加的，絕不能破壞現有功能。

如何從不重寫所有內容開始

大多數團隊不需要在一週內重新設計整個 API。一個較小的起點就很有效：

1. 在你最高流量的錯誤中增加一兩個機器可讀的提示欄位。
2. 讓 /v1/models 或你的對等探索端點變得更豐富、更明確。
3. 發布一份機器可讀的概覽，例如 llms.txt。
4. 使用實際的 Agent 客戶端測試完整的循環，而不僅僅是使用 curl。

如果你已經透過閘道層（gateway layer）運作，統一 AI 閘道指南解釋了為什麼該控制平面很重要。如果你仍在使用直接的 OpenAI 相容整合，遷移指南是在加入 Agent 友善行為之前最容易開始的地方。

常見問題

什麼是 Agent-First API 設計？

這是一種方法，其中錯誤回應包含結構化、機器可讀的提示（如 did_you_mean、suggestions 和 hint 等欄位），以便 AI Agent 無需人工介入或查詢文件即可自我修正。

Agent-First 與開發者優先（Developer-First）API 設計有何不同？

開發者優先的 API 優化了人類的可讀性：清晰的訊息、良好的文件、有用的範例。Agent-First API 在此基礎上增加了結構化欄位，以便機器可以解析錯誤並以程式化方式採取行動，而無需閱讀任何內容。

Agent-First 設計會破壞現有的客戶端嗎？

不會。這些欄位是附加的。不尋找 did_you_mean 或 suggestions 的現有客戶端只會忽略它們，並繼續像以前一樣正常運作。

---

TokenLab 提供對 300 多種 AI 模型的統一存取，包括 GPT-5.5、Claude Sonnet 5 和 Gemini 3.5 Flash 等當前前沿模型，透過 模型目錄中列出的單一 API 即可存取。免費開始使用，並以 1 美元的入門額度測試 Agent-First API。