顯示具有 API 標籤的文章。 顯示所有文章
顯示具有 API 標籤的文章。 顯示所有文章

Agent-Friendly API：把你的服務做成 Agent 拿得起來的工具

Agent-Friendly API：把你的服務做成 Agent 拿得起來的工具

前言

過去十年，我們為人類工程師設計 API：RESTful 命名、OpenAPI 文件、SDK 範例。但 2026 年，你的 API 多了一種呼叫者——AI Agent。它只讀三樣東西：工具名稱、描述文字、參數 schema，然後憑此決定要不要呼叫、怎麼呼叫。

結果是：同一支 API，人類工程師用得好好的，Agent 卻頻頻呼叫錯誤的工具、傳錯參數格式、被錯誤訊息困住。這不是模型不夠聰明，而是介面從來沒為它設計過。

Anthropic 在〈Building Effective Agents〉裡說過一句值得貼在牆上的話："Tools are a new kind of software which reflects a contract between deterministic systems and non-deterministic agents."（工具是一種新軟體，體現的是確定性系統與非確定性 Agent 之間的契約。）他們的建議很直白：在 Agent-Computer Interface（ACI）上花的功夫，應該要跟 Human-Computer Interface（HCI）一樣多。

這篇文章從服務提供者的角度出發：如果你手上有一支 API 或一個後端服務，要怎麼把它包裝成 Agent 拿得起來、用不壞的工具？五個原則，一個可跑的 MCP 範例。

一、換個腦袋：Agent 是另一種使用者

人類工程師和 Agent 讀介面的方式完全不同（如圖一）：

  • 人類會先讀文件、看範例、試錯幾次後記住慣例。Agent 沒有「記住」的機會——每次呼叫都是一次全新的閱讀理解。
  • 人類遇到模糊的錯誤訊息會去搜尋、問同事。Agent 只能靠錯誤訊息本身決定下一步；一句「Invalid request」對它來說等於死路。
  • 人類能從 50 個端點中憑經驗挑出對的那個。Agent 靠的是工具描述的語義相似度——描述寫得含糊，它就選錯。

所以第一個心態轉換是：工具描述不是文件，是路由訊號。MCP 生態有句實務格言：description 是模型決定要不要呼叫這個工具的「主要路由訊號」。寫描述的時候，想像你在對一個聰明但毫無上下文的新人說話——他只看得到這段文字。

二、五個設計原則

原則一：描述寫「何時用」，不只寫「做什麼」

壞描述只講功能：「搜尋文件並回傳結果。」好描述講觸發條件：

在內部知識庫搜尋公司文件、政策與流程。當使用者詢問公司內部資訊、人資流程，或任何可能記載於內部文件的問題時使用。回傳最相關的三段摘錄並附來源。不處理一般網頁搜尋與即時資料。

好的工具描述回答四件事：是什麼、何時用、回傳什麼、不處理什麼。最後一點最常被忽略——明確寫出不處理什麼，比寫做什麼更能防止選錯工具。

實務上限：描述控制在 200 字以內。太長的描述會稀釋路由訊號，模型反而抓不到重點。

原則二：參數要防呆（poka-yoke）

Anthropic 在打造 SWE-bench agent 時發現，模型在使用相對路徑的工具時頻頻出錯；把工具改成「只接受絕對路徑」之後，錯誤直接歸零。他們把這個概念叫做 poka-yoke（防呆）：與其指望模型不犯錯，不如讓錯誤的參數根本傳不進來。

落到 API 設計上：

  • 日期一律 ISO-8601（YYYY-MM-DD），不要讓模型猜 10/15/2026 是哪國格式。
  • 有限集合用 enum：status: [pending, paid, cancelled]，不要用自由文字。
  • 單位寫在參數名或描述裡：timeout_ms 比 timeout 好；預設值要合理（例如 5000）。
  • 每個參數都要有型別與描述——永遠不要指望模型「猜」參數。

原則三：Chunky tools——一個工具做完一件事

人類工程師喜歡細粒度的 REST 端點：查訂單、查客戶、查物流，三支 API 各司其職。但對 Agent 來說，每多一次呼叫就多一次出錯機會、多一段 context 消耗。

The New Stack 在〈How To Prepare Your API for AI Agents〉中引述的實務建議是：提供 "chunky" 工具——把多個端點包裝成「完成一個商業結果」的單一工具。例如與其讓 Agent 先查客戶、再查訂單、再查物流，不如給它 get_order_status_with_tracking，一次回傳訂單加物流狀態。

判斷標準：一個工具應該對應一個使用者意圖，而不是一個資料表。

