agent-browser

安裝 belt CLI 技能： npx skills add belt-sh/cli

Agentic Browser

透過 inference.sh 為 AI 代理提供瀏覽器自動化功能。底層使用 Playwright，並以簡單的 @e 參考系統進行元素互動。

快速開始

需要 inference.sh CLI（belt）。安裝說明

belt login

# 開啟頁面並取得可互動元素
belt app run agent-browser --function open --input '{"url": "https://example.com"}' --session new

核心工作流程

每個瀏覽器自動化都遵循以下模式：

1. 開啟 - 導航到 URL，取得元素的 @e 參考
2. 互動 - 使用參考進行點擊、填寫、拖曳等操作
3. 重新快照 - 導航或變更後，取得新的參考
4. 關閉 - 結束工作階段（若啟用錄影則回傳影片）

# 1. 開始工作階段
RESULT=$(belt app run agent-browser --function open --session new --input '{
  "url": "https://example.com/login"
}')
SESSION_ID=$(echo $RESULT | jq -r '.session_id')
# 元素：@e1 [input] "Email", @e2 [input] "Password", @e3 [button] "Sign In"

# 2. 填寫並送出
belt app run agent-browser --function interact --session $SESSION_ID --input '{
  "action": "fill", "ref": "@e1", "text": "user@example.com"
}'
belt app run agent-browser --function interact --session $SESSION_ID --input '{
  "action": "fill", "ref": "@e2", "text": "password123"
}'
belt app run agent-browser --function interact --session $SESSION_ID --input '{
  "action": "click", "ref": "@e3"
}'

# 3. 導航後重新快照
belt app run agent-browser --function snapshot --session $SESSION_ID --input '{}'

# 4. 完成後關閉
belt app run agent-browser --function close --session $SESSION_ID --input '{}'

函式

函式	說明
open	導航到 URL，設定瀏覽器（視口、代理、錄影）
snapshot	DOM 變更後重新取得頁面狀態及 @e 參考
interact	使用 @e 參考執行操作（點擊、填寫、拖曳、上傳等）
screenshot	擷取頁面截圖（視口或全頁）
execute	在頁面上執行 JavaScript 程式碼
close	關閉工作階段，若啟用錄影則回傳影片

互動動作

動作	說明	必要欄位
click	點擊元素	ref
dblclick	雙擊元素	ref
fill	清除並輸入文字	ref, text
type	輸入文字（不清除）	text
press	按下按鍵（Enter、Tab 等）	text
select	選擇下拉選項	ref, text
hover	滑鼠懸停在元素上	ref
check	勾選核取方塊	ref
uncheck	取消勾選核取方塊	ref
drag	拖放	ref, target_ref
upload	上傳檔案	ref, file_paths
scroll	捲動頁面	direction（up/down/left/right）, scroll_amount
back	返回上一頁	-
wait	等待毫秒數	wait_ms
goto	導航到 URL	url

元素參考

元素會以 @e 參考回傳：

@e1 [a] "Home" href="/"
@e2 [input type="text"] placeholder="Search"
@e3 [button] "Submit"
@e4 [select] "Choose option"
@e5 [input type="checkbox"] name="agree"

重要： 導航後參考會失效。請務必在以下情況後重新快照：

• 點擊會導航的連結或按鈕
• 表單送出
• 動態內容載入

功能

錄影

錄製瀏覽器工作階段以供除錯或文件使用：

# 啟用錄影開始（可選顯示游標指示器）
SESSION=$(belt app run agent-browser --function open --session new --input '{
  "url": "https://example.com",
  "record_video": true,
  "show_cursor": true
}' | jq -r '.session_id')

# ... 執行操作 ...

# 關閉以取得影片檔案
belt app run agent-browser --function close --session $SESSION --input '{}'
# 回傳：{"success": true, "video": <File>}

游標指示器

在截圖和影片中顯示可見游標（適用於示範）：

belt app run agent-browser --function open --session new --input '{
  "url": "https://example.com",
  "show_cursor": true,
  "record_video": true
}'

游標顯示為紅點，會跟隨滑鼠移動並顯示點擊回饋。

