3.3 API 經濟學與 ACI 商業介面設計
學完本節,你能夠:
- 用「服務窗口」的比喻解釋 API,並舉例說明 API 如何成為企業的商業模式。
- 說明 ACI(給 AI Agent 用的介面)與 HCI(給人用的介面)的差異,並依四項原則檢查一個工具定義。
- 用一段 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 節 商業工具設計原則 |
本節小結
- API 是系統之間的服務窗口;把複雜能力包裝成好用的 API,本身就能成為商業模式。
- 當使用者從人變成 AI Agent,介面要從「好看好點」轉為「文字說清楚、輸入有限制、重送不重做、錯誤能指路」。
- 冪等鍵代表「一筆交易」,重試時必須沿用同一把,才能防止重複付款。
- 冪等是 API 端的責任,因為 Agent 從回應上根本看不出差別。
柒、練習
- 改數字(5 分鐘):在程式中再多加一行重試(共重試兩次)。沒有冪等設計時,實際扣款總額是多少?有冪等設計時呢?
- 加功能(20 分鐘):為「海外倉建立出庫單」設計一個工具定義,包含:清楚的工具名稱、至少一個用選項清單限制的參數(例如倉庫代碼)、冪等鍵欄位,以及一則「庫存不足」時的錯誤訊息(要寫出
suggested_action)。 - 管理反思(討論):有主管說「API 只是工程師在後台接線的工具,跟競爭力無關」。請用 Stripe 或 Twilio 的例子反駁。再想一想:如果出庫 API 沒有冪等設計,大促期間網路壅塞時,倉庫現場會發生什麼混亂?