agent-browser

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

Agentic Browser

通过 inference.sh 为 AI Agent 提供浏览器自动化功能。底层使用 Playwright，并通过简单的 @e 引用系统与元素交互。

快速开始

需要 inference.sh CLI（belt）。安装说明

belt login

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

核心工作流

每次浏览器自动化都遵循以下模式：

1. 打开 - 导航到 URL，获取元素的 @e 引用
2. 交互 - 使用引用执行点击、填充、拖拽等操作
3. 重新快照 - 导航或页面变更后，获取最新引用
4. 关闭 - 结束会话（录制时会返回视频）

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

# 2. Fill and submit
belt app run agent-browser --function interact --session $SESSION_ID --input '{
  "action": "fill", "ref": "@e1", "text": "[email protected]"
}'
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. Re-snapshot after navigation
belt app run agent-browser --function snapshot --session $SESSION_ID --input '{}'

# 4. Close when done
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"

**重要：**导航后引用会失效。以下操作后务必重新获取快照：

• 点击会触发导航的链接或按钮
• 提交表单
• 动态内容加载

功能

视频录制

录制浏览器会话，以便调试或编写文档：

# Start with recording enabled (optionally show cursor indicator)
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')

# ... perform actions ...

# Close to get the video file
belt app run agent-browser --function close --session $SESSION --input '{}'
# Returns: {"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"
}'
# Returns: {"result": "5", "screenshot": <File>}

深入文档

参考文档	说明
references/commands.md	完整函数参考及所有选项
references/snapshot-refs.md	引用生命周期、失效规则和故障排查
references/session-management.md	会话持久化、并行会话
references/authentication.md	登录流程、OAuth、双重身份验证处理
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')

# Get elements: @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": "[email protected]"}'
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')

# Take full page screenshot
belt app run agent-browser --function screenshot --session $SESSION --input '{
  "full_page": true
}'

# Close and get video
RESULT=$(belt app run agent-browser --function close --session $SESSION --input '{}')
echo $RESULT | jq '.video'

会话

浏览器状态会在会话中保留。请务必：

1. 首次调用时使用 --session new
2. 后续调用使用返回的 session_id
3. 完成后关闭会话

相关技能

# Web search (for research + browse)
npx skills add inference-sh/skills@web-search

# LLM models (analyze extracted content)
npx skills add inference-sh/skills@llm-models

文档

• inference.sh 会话 - 会话管理
• 多功能应用 - 函数的工作方式