Claude Agent SDK 負責 Agent 循環，可以通過 MCP 調用工具。瀏覽器由工具處理函式啓動，成功條件也由項目定義。本例要求狀態代碼實際出現在本地測試頁上，點擊完成只是其中一步。
選擇瀏覽器接入方式
如果流程固定、輸入已知且結果可以驗收，適合做成範圍明確的工具。探索陌生頁面時，通用 Playwright MCP 提供的交互方式更靈活。Anthropic 的 API SDK 還有一套使用獨立驅動接口的瀏覽器工具集。複製示例前，先確認自己接的是哪套 SDK 和接口。
API SDK 瀏覽器工具集文件 · Playwright 接入文檔
瀏覽器 Agent · 瀏覽器自動化 · 瀏覽器自動化 Agent
分開檢查注冊、執行和任務結果
MCP 用戶端能列出三個短名稱，說明工具注冊成功。下一層是處理函式是否打開了正確的頁面。回傳結果同時記錄 URL 和可見狀態，便於確認結果來自哪張頁面。最後一層是任務驗收，即使工具調用成功，也要單獨看到預期狀態才算完成。遇到故障時按這個順序定位。
實現三個工具
用 tool() 聲明參數校驗和處理函數，再通過 createSdkMcpServer() 注冊。可選 Agent 入口把服務放在 query().options.mcpServers.fixture 下，因此模型看到的工具名是 mcp__fixture__reveal_status。允許名單寫完整名稱，處理函數仍應約束每次調用能夠訪問的範圍。 SDK 自定義工具文件
示例只允許打開普通或缺少控制項的測試頁。Playwright 創建沒有登入狀態的新上下文，參數用列舉，導航限定在測試頁自己的來源。按按鈕的無障礙名稱精確查找，只有恰好一個匹配才點擊。點擊後讀取狀態區，並把可見文字與預期狀態代碼核對。
| 工具 | 實際回傳結果 |
|---|---|
open_fixture({variant}) | Status code hidden |
read_status() | 只讀頁面狀態 |
reveal_status() | Status code: SDK-17 |
按執行順序讀源碼
先看 fixture.mjs 的兩種測試路徑，再到 browser-tools.mjs 找精確角色定位、狀態回讀和調用預算，最後讀 smoke.mjs。基本驗證用戶端通過內存 MCP 枚舉工具和調用工具。可選 Agent 循環使用相同的處理函式。先跑基本驗證，便於把工具故障與模型授權或提示問題分開。
在本地運行示例
基本驗證經內存傳輸連接真實的 SDK MCP 服務，由確定性用戶端調用工具，並啓動本地 Chromium。它不需要模型憑證。可選 Agent 入口需要你自己的授權 API 密鑰。本次運行了基本驗證，模型入口沒有執行。
npm ci
npx playwright install chromium
npm test對照普通路徑和故障路徑
第一次調用打開普通頁，第二次顯示狀態代碼，第三次獨立讀取狀態。隨後打開缺失按鈕的故障頁，預期操作失敗，再讀一次確認狀態代碼仍然隱藏。後續用只讀調用觸發額度上限，第九次確認預算由宿主執行。基本驗證通過說明這些斷言在合成頁上成立。
查看工具回傳結果
故障頁故意移除了按鈕。操作工具返回錯誤、零個匹配，以及仍然隱藏的狀態。獨立頁面讀取確認代碼沒有出現。八次調用用完後，第九次返回預算錯誤。截圖記錄頁面當時的狀態，JSON 記錄工具如何報告這次嘗試。
{
"isError": true,
"ok": false,
"code": "TARGET_MISSING_OR_AMBIGUOUS",
"expected": "Reveal status code",
"matches": 0,
"observed": "Status code hidden"
}
在執行動作的地方約束工具
本項目只有一個本地來源、兩種輸入和一個按鈕。替換測試頁時保留同等的邊界。頁面內容是待處理數據，裡面的指令無權擴大工具權限。不要把網頁給出的選擇器、腳本或目標地址直接傳進處理器。增加寫操作之前，先約定允許修改的欄位、可執行的環境，以及結果無法確認時如何處理。
確定何時停止
控制項缺失或有歧義時，保存頁面狀態，檢查選擇器後再改。點擊已經執行但狀態未更新時，先重新讀取頁面。調用用完時停止，保留最後一個已確認結果。涉及寫入的流程應先準備回讀檢查，再決定是否重試寫操作。
| 失敗 | 下一步 |
|---|---|
TARGET_MISSING_OR_AMBIGUOUS | 檢查選擇器 |
POSTCONDITION_FAILED | 重新讀取頁面 |
TOOL_BUDGET_EXHAUSTED | 停止並保留最後一次結果 |
一位 Claude Code 用戶發現，助手稱表單測試已通過，瀏覽器卻沒有可見操作。另一條瀏覽器工具討論中，有人建議同時驗證錯誤提示出現和後續動作確實停下。兩條反饋幫助確定了本例的獨立回讀與停止檢查。 r/ClaudeCode · r/AI_Agents
遇到問題先核對頁面
狀態讀取失敗可能因為適配器沒打開目標頁、頁面缺少匹配控制項，或點擊已經觸發但應用拒絕更新。保存失敗代碼和實際狀態。超時或沒有匹配時應先查看真實頁面，避免把定位條件放寬到可能誤點。確定性用戶端能復現的問題，優先修工具或測試頁，再調整模型提示。
在模型之外驗證結果
可選 Agent 入口關閉內置工具，只允許三個工具名，並限制輪數和運行時長。即使模型報告成功，宿主也會獨立檢查頁面。遷移時先寫一條你能單獨運行的回讀檢查，例如重新載入後核對保存的欄位。
npm run agent先遷移一條小流程
把合成頁換成測試來源，把狀態代碼換成一個明確的業務條件，並保留同樣窄的輸入範圍。延續調用預算，記錄能區分成功和失敗的最少資訊，例如動作名、穩定錯誤碼與簡短的驗證結果。共享記錄排除憑據、帶用戶資訊的頁面文字和原始表單值。小流程可以重復驗證後，再增加其他動作。
常見問題
瀏覽器由哪個組件啓動？
工具宿主里的本地 Playwright 適配器負責啓動瀏覽器。
基本驗證需要 API 密鑰嗎？
不需要。用戶端直接調用 SDK 注冊的 MCP 工具。
可以給示例傳任意網址嗎？
示例只接受兩種測試頁模式，導航限定在本地測試來源。
點擊後為甚麼還要驗收？
瀏覽器可以執行點擊，但應用仍可能沒有產生預期狀態。
和通用 Playwright MCP 有甚麼區別？
通用服務提供可復用的瀏覽器操作，本例提供三個有明確結果的流程工具。
可以直接接真實表單嗎？
先用測試頁重現，接真實表單前明確寫入策略並實現獨立驗證。