3.3 API 經濟學與 ACI 商業介面設計

學完本節,你能夠:

  1. 用「服務窗口」的比喻解釋 API,並舉例說明 API 如何成為企業的商業模式。
  2. 說明 ACI(給 AI Agent 用的介面)與 HCI(給人用的介面)的差異,並依四項原則檢查一個工具定義。
  3. 用一段 Python 模擬,示範「冪等鍵」如何防止逾時重試造成的重複付款。

壹、開場情境:AI 助理付了兩次款

📌 以下為教學情境(依實務改編)。

鍵盤外銷公司導入一個 AI 助理,讓它幫採購人員處理例行工作:查庫存、建立出貨單、對供應商付款。助理不是靠「看螢幕」操作,而是呼叫公司系統提供的 API。

某天,助理對越南供應商送出一筆 US$ 5,000 的貨款。銀行那端其實已經扣款成功,但回應在網路上遺失,助理等不到結果,判斷為「逾時」,於是自動重試一次。月底對帳時,財務發現同一張採購單被付了 US$ 10,000,多付的 US$ 5,000 要花好幾週向供應商追回。

AI 沒有做錯任何一步:逾時就重試,本來就是合理的做法。問題出在付款 API 的設計:它分不出「這是同一筆付款的重試」還是「一筆新的付款」。

本節要解決的問題: 當使用 API 的不再只是工程師,而是會自己判斷、自己重試的 AI Agent,介面應該怎麼設計才安全?


貳、為什麼會這樣:API 經濟與介面的新使用者

1. API 是數位世界的服務窗口

API(Application Programming Interface,應用程式介面)規定了:外部可以向你提出什麼請求、要附上哪些資料、會拿到什麼結果。就像銀行櫃台:填對表單、交給窗口,就能拿到結果,不需要知道後台怎麼運作(第 3.1 節的「黑盒子」)。

把複雜能力包裝成好用的 API,本身就能成為商業模式:

企業/系統 把什麼複雜的事包裝起來 商業意義
Stripe 跨國刷卡收款、多幣別、支付合規 開發者用幾行程式就能收全球款項,Stripe 按交易收手續費
Twilio 各國電信網路的簡訊與語音 企業發驗證碼、出貨通知不必逐國談電信合約
關港貿單一窗口 報關、簽審等通關文件的電子化申辦 業者可用系統連線申報,減少紙本往返

2. 從 HCI 到 ACI

💡 AI Agent:能依目標自己規劃步驟、呼叫工具(API)並根據結果決定下一步的 AI 程式。第 8 章會完整介紹。

HCI(人機介面) ACI(Agent–電腦介面)
使用者 人 AI Agent
靠什麼理解 畫面、按鈕、顏色、常識 工具名稱、參數說明、資料型別、錯誤訊息的文字
設計不良的後果 使用者困惑、多點幾下 Agent 猜錯參數、反覆重試、執行錯誤交易
會不會自動重試 人通常會先打電話確認 會,而且可能很快、很多次

最後一列就是開場情境的根源:給人用的付款按鈕,按一次就是一次;給 Agent 用的付款 API,必須預期「同一個請求可能被送好幾次」。


參、把規則寫下來:ACI 設計四原則

以「付款」與「計算進口稅」兩個工具為例:

原則 不好的設計 好的設計 防止什麼
① 名稱說清楚用途 calc(a, b, x) calculate_import_duty(cif_amount, hs_code, destination_country) Agent 不知道何時該用、參數該填什麼
② 用選項清單限制輸入 trade_term:自由文字 只能從 FOB、CIF、DDP、EXW 中選 Agent 填出 fob、F.O.B.、Free On Board 等各種寫法
③ 冪等:重送不重做 每收到一次請求就付一次款 每筆付款附一個冪等鍵,同一把鍵只處理一次 逾時重試造成重複付款
④ 錯誤訊息要能指引下一步 回傳「500 系統錯誤」 說明錯在哪裡、該怎麼修正 Agent 盲目重試或亂猜

原則② 源自豐田生產方式的防呆(Poka-yoke):與其事後抓錯,不如讓錯誤根本無法輸入。用 JSON 格式寫成工具定義如下(Incoterms 2020 共 11 種貿易條件,這裡假設公司政策只接受其中 4 種):

"trade_term": {
  "type": "string",
  "enum": ["FOB", "CIF", "DDP", "EXW"],
  "description": "Incoterms 2020 貿易條件代碼;本公司只接受這四種"
}

原則④ 的好例子:

{
  "status": "error",
  "error_code": "HS_CODE_TOO_SHORT",
  "message": "收到的 HS Code「6109」只有 4 碼。計算稅額至少需要國際通用的 6 碼。",
  "suggested_action": "請先呼叫 search_hs_code 查出完整代碼後再試一次。"
}

原則③ 的規格,就是開場情境缺少的那一條:

業務說的話 追問 寫成規格
「不要重複付款」 怎麼判斷是不是同一筆? 呼叫端為每一筆付款產生唯一編號(冪等鍵),例如採購單號加流水號 PO-20261005-0001
(沒人說) 收到重複的鍵怎麼辦? 不再扣款,直接回傳第一次的處理結果
(沒人說) 鍵要保留多久? 至少涵蓋可能重試的期間(例如 24 小時),由財務與資訊部共同訂定

