---
site: "zyx.tw"
title: "我把畫面動作與 tool 放進同一份定義，讓 agent 也能操作產品"
description: "共用動作定義，再檢查畫面與 tool 是否漏了對應。"
url: "https://www.zyx.tw/map/principles/agent-experience"
---

# 我把畫面動作與 tool 放進同一份定義，讓 agent 也能操作產品

紀錄 011，經驗 L2，569 字，1 分鐘，v2.0.0，更新 2026-11-16

我在設計產品時，把 agent 當成使用者。tool 是讓 agent 執行產品動作的工具；畫面上的每個功能，都要有 agent 能呼叫的 tool。

以投影片編輯器作為設計例子：Claude Code 操作編輯器，使用者在畫面查看結果。使用者選取內容並留下評論，Claude Code 再依評論修改。

## 讓畫面與 tool 共用動作定義

我採用的做法，是每個讀寫動作只保留一份定義，再從定義產生 tool，透過提供工具的開放標準 MCP 供 agent 使用。

整理既有產品時，我先列出畫面上的動作，在每個動作旁寫下對應的 tool。這份對照用來找出缺口。

接著用測試比對畫面動作與 tool 清單，讓漏項被擋下。下圖示範修改合併前的 pull request 檢查：只改畫面、缺少 tool 時，測試失敗，不合併；同時提供對應 tool，才通過這項比對。

**新功能的 pull request 只改了畫面**

人:
- 在畫面上用得到新功能

agent:
- 沒有對應的 tool，無法操作

自動檢查:
- 測試失敗，不合併

測試比對畫面動作與 tool 清單。缺少對應的 tool，測試就失敗。

**新功能的 pull request 同時加了 tool**

人:
- 在畫面上用得到新功能

agent:
- 呼叫 tool，執行相同動作

自動檢查:
- 測試通過

人和 agent 都能執行相同動作。比對的測試通過後，才合併修改。

## 有工具之外，還要提供操作資訊

動作有入口，還需要能辨識的控制項。我會為按鈕和欄位標上角色與名稱。頁面文字快照會把頁面上的按鈕與欄位轉成文字，讓 agent 讀得到角色與名稱，辨識要操作的對象。

tool 失敗時，我要求回傳原因與處理方法。例如設定尚未完成，錯誤訊息就要指出該先呼叫哪個 tool，讓 agent 知道下一個動作。

## 測試可能漏項，直接修改要能還原

測試本身可能漏掉畫面動作，因此檢查 tool 清單時，還要確認投影片標題等功能。

若編輯器讓 agent 的修改直接生效，就要保留還原方法。我採用的做法是把每筆修改寫進 log，也就是程式執行時留下的紀錄，供需要時還原。

## 缺少 tool 的動作仍要靠瀏覽器

缺少對應 tool 的動作，agent 仍只能透過瀏覽器點擊，操作較慢，也容易出錯。

## 地圖

- 原理：[MCP 把服務操作包成 agent 能呼叫的工具](https://www.zyx.tw/map/basics/mcp-wraps-a-service.md)
- 相關：[我按固定順序選服務介面，做得到就不開網頁](https://www.zyx.tw/map/goals/acts-for-me.md)
- 相關：[替監控提供 agent 可查詢的入口](https://www.zyx.tw/map/beyond/monitoring-for-agents.md)
- 回到：[原則](https://www.zyx.tw/map.md)
