agent-browser

概觀

什麼是 agent-browser？

agent-browser 是一個專為在 inference.sh 平台上執行的 AI agents 設計的瀏覽器自動化技能。它在底層使用 Playwright，並提供簡單、以 JSON 為基礎的介面，讓 agents 能夠：

• 在真正的瀏覽器中開啟與瀏覽網頁
• 使用穩定的 @e 元素參照與畫面互動
• 點擊、輸入、拖放以及上傳檔案
• 擷取結構化資料，用於爬取與研究
• 截取螢幕畫面並錄製瀏覽工作階段的影片

你不需要手寫 Playwright 程式碼，而是透過 infsh CLI（或能執行 Bash 指令的 agent）呼叫 agent-browser。這個技能會協調整個瀏覽器工作階段，回傳對頁面的機器可讀描述，並讓你的 agent 能一步步地驅動互動流程。

agent-browser 適合誰使用？

agent-browser 主要提供給：

• 將 AI agents 連接到真實網站的 開發者
• 需要可重複執行瀏覽流程的 自動化工程師
• 進行目標式網頁爬取或以 UI 為主研究的 資料與研究團隊
• 使用 inference.sh 作為協調層的 流程設計者 / workflow builders

當你已經使用或願意採用 inference.sh，並希望瀏覽器成為可被 agent 控制的工具時，就特別適合使用這個技能。

它幫助解決哪些問題？

agent-browser 能協助你處理常見的瀏覽器自動化工作：

• 自動化登入、導覽與表單流程
• 爬取需要互動才能取得的結構化內容（如搜尋表單、篩選器、分頁）
• 在真實網站上執行類似測試流程的 agent 驅動操作
• 錄製自動瀏覽工作階段的影片供檢閱

它將直接撰寫 Playwright 腳本的細節抽象化，改以使用 @e 元素參照來提供更高階的操作介面，有助於在多步驟流程中維持互動的穩定性。

什麼情況下適合使用 agent-browser？

當符合以下條件時，可考慮使用 agent-browser：

• 你透過 inference.sh 執行 agents，且需要讓它們能瀏覽網路
• 想要有 Playwright 等級的穩定性，但不想自己寫 Playwright 程式碼
• 你的流程主要由開啟頁面、與元素互動、讀取結果所組成

以下情況則可能 不太適合：

• 你無法使用 infsh CLI 或類 Bash 的工具
• 你需要技能本身沒有開放的、高度客製化 Playwright 功能
• 你的場景完全是 API 為主，不需要真實瀏覽器

如果你需要對瀏覽器內部或前端框架進行非常細緻的控制，且超出技能提供的能力範圍，直接撰寫 Playwright 腳本可能會更合適。對一般由 agent 驅動的自動化情境而言，agent-browser 則提供更簡單、抽象層更高的介面。

使用方式

先決條件

在使用 agent-browser 之前，請先確認你已具備：

• 一個可以執行 Bash 指令的環境
• 已安裝 inference.sh CLI (infsh)
• 一個能從 CLI 登入的 inference.sh 帳號

此技能的快速開始流程明確需要 infsh CLI。你可以依照官方 repo 中的 CLI 安裝說明進行：

• CLI 安裝文件：https://raw.githubusercontent.com/inference-sh/skills/refs/heads/main/cli-install.md

完成 infsh 安裝與設定後，你可以在終端機中，或任何能執行 infsh 指令的 agent 工具裡呼叫 agent-browser 技能。

安裝與啟用技能

agent-browser 是 inferen-sh/skills repository 的一部分。在大多數以 inference.sh 為基礎的環境中，你 不需要 另外安裝獨立的 npm 套件；只要確認該技能可用，接著透過 infsh 呼叫即可。

一般設定步驟如下：

1. 安裝 inference.sh CLI
   • 依照 repo 中的 cli-install.md 說明進行。
2. 驗證身分
   • 執行：

     infsh login
     

   • 依提示完成 inference.sh 的登入驗證。