實務上,Stripe 等金流 API 都提供類似的冪等鍵機制,讓呼叫端在重試時帶上同一把鍵。


肆、動手模擬:冪等鍵如何擋住重複付款

這段 Python 不需要安裝任何東西,可以貼到 Google Colab 直接執行。它模擬開場情境:第一次請求扣款成功但回應遺失,Agent 自動重試一次。

# 模擬「付款 API」:比較有無冪等鍵時,逾時重試的結果
AMOUNT_USD = 5000   # 這筆採購付款金額(商業參數放最上方)

class PaymentServer:
    def __init__(self, idempotent):
        self.idempotent = idempotent  # 是否具備冪等設計
        self.charged = 0              # 實際扣款總額
        self.seen = {}                # 冪等鍵 → 上次的處理結果

    def pay(self, key, amount):
        if self.idempotent and key in self.seen:
            return self.seen[key]     # 同一把鍵:回傳上次結果,不再扣款
        self.charged += amount        # 真的扣款
        result = f"已扣款 US${amount:,}"
        self.seen[key] = result
        return result

for idempotent in (False, True):
    server = PaymentServer(idempotent)
    key = "PO-20261005-0001"          # 由呼叫端為「這一筆付款」產生的唯一編號

    server.pay(key, AMOUNT_USD)       # 第 1 次:銀行扣款成功,但回應在網路上遺失
    reply = server.pay(key, AMOUNT_USD)  # Agent 沒收到回應,自動重試

    print("冪等設計:", "有" if idempotent else "沒有")
    print("  重試收到的回應:", reply)
    print(f"  實際扣款總額:US${server.charged:,}")

執行結果:

冪等設計: 沒有
  重試收到的回應: 已扣款 US$5,000
  實際扣款總額:US$10,000
冪等設計: 有
  重試收到的回應: 已扣款 US$5,000
  實際扣款總額:US$5,000

注意:兩種設計下,Agent 收到的回應一模一樣,從 Agent 的角度完全看不出差別。差別只在銀行帳上。這就是為什麼冪等性必須設計在 API 端,而不能指望 Agent「小心一點」。

🔍 驗收重點 - 冪等鍵是代表「這一筆付款」,還是「這一次請求」?重試時必須帶同一把鍵。 - 收到重複的鍵時,是否回傳第一次的結果,而不是報錯?(報錯可能讓 Agent 以為付款失敗,又改用別的方法再付一次。)


伍、跑跑看、壞給你看

實驗 操作 預期結果 想想看
① 金額放大 把 AMOUNT_USD 改成 12000 無冪等:扣 US$ 24,000;有冪等:US$ 12,000 金額越大、重試越多次,損失越大
② 鑰匙用錯 把重試那行改成 server.pay(key + "-retry", AMOUNT_USD) 兩種設計都扣了 US$ 10,000 冪等機制還在,為什麼擋不住?
③ 判斷工具定義 檢查一個名為 do_task(data)、參數為自由文字的工具 違反原則①②④ 你會怎麼改名、怎麼限制參數?

實驗②是最常見的實務錯誤:如果呼叫端每次重試都產生一把新鍵,伺服器只會當成另一筆新付款。機制有了,但用錯了,等於沒有。


陸、回到情境

付款 API 加上冪等鍵後,助理逾時重試只會拿到「已扣款 US$ 5,000」的原始結果,不會再付第二次。

還有哪些問題沒解決?

限制 後果 在哪一節解決
冪等只防「重複」,不防「付錯對象、付錯金額」 Agent 仍可能一次就付錯 第 9.4 節 熔斷、第 13.2 節 雙簽
付款這種高風險動作,是否該讓 Agent 直接執行? 一次錯誤就是真金白銀 第 8.2 節 工具分級與人工審批
本節只談四原則,還沒談完整的工具設計方法 實際封裝 ERP 工具時仍缺方法 第 8.1 節 商業工具設計原則

本節小結

  1. API 是系統之間的服務窗口;把複雜能力包裝成好用的 API,本身就能成為商業模式。
  2. 當使用者從人變成 AI Agent,介面要從「好看好點」轉為「文字說清楚、輸入有限制、重送不重做、錯誤能指路」。
  3. 冪等鍵代表「一筆交易」,重試時必須沿用同一把,才能防止重複付款。
  4. 冪等是 API 端的責任,因為 Agent 從回應上根本看不出差別。

柒、練習

  1. 改數字(5 分鐘):在程式中再多加一行重試(共重試兩次)。沒有冪等設計時,實際扣款總額是多少?有冪等設計時呢?
  2. 加功能(20 分鐘):為「海外倉建立出庫單」設計一個工具定義,包含:清楚的工具名稱、至少一個用選項清單限制的參數(例如倉庫代碼)、冪等鍵欄位,以及一則「庫存不足」時的錯誤訊息(要寫出 suggested_action)。
  3. 管理反思(討論):有主管說「API 只是工程師在後台接線的工具,跟競爭力無關」。請用 Stripe 或 Twilio 的例子反駁。再想一想:如果出庫 API 沒有冪等設計,大促期間網路壅塞時,倉庫現場會發生什麼混亂?

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

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

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

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