從「會做事」到「能辦事」

Day 6 我們幫 Agent 定好了職責。但職責再清楚，如果它只能在自己的資料夾裡打轉，還是不夠「可用」。

真正可用的 Agent，要能碰到你的真實系統——去查一筆訂單、更新一個任務狀態、抓一份報表、發一則通知。這些都靠同一件事：呼叫 API。

Day 5 我提過「給 Agent 工具」有兩條路（直接 curl vs MCP）。今天我們把最實用、最好上手的那條——直接呼叫 API——講到你能實際做出來。

Agent 呼叫 API，其實就三件事

不要被「整合」這個詞嚇到。Agent 打一個 API，本質上跟你在終端機打 curl 一模一樣，它只需要知道三件事：

1. 打去哪裡（endpoint URL）
2. 怎麼證明身分（authentication）
3. 資料長什麼樣（request 格式 + response 怎麼解析）

只要這三件事講清楚，Agent 就能自己組出正確的呼叫、送出去、把結果讀回來。難的不是「怎麼打」，難的是**「讓它每次都打對」**——這才是今天真正的重點。

最大的坑：Agent 會「憑印象」亂打

這是我用血換來的教訓，你一定要先知道：

如果你不把 API 的規格明確寫給 Agent，它會憑訓練資料裡的「印象」去猜——而它猜的，經常是錯的。

最常見的三種猜錯：

• 認證方式猜錯：有的 API 用 Authorization: Bearer xxx，有的用 X-API-Key: xxx。Agent 可能兩個混用，結果收到一個看起來像權限問題、其實是你 header 帶錯的 401，然後它開始往錯的方向 debug。
• request 格式猜錯：這個 endpoint 要的是 JSON body，還是 multipart/form-data？猜錯的話，你會收到一個 422，而且它可能反覆用同一種錯格式重試。
• 欄位名猜錯：狀態欄位要填 done 還是 completed？ID 要用數字還是編號？

我艦隊裡真的踩過這些：一個內部服務的回覆是 multipart，Agent 卻一直送 JSON，收 422 收到懷疑人生；另一個服務認證要 X-API-Key，Agent 卻套了 Bearer。這些都不是 Agent 笨，是我一開始沒把規格寫下來給它。

解法：把 API 的「使用說明」寫在 Agent 讀得到的地方

還記得 Day 3 的 CLAUDE.md 和 Day 4 的記憶嗎？API 的規格就寫在那裡（或一份專門的操作手冊，Day 11 會講的 Skill 系統）。一份好的 API 說明長這樣：

## 呼叫任務系統 API

- Base URL：https://task.internal.example.com
- 認證：header 帶 `X-API-Key: <金鑰>`（不是 Bearer！）
- 更新任務狀態：
    PATCH /tasks/{id}
    body（JSON）：{"status": "done"}   # 完成用 done，不是 completed
- 常見錯誤：
    - 401 → 先檢查是不是把 Bearer 誤當成 X-API-Key
    - 422 → 檢查 body 是不是該用 multipart 而不是 JSON

把「怎麼打、認證怎麼帶、格式是什麼、踩過什麼坑」寫死，Agent 就從「憑印象猜」變成「照說明書做」。這一步做不做，決定你的 Agent 是可靠工具還是薛丁格的貓。

一個具體的例子：讓 Agent 更新任務狀態

假設你有一個任務系統，你想讓 Agent 做完事後自己把任務標成完成。你在 CLAUDE.md 寫好上面那段說明後，只要跟它說：

把任務 123 標成完成

它就會自己組出：

curl -X PATCH https://task.internal.example.com/tasks/123 \
  -H "X-API-Key: $TASQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "done"}'

送出、讀回結果、跟你確認。你完全不用教它 curl 語法——它會，你只要給它「這個 API 的規矩」。

別忘了那條線：讀 vs 寫

Day 5 講過「工具 = 權力」，呼叫 API 同樣適用：

• 唯讀的 API（查訂單、抓報表）→ 通常可以放心讓 Agent 自由呼叫
• 會改東西的 API（改狀態、送通知、扣款）→ 你會希望它動之前先確認，尤其是對外、不可逆、會花錢的

一個實用的習慣：把「唯讀」和「會寫」的 API 在說明裡分開標記，讓 Agent（和你）一眼就知道哪些要小心。

還有一件事：讓它「真的看結果」，別假設成功

API 打出去了，不代表成功。我看過 Agent 犯的錯是：把一個錯誤回應當成正常結果。

例如某個 API 出錯時回 {"detail": "Method Not Allowed"}，但 Agent 的解析邏輯直接抓「結果清單」欄位、抓不到就當成「查到 0 筆」——於是一個「打錯端點」被它誤解成「這裡沒資料」，往下全錯。

所以規格說明裡要多寫一句：先看 HTTP 狀態碼 / 有沒有 error 欄位，再解析內容。 讓 Agent 學會分辨「這條路失敗了」和「這條路成功但沒資料」——這兩個差很多。

今天的重點回顧

• Agent 呼叫 API 只需知道三件事：打去哪、怎麼證明身分、資料長怎樣。
• 最大的坑是它會憑印象猜 API 格式（認證 Bearer vs X-API-Key、JSON vs multipart、done vs completed）——猜錯就收到誤導性的 401/422。
• 解法：把 API 的「使用說明 + 踩過的坑」寫在 Agent 讀得到的地方（CLAUDE.md / 手冊），讓它照說明書做，不要憑印象。
• 讀 vs 寫要分開對待；會改 / 對外 / 花錢的 API 設關卡。
• 讓 Agent 先看狀態碼再解析，別把錯誤回應誤當成「沒資料」。

明天 Day 8：現在 Agent 會定義自己、會打 API 辦事了，但它還是「你叫一次它動一次」。要讓它變成真正的助手，得讓它自己 24/7 醒著、有事就自己撿來做——我們進入 Daemon 模式，這是「單一 Agent」邁向「艦隊」最關鍵的一躍。

Genos Lin 是一位技術創辦人，同時擔任多個 AI 導入客戶案的技術顧問。他目前維運一套由 39 個 Claude Code Agent 組成的自動化系統，用於產品開發、業務流程自動化與客戶服務。