3. 確認技能是否可用
   • 確保你的 inference.sh 環境可以存取 inferen-sh/skills repo 中 tools/utilities/agent-browser 目錄下的 agent-browser app/skill。

如果你整合的是支援 npx skills add 的「技能生態系」，也可以將這個 repository 掛載為來源。不過，agent-browser 的標準使用流程還是透過 infsh app run 來執行。

核心瀏覽器自動化流程

技能文件描述了一個一致的四步驟操作模式：

1. Open – 啟動瀏覽器工作階段並前往指定 URL。
2. Interact – 使用回傳的 @e 元素參照來點擊、輸入、拖曳或上傳。
3. Re-snapshot – 在導覽或 DOM 變化後，要求重新快照以取得新的 @e 參照。
4. Close – 結束工作階段；若有啟用錄影，可選擇性取得該段影片。

透過這個模式，你的 agent 能維持對頁面狀態的「心智模型」。每一次呼叫都會送出 JSON 輸入並收到結構化 JSON 輸出，再供 agent 的推理迴圈使用。

快速開始範例

若想快速看到 agent-browser 的實際運作（例如開啟單一頁面），可依照 repo 中的 Quick Start 模式：

infsh login

# Open a page and get interactive elements
infsh app run agent-browser --function open --input '{"url": "https://example.com"}' --session new

上述指令會：

• 透過 --function open 指示 agent-browser 在指定 URL 開啟新頁面。
• 使用 --session new 建立新的工作階段，讓後續動作能共用同一個瀏覽器狀態。
• 技能會回傳 JSON，通常包含元素描述與 @e 參照，可供你的 agent 在後續 interact 呼叫中使用。

使用 @e 元素參照

agent-browser 的核心特色之一，就是使用 @e 參照。相較於直接使用 CSS selector 或 XPath，技能會回傳類似 @e:button-1 的 handle（實際格式視實作而定），並附上人類可讀的描述。

你的 agent 一般會：

1. 讀取所有可用元素及其描述。
2. 選擇適當的 @e 參照（例如標示為「Search」的按鈕）。
3. 透過互動函式（如 click 或 fill）搭配該 @e 參照進行操作。

這樣的設計特別適合 AI agents，因為它們可以基於描述內容進行推理，而不必處理低階 DOM 細節。只要描述仍可理解，即便底層 selector 有變動，也較能維持互動的穩健性。

範例：open、click 與 resnapshot

典型的多步驟流程大致如下（僅為模式示意，請依實際函式調整）：

# 1. Start a session and open a page
OPEN_RESULT=$(infsh app run agent-browser \
  --function open \
  --session new \
  --input '{"url": "https://example.com"}')

# 2. Use OPEN_RESULT to pick an @e ref (e.g. @e:search-button) in your agent logic
# 3. Interact with that element
INTERACT_RESULT=$(infsh app run agent-browser \
  --function interact \
  --session "$INF_SH_SESSION" \
  --input '{"action": "click", "element": "@e:search-button"}')

# 4. Re-snapshot after the click to get updated elements
SNAPSHOT_RESULT=$(infsh app run agent-browser \
  --function snapshot \
  --session "$INF_SH_SESSION" \
  --input '{}')

open 之外的函式名稱可能會有所不同，因此請務必查閱最新的 SKILL.md 以及 tools/utilities/agent-browser 內的相關文件，以確認實際的函式名稱與輸入結構。

截圖與錄影

agent-browser 可以擷取瀏覽工作階段的視覺紀錄：

• Screenshots – 適合用來除錯 agent 行為，或保留視覺上的確認紀錄。
• Video – 當你在啟用錄影的狀況下關閉工作階段時，技能可以回傳或提供完整自動化流程的影片檔連結。

這些功能可以透過技能的輸入選項來設定。關於如何啟用錄影與存取輸出內容的詳細方式，請參考 repo 中的 SKILL.md 定義，以及 tools/utilities/agent-browser 底下的補充說明文件。

