8.1 商業工具設計通用原則(ACI)
學完本節,你能夠:
- 說明 AI 是靠工具的「名稱、說明、參數規格」三樣東西決定要不要用、怎麼用一個工具。
- 用語義、結構、回饋三個維度,檢查並改寫一份設計不良的工具定義。
- 把「下銷售訂單」這條業務規則寫成有防呆限制的參數規格(JSON Schema),並驗證它能擋下哪些錯誤輸入。
壹、開場情境:AI 助理第一天上班就下錯單
📌 以下為教學情境(依實務改編)。
第 4.2 節的進銷存試算表已經上線。資訊組想讓業務經理用一句話就能查庫存、下訂單,於是替 AI 助理接上一個「萬用工具」:
{ "name": "do_sheet", "description": "操作試算表", "parameters": { "action": "string", "data": "string" } }
經理說:「A 款還有沒有貨?有的話幫台中經銷商下 25 台,單價 4,200。」結果發生了三件事:
| 發生什麼事 | 問題出在哪 |
|---|---|
AI 不知道 action 該填什麼,先試了 "read"、再試 "query",最後填了 "update",把庫存那格改成 25 |
名稱與說明太模糊,AI 只能猜 |
data 被填成 "A款 25台 4200元",品名、數量、單價全擠在一串文字裡 |
參數沒有結構,什麼都能塞 |
工具回傳 {"error": "fail"},AI 回覆經理「已完成下單」 |
失敗訊息沒有內容,AI 只好自己編 |
程式本身沒有壞,壞的是 AI 和系統之間的那道「介面」。
本節要解決的問題: 一個要交給 AI 使用的商業工具,應該怎麼定義,AI 才會選對、填對,失敗時也知道下一步怎麼做?
貳、為什麼會這樣:AI 看不到你的程式碼
本書把 Agent 拆成三個部分:
Agent = LLM(判斷) + Context(情境與記憶) + Tools(能實際動手的工具)
沒有工具的 LLM 只能「說」,不能「做」:它可以分析運價為什麼上漲,卻查不到你倉庫裡還有幾台貨。工具讓它能讀 ERP、寄信、建立訂單,但這也代表介面設計不好時,錯誤會直接落在帳上。
關鍵在於:AI 決定呼叫哪個工具時,看不到工具背後的程式碼,只看得到三樣東西:
| AI 看得到的 | 例子 | 對應的設計維度 |
|---|---|---|
| 名稱(name) | create_sales_order |
語義 |
| 說明(description) | 「在銷售訂單新增一筆並扣減庫存…」 | 語義 |
| 參數規格(input schema) | quantity 必須是 1~100 的整數 |
結構 |
| (呼叫之後)回傳結果 | 「庫存不足,僅剩 25 台」 | 回饋 |
為 AI 設計的這層介面稱為 ACI(Agent-Computer Interface,代理-電腦介面),對應人類使用的 HCI(人機介面)。第 3.3 節已從 API 的角度介紹過 ACI 的原則(含防止重複扣款的冪等性);本節聚焦在一份工具定義本身該怎麼寫。
三個維度一次看
| 維度 | 要回答的問題 | 做不好的後果 | 做法 |
|---|---|---|---|
| 語義(Semantic) | AI 知道何時該用這個工具嗎? | 選錯工具、該用時不用 | 動詞+對象的命名;說明寫清用途、適用範圍、與其他工具的分界 |
| 結構(Structural) | AI 填錯參數時,系統擋得住嗎? | 負數數量、自創欄位、文字塞進數字欄 | 型別、必填、數值範圍、列舉(enum)、禁止額外欄位 |
| 回饋(Feedback) | 失敗時,AI 知道下一步嗎? | AI 放棄,或更糟:假裝成功 | 回傳錯誤代碼、具體數字、建議的下一步 |
💡 一條原則:說明是「請求」,規格是「限制」。 寫在 description 裡的「請勿輸入負數」,AI 可能遵守也可能忘記;寫在參數規格裡的
"minimum": 1,系統會直接拒絕。能用規格擋的,就不要只靠說明。
參、把規則寫下來:一個「下訂單」工具的規格
業務主管說:「讓 AI 可以幫業務下單。」先把這句話拆開:
| 主管說的話 | 需要追問的問題 | 寫成規格 |
|---|---|---|
| 「幫業務下單」 | 查庫存和下單是同一件事嗎? | 拆成兩個工具:check_erp_inventory(只讀)、create_sales_order(寫入) |
| 「填品名就好」 | 「A款」和「人體工學鍵盤 A款」算同一個嗎? | 下單必須用完整品名;說明中規定先查庫存取得完整品名 |
| 「數量照客戶說的」 | 可以是 0、負數、小數嗎?上限多少? | 整數,1~100;超過 100 台走人工流程 |
| 「單價用台幣」 | 可以是 0 嗎? | 數字,必須大於 0 |
| (主管沒說) | AI 自己多加一個「折扣」欄位怎麼辦? | 不接受規格以外的欄位 |
| (主管沒說) | 庫存不足時要回傳什麼? | 回傳錯誤代碼、現有庫存、可行的下一步 |
注意第一列:一個工具只做一件事。開場的 do_sheet 把讀和寫混在一起,AI 光是查庫存都有機會改到帳。第 8.2 節會進一步依風險把工具分類。
肆、動手寫一份工具定義
1. 語義:名稱與說明
{
"name": "create_sales_order",
"description": "在 ERP「銷售訂單」新增一筆訂單,並立即扣減「庫存主檔」的庫存。會改變正式帳務資料:呼叫前必須先用 check_erp_inventory 取得完整品名,並向使用者複述客戶、品名、數量、單價取得同意。只處理現貨出貨;預購或樣品請改走人工流程。"
}
這段說明交代了四件事:做什麼(新增訂單、扣庫存)、副作用(會改帳)、前置步驟(先查庫存、先確認)、不適用範圍(預購、樣品)。
2. 結構:參數規格(JSON Schema)
AI 工具普遍使用 JSON Schema 描述參數:它是一份「表單填寫規則」,規定每個欄位的型別、是否必填、數值範圍。
{
"type": "object",
"properties": {
"customer": { "type": "string", "minLength": 1, "description": "客戶名稱" },
"item_name": { "type": "string", "minLength": 1, "description": "完整品名,須與 check_erp_inventory 回傳的 itemName 完全相同" },
"quantity": { "type": "integer", "minimum": 1, "maximum": 100, "description": "銷售數量(整數)" },
"unit_price_twd": { "type": "number", "exclusiveMinimum": 0, "description": "銷售單價(新台幣)" }
},
"required": ["customer", "item_name", "quantity", "unit_price_twd"],
"additionalProperties": false
}
3. 驗證:這份規格到底擋得住什麼?
不用相信規格「應該」有效,跑一次就知道。以下 Python 程式用 jsonschema 套件模擬 6 種 AI 可能送出的參數(執行方式見附錄 E;需先 pip install jsonschema):
from jsonschema import validate, ValidationError
# 工具 create_sales_order 的參數規格(inputSchema)
MAX_ORDER_QTY = 100
schema = {
"type": "object",
"properties": {
"customer": {"type": "string", "minLength": 1},
"item_name": {"type": "string", "minLength": 1},
"quantity": {"type": "integer", "minimum": 1, "maximum": MAX_ORDER_QTY},
"unit_price_twd": {"type": "number", "exclusiveMinimum": 0},
},
"required": ["customer", "item_name", "quantity", "unit_price_twd"],
"additionalProperties": False,
}
calls = {
"正常訂單": {"customer": "台中經銷商", "item_name": "人體工學鍵盤 A款", "quantity": 25, "unit_price_twd": 4200},
"負數數量": {"customer": "台中經銷商", "item_name": "人體工學鍵盤 A款", "quantity": -5, "unit_price_twd": 4200},
"小數數量": {"customer": "台中經銷商", "item_name": "人體工學鍵盤 A款", "quantity": 2.5, "unit_price_twd": 4200},
"超過上限": {"customer": "台中經銷商", "item_name": "人體工學鍵盤 A款", "quantity": 150, "unit_price_twd": 4200},
"自創欄位": {"customer": "台中經銷商", "item_name": "人體工學鍵盤 A款", "quantity": 25, "unit_price_twd": 4200, "discount": 0.3},
"漏填單價": {"customer": "台中經銷商", "item_name": "人體工學鍵盤 A款", "quantity": 25},
}
for name, args in calls.items():
try:
validate(args, schema)
print(f"{name}:✅ 通過")
except ValidationError as e:
print(f"{name}:🛑 擋下({e.message})")
執行結果:
正常訂單:✅ 通過
負數數量:🛑 擋下(-5 is less than the minimum of 1)
小數數量:🛑 擋下(2.5 is not of type 'integer')
超過上限:🛑 擋下(150 is greater than the maximum of 100)
自創欄位:🛑 擋下(Additional properties are not allowed ('discount' was unexpected))
漏填單價:🛑 擋下('unit_price_twd' is a required property)
「自創欄位」那一列值得多看一眼:AI 有時會「好心」幫客戶加個 30% 折扣。additionalProperties: false 讓這種即興發揮直接失效。
4. 回饋:失敗時要說清楚
第 4.2 節的 ERP 在庫存不足時回傳一段文字:「出貨失敗!人體工學鍵盤 A款 目前倉庫僅剩 25 台,客戶欲訂購 30 台。」這已經比 {"error": "fail"} 好很多,因為有具體數字。若再整理成結構化格式,AI 更容易接著處理:
{
"success": false,
"error_code": "INSUFFICIENT_STOCK",
"message": "人體工學鍵盤 A款 目前僅剩 25 台,客戶欲訂購 30 台。",
"available_stock": 25,
"suggested_next_steps": [
"詢問使用者:是否先出貨 25 台,其餘 5 台待補貨後再出?",
"不要自行更改數量重新下單"
]
}
第二條建議同樣重要:回饋不只告訴 AI 可以做什麼,也告訴它不可以做什麼。 AI 看到「只剩 25 台」,可能會「聰明地」直接改成下 25 台;但改數量是要跟客戶確認的商業決定。
🔍 驗收重點(不懂語法也能檢查) - 一個工具是否只做一件事?讀和寫有沒有分開? - 說明有沒有寫「不適用範圍」與「副作用」? - 數量、金額有沒有
minimum/maximum?是否禁止額外欄位? - 失敗時的回傳,是否包含具體數字與「下一步」?
伍、判斷看看:常見誤解
| 說法 | 對嗎? | 說明 |
|---|---|---|
| 「說明寫得越長越好,把所有規則都寫進去。」 | ⚠️ | 說明要寫用途與分界,但硬性限制應該放進參數規格;只寫在說明裡的規則 AI 可能忽略 |
| 「工具越少越好,做一個萬用工具最省事。」 | 🛑 | 萬用工具讓 AI 必須猜 action 怎麼填,且讀寫權限無法分開 |
| 「參數規格擋住了,後端就不用再檢查。」 | 🛑 | 規格只約束「透過這個工具」送進來的請求;有人繞過工具直接呼叫後端時就失效(第 8.3 節實驗會示範) |
| 「錯誤訊息是給工程師看的,簡單就好。」 | 🛑 | 在 Agent 系統裡,錯誤訊息的第一個讀者是 AI,它會根據內容決定下一步 |
陸、回到情境
把 do_sheet 換成本節的兩個工具後,開場的三個問題分別被處理:
| 開場問題 | 處理方式 |
|---|---|
AI 猜 action,誤改庫存 |
拆成唯讀的 check_erp_inventory 與寫入的 create_sales_order,名稱即用途 |
| 參數擠成一串文字 | 四個欄位各有型別與範圍,負數、小數、自創欄位都被擋下 |
| 失敗後假裝成功 | 回傳錯誤代碼、現有庫存與建議下一步 |
但工具定義寫得再好,仍有做不到的事:
| 限制 | 後果 | 在哪一節解決 |
|---|---|---|
| 每個工具的風險不同,卻用同一套放行標準 | 查庫存和下大單一樣容易被執行 | 8.2 依風險分類工具與人工核准 |
| 工具定義只是一份「文件」,還沒有真正接上試算表 | AI 仍然無法動手 | 8.3 用 MCP 把 ERP 包裝成工具 |
| 規格只擋格式,擋不住「格式正確但不該做」的請求 | 例如被惡意指令誘導下一張合法格式的大單 | 第 9 章 約束與驗證、13.1 提示注入防禦 |
本節小結
- AI 看不到程式碼,只看得到工具的名稱、說明、參數規格與回傳結果;這些就是 ACI。
- 語義讓 AI 選對工具,結構讓 AI 填不錯參數,回饋讓 AI 失敗時知道下一步。
- 說明是請求、規格是限制:能用
minimum、enum、additionalProperties擋的,不要只寫在說明裡。 - 一個工具只做一件事,讀與寫分開,是後面所有權限設計的基礎。
柒、練習
- 改數字(5 分鐘):公司規定 AI 單筆最多只能代下 50 台。請修改第肆段 Python 程式中的一行,重新執行。6 筆的通過/擋下結果有改變嗎?哪一筆的訊息內容變了?請再自己新增一筆「改規則前會通過、改規則後會被擋下」的測試資料(例如 60 台)。
- 加功能(20 分鐘):替 ERP 設計第三個工具
create_purchase_order(採購進貨,對應採購進貨單分頁的「採購品項、進貨數量、本次單價 EUR」)。請依第參段的格式先寫規格表,再寫出 JSON Schema,並用第肆段的程式驗證它能擋下「進價為 0」與「數量為小數」。 - 管理反思(討論):某公司給 AI 一個
send_payment(receiver_id, amount)工具,只有兩個參數。請用本節三個維度指出它的缺陷:說明缺了什麼?參數該加哪些限制(幣別列舉、金額上限、收款人白名單)?付款失敗時應回傳什麼?最後想一想:有哪些限制「不該」交給工具規格,而應該交給人來核准?