agent-browser

Agentic Browser

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

快速开始

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

infsh login

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

核心工作流

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

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

# 1. Start session
RESULT=$(infsh 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
infsh app run agent-browser --function interact --session $SESSION_ID --input '{
  "action": "fill", "ref": "@e1", "text": "[email protected]"
}'
infsh app run agent-browser --function interact --session $SESSION_ID --input '{
  "action": "fill", "ref": "@e2", "text": "password123"
}'
infsh app run agent-browser --function interact --session $SESSION_ID --input '{
  "action": "click", "ref": "@e3"
}'

# 3. Re-snapshot after navigation
infsh app run agent-browser --function snapshot --session $SESSION_ID --input '{}'

# 4. Close when done
infsh 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=$(infsh 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
infsh app run agent-browser --function close --session $SESSION --input '{}'
# Returns: {"success": true, "video": <File>}

光标指示器

在截图和视频中显示可见光标（适用于演示）：

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

光标显示为一个红点，会跟随鼠标移动并显示点击反馈。

代理支持

通过代理服务器转发流量：

infsh 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"
}'

文件上传

将文件上传到文件输入框：

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

拖放

将元素拖至目标位置：

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

JavaScript 执行

运行自定义 JavaScript：

infsh 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、2FA 处理
references/video-recording.md	用于调试的录制工作流
references/proxy-support.md	代理配置、地理位置测试

即用模板

模板	说明
templates/form-automation.sh	带验证的表单填写
templates/authenticated-session.sh	登录一次，重复使用会话
templates/capture-workflow.sh	使用截图提取内容

示例

提交表单

SESSION=$(infsh 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"

infsh app run agent-browser --function interact --session $SESSION --input '{"action": "fill", "ref": "@e1", "text": "John Doe"}'
infsh app run agent-browser --function interact --session $SESSION --input '{"action": "fill", "ref": "@e2", "text": "[email protected]"}'
infsh app run agent-browser --function interact --session $SESSION --input '{"action": "fill", "ref": "@e3", "text": "Hello!"}'
infsh app run agent-browser --function interact --session $SESSION --input '{"action": "click", "ref": "@e4"}'

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

搜索和提取

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

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

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

截图和视频

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

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

# Close and get video
RESULT=$(infsh 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 会话 - 会话管理
• 多功能应用 - 函数的工作方式