代理支援

透過代理伺服器路由流量：

belt app run agent-browser --function open --session new --input '{
  "url": "https://example.com",
  "proxy_url": "http://proxy.example.com:8080",
  "proxy_username": "user",
  "proxy_password": "pass"
}'

檔案上傳

上傳檔案到檔案輸入：

belt app run agent-browser --function interact --session $SESSION --input '{
  "action": "upload",
  "ref": "@e5",
  "file_paths": ["/path/to/file.pdf"]
}'

拖放

將元素拖曳到目標：

belt app run agent-browser --function interact --session $SESSION --input '{
  "action": "drag",
  "ref": "@e1",
  "target_ref": "@e2"
}'

JavaScript 執行

執行自訂 JavaScript：

belt app run agent-browser --function execute --session $SESSION --input '{
  "code": "document.querySelectorAll(\"h2\").length"
}'
# 回傳：{"result": "5", "screenshot": <File>}

深入文件

參考	說明
references/commands.md	完整函式參考及所有選項
references/snapshot-refs.md	參考生命週期、失效規則、疑難排解
references/session-management.md	工作階段持久化、平行工作階段
references/authentication.md	登入流程、OAuth、2FA 處理
references/video-recording.md	用於除錯的錄影工作流程
references/proxy-support.md	代理設定、地理測試

即用範本

範本	說明
templates/form-automation.sh	含驗證的表單填寫
templates/authenticated-session.sh	登入一次，重複使用工作階段
templates/capture-workflow.sh	含截圖的內容擷取

範例

表單送出

SESSION=$(belt app run agent-browser --function open --session new --input '{
  "url": "https://example.com/contact"
}' | jq -r '.session_id')

# 取得元素：@e1 [input] "Name", @e2 [input] "Email", @e3 [textarea], @e4 [button] "Send"

belt app run agent-browser --function interact --session $SESSION --input '{"action": "fill", "ref": "@e1", "text": "John Doe"}'
belt app run agent-browser --function interact --session $SESSION --input '{"action": "fill", "ref": "@e2", "text": "john@example.com"}'
belt app run agent-browser --function interact --session $SESSION --input '{"action": "fill", "ref": "@e3", "text": "Hello!"}'
belt app run agent-browser --function interact --session $SESSION --input '{"action": "click", "ref": "@e4"}'

belt app run agent-browser --function snapshot --session $SESSION --input '{}'
belt app run agent-browser --function close --session $SESSION --input '{}'

搜尋與擷取

SESSION=$(belt app run agent-browser --function open --session new --input '{
  "url": "https://google.com"
}' | jq -r '.session_id')

belt app run agent-browser --function interact --session $SESSION --input '{"action": "fill", "ref": "@e1", "text": "weather today"}'
belt app run agent-browser --function interact --session $SESSION --input '{"action": "press", "text": "Enter"}'
belt app run agent-browser --function interact --session $SESSION --input '{"action": "wait", "wait_ms": 2000}'

belt app run agent-browser --function snapshot --session $SESSION --input '{}'
belt app run agent-browser --function close --session $SESSION --input '{}'

含影片的截圖

SESSION=$(belt app run agent-browser --function open --session new --input '{
  "url": "https://example.com",
  "record_video": true
}' | jq -r '.session_id')

# 擷取全頁截圖
belt app run agent-browser --function screenshot --session $SESSION --input '{
  "full_page": true
}'

# 關閉並取得影片
RESULT=$(belt app run agent-browser --function close --session $SESSION --input '{}')
echo $RESULT | jq '.video'

工作階段

瀏覽器狀態在工作階段內持續存在。請務必：

1. 首次呼叫時使用 --session new
2. 後續呼叫使用回傳的 session_id
3. 完成後關閉工作階段

相關技能

# 網頁搜尋（用於研究與瀏覽）
npx skills add inference-sh/skills@web-search

# LLM 模型（分析擷取的內容）
npx skills add inference-sh/skills@llm-models

文件

• inference.sh 工作階段 - 工作階段管理
• 多函式應用程式 - 函式運作方式