但注意另一端：也不要把 get_user 和 update_user 硬塞成一個帶 mode 參數的工具。單一職責仍然成立——chunky 是指「按意圖聚合」，不是「全部塞在一起」。

原則四：錯誤訊息是寫給 Agent 的說明書

當工具呼叫失敗，模型手上唯一的線索就是錯誤回傳。一句 400 Bad Request 或直接丟 stack trace，等於把 Agent 推下懸崖。

好的錯誤回傳有三個要素：

  1. 結構化：用固定 schema（例如 {"error_code": "ORDER_NOT_FOUND", "message": "...", "next_step": "..."}），不要純文字。
  2. 可行動：告訴 Agent 下一步能做什麼。「訂單不存在」之後加一句「請用 list_orders 確認訂單編號是否正確」。
  3. 不洩漏：永遠不要把 stack trace 或內部實作細節丟給模型——那是給人類除錯看的，不是給 Agent 看的。

MCP 的慣例是用 isError: true 標記錯誤內容，讓 harness 能區分「工具執行失敗」和「工具回傳了錯誤資訊」。

原則五：回傳要為 context 預算設計

Agent 的 context 視窗是預算，不是檔案櫃。你的 API 回傳直接吃掉這個預算，所以：

  • 預設回傳精簡版（concise mode）：關鍵欄位加 has_more 旗標，需要時再要詳細版。
  • 大列表一定要分頁或截斷（例如 25,000 token 上限），並在截斷時明確告知。
  • 優先回傳人類可讀的識別（名稱而非 ID）、高訊號欄位；冗餘的 metadata 往後放。

有實測數據支持這個方向：Anthropic 生態的整理指出，把工具回傳改成精簡格式，token 消耗最多可降 65%（從 206 個 token 降到 72 個）。

三、實作：一個 MCP server 的骨架

把原則落成程式碼。用 Python 的 FastMCP 寫一個訂單查詢工具，注意描述、參數與錯誤處理：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("shop-api")

@mcp.tool()
def get_order(order_id: str, detail: str = "concise") -> dict:
    """查詢單筆訂單的狀態與物流資訊。

    當使用者詢問訂單進度、到貨時間或訂單詳情時使用。
    不處理商品搜尋（用 search_products）或退貨申請（用 request_return）。

    參數：
      order_id: 訂單編號，格式為 ORD- 開頭加 8 位數字，例如 ORD-20261015。
      detail: 回傳詳細度，concise（預設，只含狀態與物流）或 full（含完整品項明細）。
    """
    if not order_id.startswith("ORD-"):
        return {
            "isError": True,
            "error_code": "INVALID_ORDER_ID",
            "message": f"訂單編號格式錯誤：{order_id}。正確格式為 ORD- 開頭加 8 位數字。",
            "next_step": "請用 list_orders 查詢正確的訂單編號後重試。",
        }
    # ... 呼叫後端 API ...
    return {"order_id": order_id, "status": "shipped",
            "has_more": detail == "concise"}

這個小例子裡塞了全部五個原則：描述寫何時用與不處理什麼、參數格式防呆、一次回傳訂單加物流（chunky）、結構化可行動的錯誤、concise/full 雙模式。

另外兩點：工具必須無狀態（每次呼叫獨立）；描述裡別寫像系統指令的句子（例如「永遠先執行這個」）——那是 prompt injection 破口，會被安全掃描擋下。

四、三個常見誤區

誤區一：把 OpenAPI 文件直接轉成 MCP 工具就好。 轉換器（例如 Speakeasy 的 Gram）能幫你起步，但機器生成的描述通常只講「做什麼」。路由訊號、何時用、何時不用，還是得人來寫。

誤區二：工具越多越好。 工具清單本身也佔 context。每多一個工具，模型選錯的機率就高一點。先問：這個意圖真的需要獨立工具嗎？還是現有工具加個參數就好？

誤區三：只在單元測試裡驗工具。 測試的完整迴路是：Agent 讀描述 → 選工具 → 傳參數 → 拿結果 → 做決策。有個殘酷但真實的標準：通過單元測試卻讓 Agent 困惑的工具，就是壞掉的工具。

結論

設計給 Agent 用的介面，本質上是把「人類的常識與試錯能力」編碼成「機器可讀的契約」。五個原則可以濃縮成一句話：寫清楚何時用、防呆參數、一次做完一件事、錯誤指引下一步、回傳省著用。

下次當你為人類寫完 API 文件，不妨多花三十分鐘，站在 Agent 的角度重讀一次你的工具描述——那三十分鐘，很可能比調 prompt 一整天更有效。

