8.1 商業工具設計通用原則(ACI)

學完本節,你能夠:

  1. 說明 AI 是靠工具的「名稱、說明、參數規格」三樣東西決定要不要用、怎麼用一個工具。
  2. 用語義、結構、回饋三個維度,檢查並改寫一份設計不良的工具定義。
  3. 把「下銷售訂單」這條業務規則寫成有防呆限制的參數規格(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 提示注入防禦

本節小結

  1. AI 看不到程式碼,只看得到工具的名稱、說明、參數規格與回傳結果;這些就是 ACI。
  2. 語義讓 AI 選對工具,結構讓 AI 填不錯參數,回饋讓 AI 失敗時知道下一步。
  3. 說明是請求、規格是限制:能用 minimum、enum、additionalProperties 擋的,不要只寫在說明裡。
  4. 一個工具只做一件事,讀與寫分開,是後面所有權限設計的基礎。

柒、練習

  1. 改數字(5 分鐘):公司規定 AI 單筆最多只能代下 50 台。請修改第肆段 Python 程式中的一行,重新執行。6 筆的通過/擋下結果有改變嗎?哪一筆的訊息內容變了?請再自己新增一筆「改規則前會通過、改規則後會被擋下」的測試資料(例如 60 台)。
  2. 加功能(20 分鐘):替 ERP 設計第三個工具 create_purchase_order(採購進貨,對應 採購進貨單 分頁的「採購品項、進貨數量、本次單價 EUR」)。請依第參段的格式先寫規格表,再寫出 JSON Schema,並用第肆段的程式驗證它能擋下「進價為 0」與「數量為小數」。
  3. 管理反思(討論):某公司給 AI 一個 send_payment(receiver_id, amount) 工具,只有兩個參數。請用本節三個維度指出它的缺陷:說明缺了什麼?參數該加哪些限制(幣別列舉、金額上限、收款人白名單)?付款失敗時應回傳什麼?最後想一想:有哪些限制「不該」交給工具規格,而應該交給人來核准?

國立臺中科技大學 國際貿易系 / 企業管理系 專用教材

《現代軟體工程:商學院的 AI 系統思維與 Agent 實踐》

作者:陳俊智 博士 Dr. Chun-Chih Chen

本書章節架構改編自陳鍾誠教授(金門大學)開源課程《現代軟體工程》(github.com/ccc115a/se,MIT 授權),內容針對商學院全面改寫與擴充。