Agent-First API 設計：如何構建 AI Agent 真正理解的 API

大多數 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 欄位使用了三層解析：靜態別名映射（來自生產數據，而非猜測）、標準化字串匹配以及有界編輯距離。所有候選模型都會根據即時模型列表進行驗證——我們絕不會建議一個目前離線的模型。

模式 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 規範或結構化模型列表
保持向下相容性 — 新的提示欄位應該是附加的，絕不能造成破壞

常見問題 (FAQ)

什麼是 Agent-first API 設計？

Agent-first API 設計是一種方法，其錯誤回應包含結構化、機器可讀的提示，允許 AI Agent 在無需人工干預或外部文件查找的情況下進行自我修正。

Agent-first 與開發者優先 (Developer-first) 的 API 設計有何不同？

開發者優先的 API 優化了人類的可讀性：清晰的錯誤訊息、良好的文件、有用的範例。Agent-first API 則添加了機器可以程式化解析並執行的結構化欄位（did_you_mean、suggestions、hint）。

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

不會。Agent-first 欄位是附加的——即 JSON 回應中的額外欄位。不知道這些欄位的客戶端會直接忽略它們。現有的整合將繼續照常運作。

LemonData 如何實現 Agent-first 設計？

LemonData 的統一 AI API 閘道為所有 300 多個模型添加了結構化錯誤提示。每個錯誤回應都包含可操作的建議，而 llms.txt endpoint 則提供了機器可讀的 API 發現機制。

LemonData 透過單一 API 提供對 300 多個 AI 模型的統一存取。請在 lemondata.cc 嘗試 Agent-first API。

Agent-First API 設計：如何打造 AI Agents 真正理解的 API