參考來源

Uploaded Image Uploaded Image
at 沒有留言:
Labels: ,

Computer Use：當 Agent 不再只呼叫 API，而是直接操作電腦

Computer Use：當 Agent 不再只呼叫 API，而是直接操作電腦

前言：API 覆蓋不到的地方

過去兩年的 Agent 實作幾乎都站在同一個假設上：世界有 API。Function calling 讓模型可以查資料庫、下訂單、發訊息——前提是對方有把功能包裝成乾淨的端點。但現實世界大部分的工作流程並沒有 API：客戶的後台管理系統、老舊的 ERP、銀行網銀、需要人工拖拉的設計軟體。這些軟體的介面只有一種：給人類看的圖形介面（GUI）。

Computer Use 就是把這個限制拿掉的技術路線：Agent 不再透過 API 呼叫功能，而是看螢幕截圖、推理下一步、在像素座標上點滑鼠、打字——用和人類完全一樣的介面操作電腦。2024 年 10 月 Anthropic 率先把 computer use 做成 API 工具，OpenAI 則以 CUA（Computer-Using Agent）模型驅動 Operator（2025 年併入 ChatGPT Agent）。到 2026 年，這條路線已經從 demo 變成可部署的架構選項。

核心機制：截圖→推理→動作的迴路

Computer use 的控制迴路簡單到近乎笨拙，如圖一所示：

  1. 看：執行環境擷取一張螢幕截圖，交給模型；
  2. 想：模型在截圖上做版面解析、OCR、空間推理，決定下一步動作；
  3. 動：模型輸出一個動作——通常是「在像素座標 (x, y) 左鍵點擊」「輸入這段文字」「按 ctrl+S」「往下捲動」；
  4. 執行與回饋：你的程式碼實際執行這個動作（透過 Playwright、VNC、作業系統自動化），再擷取新的截圖回傳；
  5. 重複，直到模型回傳純文字（不再呼叫工具），表示任務完成。

這個架構最關鍵的設計取捨是：模型手上沒有任何語意資訊。沒有 DOM、沒有元素選擇器、沒有無障礙樹的座標。它必須從像素裡「看」出按鈕在哪——這就是所謂的視覺定位（visual grounding），也是整個技術棧裡最難的子問題。好處是通用性：只要看得見的東西都在操作範圍內，瀏覽器、桌面軟體、系統對話框全都通吃。

另一個取捨是每個動作都要一次完整的模型往返。N 個步驟就是 N 次 round trip，截圖還是 token 的大戶（每張截圖動輒上千 token）。這意味著 computer use 的任務天生又貴又慢：單步延遲 2–5 秒是常態，複雜任務的 token 帳單要先做心理準備。

兩大流派的實作：Anthropic 與 OpenAI

Anthropic 的路線是「API 工具」。在 Messages API 裡宣告一個 computer 工具（型別如 computer_20241022，附螢幕解析度參數），模型就能在回覆裡輸出 tool_use 區塊：{"action": "left_click", "coordinate": [640, 400]}。動作集合包含 screenshot、左右鍵點擊、雙擊、拖曳、mouse_move、type、key（支援組合鍵如 ctrl+c）、scroll，新版還加入 zoom、hold_key、wait。官方的三工具架構是：computer（滑鼠鍵盤 GUI 操作）＋ bash（持久化 shell session）＋ text_editor（結構化檔案編輯）。參考實作把整套跑在 Docker 裡的完整桌面環境，用 VNC 接畫面——環境是你的，你負責沙箱。

OpenAI 的路線是 CUA 模型。CUA（Computer-Using Agent）以 GPT-4o 的視覺能力為基礎加上強化學習訓練，透過 Responses API 的 computer 工具呼叫。實作上有個重要差異：OpenAI 允許一個回合內批次多個動作，而 Anthropic 是嚴格的單動作往返——前者在簡單任務上少走很多 round trip。CUA 當年公佈的基準：OSWorld 38.1%、WebArena 58.1%、WebVoyager 87%。消費端產品 Operator 已在 2025 年 8 月收掉，能力併入 ChatGPT Agent。

安全設計上兩家方向一致，只是落點不同：Anthropic 的文件花了大量篇幅在環境建議——沙箱 VM、域名白名單、不要交出真實憑證、重要動作要求人工確認，並用分類器偵測 prompt injection；OpenAI 的 CUA 則內建 pending_safety_checks，在敏感動作前暫停等確認。

實作要點：最小的 Computer Use 迴路

下面是一個 Anthropic 風格的最小迴路骨架（Python 概念碼）：