與 agents 和工作流程整合的小技巧

若想在自動化或研究型工作流程中最大化使用 agent-browser 的價值，可留意：

• 持久化 --session ID：確保你的 agent 在多次呼叫之間保存並重複使用工作階段 ID，讓所有操作都在同一個瀏覽器中進行。
• 謹慎解析 JSON 輸出：在 agent 執行環境中使用穩健的 JSON 解析；元素列表與中繼資料通常相當豐富。
• 必要時適度節流互動頻率：若頁面較慢或高度動態，請在技能支援的情況下，讓 agent 考慮載入時間並等待元素出現，再進行下一步。
• 記錄關鍵操作：若你需要稽核或除錯 agent 的瀏覽行為，可保留 open、interact 與 close 呼叫的紀錄。

常見問題（FAQ）

agent-browser、inference.sh 與 Playwright 之間的關係是什麼？

agent-browser 是在 inference.sh 生態系中運行的技能。當你透過 infsh app run 呼叫它時，它會以 Playwright 作為底層瀏覽器自動化引擎。你不需要直接呼叫 Playwright，而是操作更高階的技能函式與 @e 元素參照。

我要如何安裝 agent-browser？

你不需要把 agent-browser 安裝成獨立的執行檔或 npm 套件，而是遵循以下方式：

1. 依官方 cli-install.md 說明安裝 inference.sh CLI (infsh)。
2. 使用 infsh login 登入。
3. 確認你的環境可以存取 inferen-sh/skills repository 中的 agent-browser 技能（位於 tools/utilities/agent-browser）。

完成上述步驟後，就可以直接透過 infsh app run agent-browser 呼叫此技能。

使用 agent-browser 需要有程式背景嗎？

建議至少具備基本的指令列操作與 JSON 概念。你不必撰寫 Playwright 腳本，但最好能熟悉：

• 執行 infsh 指令
• 以 --input 傳遞 JSON
• 在你的 agent 或腳本中解析 JSON 輸出

若要實作更進階的流程（條件邏輯、迴圈、錯誤處理等），具備一般腳本或程式開發能力會更有幫助。

可以在 inference.sh 之外使用 agent-browser 嗎？

這個技能是專為 inference.sh 設計，並以「Browser automation for AI agents via inference.sh」為定位。目前官方支援與文件說明的使用方式，就是透過 infsh CLI 執行。如果你需要獨立的程式庫，直接在你偏好的語言中使用 Playwright 可能會比較適合。

agent-browser 適合大規模網頁爬取嗎？

agent-browser 可以用於目標明確的爬取情境，尤其是當頁面需要互動或大量 JavaScript 渲染時。不過，若你要進行非常大規模的爬取，仍需評估：

• inference.sh 帳號的限制與計價模式
• 目標網站的使用條款與 robots.txt 規範
• 效能、併發數與速率限制

對於較小規模、與特定工作流程緊密整合的爬取（例如嵌入在 agent 之中的工作），agent-browser 是相當不錯的選擇；但若是跨大量網站的巨量爬行，專門的爬蟲架構可能會更合適。

工作階段（session）管理是如何運作的？

工作階段管理是透過呼叫 infsh app run 時的 --session 參數來控制。常見模式如下：

• 第一次呼叫 open 時使用 --session new
• 在後續的 interact 與 snapshot 呼叫中重複使用同一個 session ID
• 透過適當的 close 函式來結束工作階段，並視需要取得錄影

請務必參考當前版本的 SKILL.md，了解與 session 管理相關的具體選項與輸出內容。

在哪裡可以看到完整的函式與輸入規格？

agent-browser 的權威參考文件位於 repository 中：

• inferen-sh/skills repo 根目錄下的 SKILL.md
• tools/utilities/agent-browser 目錄，用於查看實作細節、範例與額外說明

請開啟這些檔案，確認目前可用的函式列表、預期的 JSON 輸入與輸出格式，並據此設計你的 agents 或腳本。