8.1 工具設計的通用原則（ACI）#

工具：Agent 的「手」#

回顧核心公式 Agent = LLM + Context + Tools：上下文（Context） 讓模型「看得懂」，而 工具（Tools） 讓模型「做得到」。

沒有工具的 LLM，只是一個「會講話的知識庫」——它能回答「該怎麼刪除資料庫」，卻無法真的「刪除資料庫」。工具賦予 Agent 行動能力：讀檔案、執行指令、呼叫 API、操作外部系統。工具是 Agent 從「想」到「做」的橋樑。

而工具有沒有被「正確使用」，往往就是 Agent 成敗的關鍵。本節探討如何設計「讓 Agent 願意且正確使用」的工具——這就是 ACI（Agent-Computer Interface） 的主題，我們在 3.3 節已建立基礎。

回顧：ACI 的核心洞見#

3.3 節我們定義了 ACI（Agent-Computer Interface）：研究「如何設計讓 Agent 友善的介面」的範式，類比於 HCI（人機互動）。

對人友善的介面，不見得對 Agent 友善。Agent「使用介面」的方式與人截然不同：

• 人：靠視覺、直覺、點擊，看選單就能瀏覽
• Agent：靠文字描述的工具定義（Tool Definition），完全依賴介面「告訴它」每個工具是做什麼、怎麼用

因此，Agent「會不會用錯工具」，幾乎完全由「工具定義寫得好不好」決定。這把「工具設計」的地位，提升到決定 Agent 成敗的關鍵。

工具設計的通用原則#

以下是設計 Agent 工具時，應該遵守的核心原則（也是 3.3 節的延伸與操作化）：

1. 命名直觀、語意清楚#

工具名稱與參數名稱應清楚表達「做什麼、含意是什麼」。模糊的名字讓 Agent 不知道該何時用、怎麼用。

• 好：create_reservation(restaurant_id, party_size, time)
• 差：fn1(a, b, x)

原則是：當 Agent 不確定一個工具該不該用時，傾向於「不用」或用「錯」——而這往往始於一個理解不清的工具定義。

2. 參數要有描述、型別與例子#

每個參數給出：型別、不要模糊、可選擇的範圍、以及具體例子。

text (string, 必填)：要翻譯的文字，例："你好，世界"
target_lang (string, 必填)：目標語言代碼，例："en"、"ja"、"zh"

範例比抽象的型別更有助於 Agent 正確填參。

3. 用結構化與防呆設計消除「非法」#

把「合法取值」鎖死在設計裡，讓 Agent「根本無法錯」——這是 3.3 節的防呆（Poka-yoke）原則：

• 能用列舉（enum）就不要自由字串：unit: "Celsius" | "Fahrenheit"，而不是「請填溫度單位」
• 必填就設必填，別讓 Agent 省略
• 有格式就用格式約束（如日期 YYYY-MM-DD）

設計哲學：好的介面讓錯誤「無從發生」，而不是「發生了再容忍」。

4. 說明工具的邊界與前提#

清楚寫明工具的限制與使用前提，例如：

• 此工具只接受 0-99 的整數
• 此工具無法處理超過 10MB 的檔案
• 呼叫此工具前，請先確保已登入

把「不能做什麼、需要什麼前提」講清楚，Agent 才不會越界或漏掉前置步驟。

5. 提供可程式處理的錯誤（而非模糊訊息）#

當工具出錯時，回傳結構化、可程式處理的錯誤，讓 Agent 能理解原因並採取對應（如重試、換參數）：

{ "error": { "code": "INVALID_AMOUNT", "message": "金額必須為正數", "detail": { "field": "amount" } } }

失敗的回饋極其重要#

工具設計常被忽略、卻極其關鍵的一點是：失敗的回饋。

Agent 與工具互動時，絕大多數問題不是「第一次就成功」，而是「失敗後如何調整」。因此：

• 錯誤訊息要足夠好，讓 Agent 能「看懂哪裡錯、該怎麼改」
• 失敗的種類要可區分（暫時性錯誤 vs 永久性錯誤），Agent 才知道該「重試」還是「換作法」
• 必要時提供「下一步建議」（如「參數 unit 只能填 Celsius 或 Fahrenheit」）

一句話：工具設計不只是「讓成功更順利」，更是「讓失敗更可調」。 這是 Agent 可靠性的地基（9.3、9.4 節會深入）。

工具即 API：從 ACI 三原則到具體規範#

3.3 節提出了 ACI 的設計原則，本節把它操作化成「ITD（工具即介面）三面向」：

1. 語意：工具要「好懂」——名字、描述、參數範例都要清楚
2. 結構：介面要「防呆」——enum、必填、格式約束
3. 錯誤：行為要「可調」——結構化、可區分的錯誤與回饋

對照範例（好 vs 壞）：

本章小結#

• 工具是 Agent 從「想」到「做」的橋樑；工具用得好不好決定 Agent 成敗
• ACI：設計對 Agent 友善的介面（3.3 節的深化）
• 核心原則：命名直觀、參數有描述/型別/例子、防呆結構、講清邊界、結構化錯誤
• 失敗的回饋極其重要：成功靠工具「順」，可靠靠失敗「可調」
• 三面向：語意（好懂）、結構（防呆）、錯誤（可調）

想一想#

1. 找出你常用的某個 API 或工具，用本節的三面向（語意/結構/錯誤）評估它「對 Agent 友善」的程度。
2. 為什麼「失敗的回饋」對 Agent 特別重要？第一次就成功的機率其實不高，失敗後能自我調整才是關鍵。
3. 設計一個「線上訂位」的工具，落實命名、參數範例、enum 防呆與結構化錯誤。