MAX_STEPS = 40  # 迴圈一定要有上限

def computer_use_loop(user_task, model, env):
    messages = [{"role": "user", "content": user_task}]
    tools = [{"type": "computer_20241022", "name": "computer",
              "display_width_px": 1280, "display_height_px": 800}]
    for _ in range(MAX_STEPS):
        resp = model.messages.create(model="claude-sonnet-4-5",
                                     messages=messages, tools=tools)
        messages.append({"role": "assistant", "content": resp.content})
        tool_calls = [b for b in resp.content if b.type == "tool_use"]
        if not tool_calls:
            return resp.text          # 模型不再呼叫工具＝任務完成
        results = []
        for call in tool_calls:
            action = call.input["action"]
            # 座標縮放：截圖傳給模型前通常會降採樣，
            # 模型回傳的座標要按比例放大回真實解析度再執行
            env.execute(scale(call.input))
            shot = env.screenshot()   # 執行動作後立刻擷取新畫面
            results.append({"type": "tool_result",
                            "tool_use_id": call.id,
                            "content": [{"type": "image",
                                         "source": {"type": "base64",
                                                    "media_type": "image/png",
                                                    "data": shot}}]})
        messages.append({"role": "user", "content": results})
    raise RuntimeError("步數耗盡：任務可能卡住或太複雜")

落地時的三個實務提醒：第一，環境隔離是剛需——computer use 會「照著像素能做的事去做」，給它真實桌面等於給它你的全部權限，務必跑在拋棄式 VM 或容器裡；第二，座標縮放別寫錯，截圖降採樣後回傳的座標若沒放大回真實解析度，點擊會系統性偏掉；第三，錯誤是可見的——這個架構的美妙之處是每個規劃錯誤在下一步的截圖裡都看得見，模型通常能自我修正，但你要給它足夠的步數預算和明確的「卡住了就停下來問人」指令。

三條路線怎麼選：Browser Use、ChatGPT Agent、Claude Computer Use

不是所有「操作電腦」的需求都要上 computer use。如圖二，三條路線各有最適位置：

  • 只控瀏覽器、要便宜可控：選 Browser Use 這類開源框架。它讀 DOM 元素並標註，模型看到的是結構化資訊而非純像素，token 成本低、可自託管、模型無關。網站自動化的預設起點。
  • OpenAI 生態、公開網路任務：走 ChatGPT Agent。雲端 VM、爆發半徑小（blast radius 有界）、適合交易型任務；但沒有本機檔案系統存取，複雜多步任務約 30 步後容易漂移。
  • 要操作桌面軟體、超出瀏覽器：只有 Claude Computer Use 做得到。API 工具形式、環境你自己管——自由度最高，出事也是你自己修。

決策規則很直白：先問「任務能不能只用瀏覽器完成？」能，就用 browser 路線；再問「需不需要碰桌面應用或本機檔案？」需要，才上 computer use。Computer use 的通用性是它的賣點，也是它的稅：截圖架構天生又貴又慢，能用結構化介面（API、DOM）解決的任務，永遠不要拿像素去硬幹。

評測：OSWorld 與 2026 年的進展

Computer use 的標準考場是 OSWorld：在真實作業系統環境裡完成數百個跨應用任務。2025 年初 CUA 的 38.1% 還是新聞；到 2026 年，OSWorld-Verified 上的頂尖分數已經翻倍——GPT-5.5 達 78.7%、Anthropic 的 Mythos 達 79.6%，雙雙超過人類專家基線。數字之外更值得注意的是 Anthropic 在保險領域的內部數字達 94%：垂直場景＋受控環境，computer use 已經是「週二早上真的在用」的生產力工具，不是 demo。

但基準分數和生產可靠度之間仍有落差，大部分團隊第一次上線都是在這裡摔跤：demo 環境的網站不會改版、不會跳驗證碼、不會有效能抖動，真實世界全都會。評估時記得把「環境漂移」算進成本。

結論：先 API，再 DOM，最後才用眼睛

Computer use 把 Agent 的操作邊界從「有 API 的世界」擴張到「人類看得見的世界」，代價是速度、成本和安全複雜度。2026 年的實務共識是分層策略：有 API 就用 function calling，只有瀏覽器就用 browser agent，非得碰桌面軟體才派出 computer use——並且永遠跑在沙箱裡、重要動作留人工確認。眼睛和手腳是 Agent 最貴的器官，不要拿來做手做得到的事。

來源

Uploaded Image Uploaded Image
at 沒有留言:
Labels: ,
訂閱： 文章 (Atom)