題目與適用場景
請把一個面向人工開發者的專案管理 API 改造成適合 AI Agent 呼叫的 API。你會如何設計操作描述、輸入輸出、分頁、錯誤、寫入確認、限流與安全邊界？題目參考 IETF 2026 年 6 月發布的《Agent-Friendly HTTP API Profile》Internet-Draft。該文件是 Informational、仍為 work in progress，不定義新的協定、身份認證或授權機制。
面試官考察點
- 能否把機器可讀描述當作契約，而不是事後文件。
- 能否透過穩定命名、嚴格 schema、有限回應與游標分頁減少錯誤選擇。
- 能否讓錯誤、重試、冪等、預覽與撤銷成為可執行訊號。
- 能否區分 API 可用性與 Agent 身份、授權、提示注入等安全問題。
回答前需要釐清的問題
- Agent 透過 OpenAPI、MCP 工具層還是自訂目錄發現 API？
- 哪些操作只讀，哪些操作會通知、扣費或改變狀態？
- 回應是否需要欄位選擇、游標分頁與最大頁大小？
- 逾時重試時，客戶端能否提供冪等鍵並讀取原始結果？
- 哪些回傳欄位來自不可信使用者內容，必須與控制欄位隔離？
30 秒回答框架
我會把 API 描述與 HTTP 行為一起當作 Agent 的輸入契約。操作名稱穩定且表達意圖，輸入 schema 嚴格拒絕未知欄位，回應預設小且可選欄位，集合使用游標分頁。錯誤回傳穩定 code、是否可重試與下一步連結；寫入支援冪等鍵、預覽、確認與撤銷。伺服器強制限流、回應大小、權限與稽核，不能把安全決策交給 Agent。該 IETF 文件是草案清單，不是新的認證協定。
分步驟深入解答
1. 分離 API 層與工具層
OpenAPI 等機器可讀描述屬於 API 層，MCP 或其他工具呼叫協定屬於工具層。先把 API 設計成穩定、可驗證的契約，多個工具層才能複用；不要把某個 Agent 的提示詞或工具名稱當作唯一安全邊界。
2. 設計可區分的操作
操作 ID 要穩定、短且說明意圖。工具面很大時，實體優先的 task_create、task_update 比只有 create_ 前綴更容易區分。描述應明確何時使用、何時不能使用、是否有副作用，以及缺少識別碼時先呼叫哪個查詢操作。
3. 嚴格約束輸入與回應
輸入 schema 設定必填欄位、封閉列舉、長度與陣列上限，並拒絕未知屬性。回應預設返回小物件，支援欄位選擇或 verbosity；不要讓客戶端「自己少取一點」，因為伺服器仍需控制成本與上下文占用。
{
"name": "task_create",
"description": "Create a task; notifies the assignee.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"required": ["project_id", "title", "idempotency_key"],
"properties": {
"project_id": {"type": "string"},
"title": {"type": "string", "maxLength": 200},
"priority": {"type": "string", "enum": ["low", "medium", "high"]},
"idempotency_key": {"type": "string", "maxLength": 128}
}
}
}4. 讓讀取與分頁可恢復
集合返回游標而不是要求 Agent 計算 offset；游標應是不透明、過期且綁定查詢條件。回應給出 next_cursor 與可執行的下一步。穩定排序、條件請求與欄位選擇降低重複傳輸與上下文消耗。
5. 讓錯誤成為機器訊號
錯誤使用穩定 code、結構化詳情與 retryable 標誌；必要時附帶下一步操作連結。429 要給出重試等待，驗證錯誤要指出具體欄位，非同步任務要返回狀態查詢地址。自然語言可幫助人理解，但不能承擔唯一控制語義。
{
"type": "https://api.example/problems/rate-limit",
"title": "Too many requests",
"status": 429,
"code": "RATE_LIMITED",
"retryable": true,
"retry_after_seconds": 30
}6. 保護寫入操作
寫入操作接受冪等鍵並定義有效窗口與作用域；逾時重試應返回原始結果，而不是重複建立。高風險寫入提供 dry-run、確認或撤銷，並在描述中明確通知、扣費與外部副作用。伺服器仍要執行授權、配額與稽核。
7. 處理安全邊界與可觀測性
使用者或第三方回傳的文字必須標記為資料，與可信控制欄位分離，降低間接提示注入影響。限制回應大小、頁大小、輪詢頻率與工具命名空間；高風險操作要求最小權限與人工確認。記錄 correlation ID、操作者、委託資訊、請求結果與重試，不記錄敏感內容。
8. 驗證與迭代
用固定任務集評估操作選擇準確率、參數錯誤率、重複寫入率、可恢復錯誤率、平均回應大小、上下文占用、429 後成功率與人工確認覆蓋率。對描述、schema、錯誤與回應做版本化；草案建議應轉成內部檢查清單，而不是對外承諾標準相容。
高品質示範回答
我會先把 API 描述視為主契約，再設計 HTTP 行為。操作 ID 穩定、表達實體與意圖，描述同時寫清使用條件、禁用場景與副作用；輸入 schema 嚴格拒絕未知欄位，列舉、長度、陣列與頁大小都有上限。集合使用不透明游標與穩定排序，回應預設小並支援欄位選擇。
錯誤回傳穩定 code、是否可重試、retry_after 與下一步連結。寫入操作要求冪等鍵，逾時重試返回原始結果；高風險寫入支援預覽、確認或撤銷。伺服器強制權限、限流、大小與稽核，不能依賴 Agent 遵守描述。使用者內容與控制欄位隔離，工具按提供方隔離並保留 correlation ID。
最後用任務集測量錯誤選擇、參數錯誤、重複寫入、回應大小、重試成功率與人工確認覆蓋率。IETF 文件是 2026 年 6 月的 Informational 草案，未定義認證或授權，因此我會把它當成設計檢查清單，保留內部版本與回滾策略。
常見錯誤
- 把 Agent-friendly profile 說成新的身份認證或授權協定。
- 只最佳化提示詞，不把 OpenAPI、schema、錯誤與副作用寫入契約。
- 讓 Agent 自己限制回應大小或計算分頁 offset。
- 寫入沒有冪等鍵、預覽、確認與撤銷，重試會重複副作用。
- 把使用者回傳文字放進可信指令欄位，忽略間接提示注入。
追問及應對
為什麼不只寫一份更詳細的文件？
Agent 每次根據機器可讀描述與回應做選擇，穩定欄位、列舉、錯誤標誌與游標比散落在長文中的建議更容易被執行；文件仍用於人類解釋與遷移。
API 層與 MCP 工具層誰負責安全？
API 層必須執行認證、授權、限流與稽核；工具層可以限制暴露範圍、命名空間與確認流程，但不能取代伺服器端存取控制。
如何決定哪些寫入需要確認？
按不可逆性、金額、資料披露、外部通知與權限範圍分級。高風險操作提供 dry-run 或確認 token，低風險冪等更新可以自動執行，但始終由伺服器驗證。
如果描述被第三方內容污染怎麼辦？
把第三方文字放進明確的資料欄位，禁止其改變工具定義或權限；對工具來源做命名空間隔離、指紋固定與版本稽核，並在伺服器端重新檢查授權。