kernel-agent-browser

使用 Kernel 云浏览器的 Agent-Browser

本文档介绍使用 agent-browser 内置的 Kernel 提供程序（-p kernel）进行云端浏览器自动化的最佳实践。

何时使用此技能

在以下情况下使用此技能：

• 使用 agent-browser -p kernel 命令自动化网站
• 应对反机器人检测，以访问具有严格反机器人措施的网站
• 使用配置文件保留登录会话，以便在多次自动化运行之间复用
• 处理 iframe，包括跨源支付表单
• 获取实时视图 URL，用于调试或人工干预
• 查找底层 Kernel 会话 ID，以便编写高级 Playwright 脚本
• 为新网站创建特定于网站的自动化技能

参考资料

• 创建特定于网站的技能 - 为特定网站构建自动化技能的指南

前置条件

加载 kernel-cli 技能，以安装并验证 Kernel CLI。

环境变量

在首次调用 agent-browser -p kernel 之前设置这些变量。CLI 会在多次调用之间保留状态。

变量	描述	默认值
KERNEL_API_KEY	必需。 用于身份验证的 Kernel API 密钥	（无）
KERNEL_HEADLESS	以无头模式运行浏览器（true/false）	true
KERNEL_STEALTH	启动隐身浏览器（true/false）	false
KERNEL_TIMEOUT_SECONDS	会话超时时间，单位为秒	300
KERNEL_PROFILE_NAME	在 agent-browser 0.33.0 中，目前无法与 -p kernel 一起使用；请使用下方的 CDP 变通方法	（无）

推荐配置

显式设置选项；agent-browser 会在创建提供程序会话时读取这些选项。

export KERNEL_API_KEY="your-api-key"
export KERNEL_TIMEOUT_SECONDS=600     # 10-minute timeout for complex workflows
export KERNEL_HEADLESS=false          # Required when you need a live view
export KERNEL_STEALTH=true            # Opt in for bot-sensitive sites
# Do not set KERNEL_PROFILE_NAME with -p kernel; use the workaround below.

配置文件持久化

警告： KERNEL_PROFILE_NAME 在 agent-browser 0.33.0 中无法与 -p kernel 一起使用。它会将 profile 作为字符串发送，而 Kernel 要求该值为对象，因此会话创建会因 HTTP 400 错误而失败。它也不会设置 save_changes。必须预先创建配置文件。

在上游修复此问题之前，请使用 Kernel CLI 创建浏览器，然后通过 CDP 连接 agent-browser。不要将 -p kernel 与 --cdp 组合使用。

PROFILE_NAME=mysite  # Create once with: kernel profiles create --name mysite
kernel profiles get "$PROFILE_NAME" >/dev/null
BROWSER=$(kernel browsers create --profile-name "$PROFILE_NAME" --save-changes --timeout 600 -o json)
SESSION_ID=$(jq -er '.session_id' <<<"$BROWSER")
CDP_URL=$(jq -er '.cdp_ws_url' <<<"$BROWSER")
trap 'kernel browsers delete "$SESSION_ID" >/dev/null 2>&1 || true' EXIT

agent-browser --session mysite --cdp "$CDP_URL" open https://example.com
agent-browser --session mysite snapshot -i
# Run additional commands with --session mysite, then disconnect and end the Kernel session.
agent-browser --session mysite close
kernel browsers delete "$SESSION_ID"
trap - EXIT

不要打印或分享 CDP_URL；它会授予浏览器访问权限。删除通过 CLI 创建的会话会最终保存 --save-changes 的更改，因此后续会话可以复用已通过身份验证的配置文件。

基本用法

agent-browser -p kernel open <url>        # Navigate to page
agent-browser -p kernel snapshot -i       # Get interactive elements with refs
agent-browser -p kernel click @e1         # Click element by ref
agent-browser -p kernel fill @e2 "text"   # Fill input by ref
agent-browser -p kernel close             # Close the provider session

对于由提供程序管理的会话，请在每条命令中使用 -p kernel。对于配置文件/CDP 变通方法，请重复使用相同的 --session 名称，且不要添加 -p kernel。

语义选择器（推荐）

不要使用每次页面加载时都会变化的临时 @e 引用，而应通过 find 命令使用语义选择器，以实现更稳定、易读的自动化：

# By ARIA role + accessible name (most stable)
agent-browser -p kernel find role button click --name "Log In"
agent-browser -p kernel find role textbox fill "[email protected]" --name "Email"

# By visible text content
agent-browser -p kernel find text "View Menus" click
agent-browser -p kernel find text "Submit Order" click

# By form label (great for inputs)
agent-browser -p kernel find label "Username" fill "myuser"
agent-browser -p kernel find label "Password" fill "secret123"

# By placeholder text
agent-browser -p kernel find placeholder "Search..." type "query"

# By data-testid (if the site uses them)
agent-browser -p kernel find testid "submit-btn" click

# By position (when needed)
agent-browser -p kernel find first "li.item" click
agent-browser -p kernel find nth 2 ".card" hover

何时使用哪种选择器

选择器类型	最适用场景	稳定性
find role --name	按钮、链接、导航	⭐⭐⭐ 最稳定
find label	带标签的表单输入项	⭐⭐⭐ 最稳定
find text	可点击的文本元素	⭐⭐ 稳定
find testid	带有测试属性的网站	⭐⭐⭐ 最稳定
find placeholder	搜索框、输入框	⭐⭐ 稳定
@e refs	未知网站、快速迭代	⭐ 临时

建议：生产环境自动化请使用 find。探索和快速原型开发时可使用 @e refs，之后再转换为语义选择器。

查找 Kernel 会话和实时视图

将 agent-browser 的 CDP 端点与活动的 Kernel 会话匹配。比较不含查询字符串的 URL：对于同一会话，CLI 和 agent-browser 可能持有不同的短时 jwt 查询值。端点的协议、主机和路径保持稳定。当多个会话共用一个配置文件时，这种方法比根据创建时间猜测更可靠。此工作流需要 jq。

CDP_URL="$(agent-browser -p kernel get cdp-url)"
CDP_ENDPOINT="${CDP_URL%%\?*}"
SESSION_ID="$(
  kernel browsers list --status active --limit 100 -o json |
    jq -r --arg endpoint "$CDP_ENDPOINT" \
      '.[] | select((.cdp_ws_url | split("?")[0]) == $endpoint) | .session_id' |
    head -n 1
)"
test -n "$SESSION_ID"

kernel browsers view "$SESSION_ID"

请勿打印或分享 CDP URL；它授予浏览器访问权限。仅与指定用户分享实时视图 URL。无头会话没有实时视图。如果使用 --session <name>，则每条 agent-browser 命令都必须包含它，包括 get cdp-url。

处理机器人检测

隐身模式和代理路由

当前版本的 agent-browser 中，隐身模式默认不启用。请在会话的首条命令之前设置 KERNEL_STEALTH=true；之后更改该值不会重新配置正在运行的浏览器。

隐身浏览器可以使用 Kernel 的默认隐身代理。如果该代理导致特定网站出现网络或信誉问题，并且可以接受直接使用 metro 出口，请在不禁用隐身模式的情况下更改正在运行的会话：

kernel browsers update "$SESSION_ID" --disable-default-proxy
# Retry the navigation and compare behavior.

# Re-enable the default stealth proxy while continuing the same session.
kernel browsers update "$SESSION_ID" --disable-default-proxy=false

直接出口会改变公共 IP，并可能降低反机器人保护。除非测试表明确实是默认代理导致问题，否则请优先使用默认代理。对于已配置的 Kernel 代理，请使用 --proxy-id <proxy-id>；使用 --clear-proxy 将其移除。

手动登录备用方案

如果自动登录失败：

1. 使用上述 CDP 匹配工作流确定 SESSION_ID。
2. 运行 kernel browsers view "$SESSION_ID"，并仅向指定用户提供该 URL。
3. 请用户完成登录，然后在同一个 agent-browser 会话中继续操作。
4. 如需保存登录状态，请使用上述由 CLI 创建的配置文件/CDP 工作流。关闭 agent-browser，然后删除 Kernel 会话，以便 --save-changes 完成最终保存。

棘手元素的 JavaScript 备用方案

某些元素（尤其是受机器人保护的网站上的元素）不会响应标准命令：

# Click by CSS selector
agent-browser -p kernel eval "document.querySelector('.submit-btn').click()"

# Fill by selector (with event dispatch)
agent-browser -p kernel eval "
  const el = document.querySelector('#email');
  el.value = '[email protected]';
  el.dispatchEvent(new Event('input', {bubbles: true}));
  el.dispatchEvent(new Event('change', {bubbles: true}));
"

# Click by test ID
agent-browser -p kernel eval "document.querySelector('[data-testid=\"submit\"]').click()"

反机器人表单字段

某些支付处理商（例如 Point and Pay）会使用诱饵表单字段。请仅填写符合特定模式的字段：

agent-browser -p kernel eval "
  const realInputs = Array.from(document.querySelectorAll('input'))
    .filter(el => el.name && el.name.startsWith('xeiinput'));
  // Fill only these inputs
"

处理 iframe

同源 iframe

使用 frame 命令切换上下文：

agent-browser -p kernel frame "#iframe-id"   # Switch to iframe
agent-browser -p kernel snapshot -i          # Snapshot within iframe
agent-browser -p kernel click @e1            # Interact within iframe
agent-browser -p kernel frame main           # Return to main frame

跨源 iframe

请先尝试 agent-browser frame；当前版本可以切换到 iframe 上下文，包括许多跨源 frame。如果进程外 iframe 或支付 iframe 仍然失败，请确定 SESSION_ID 并使用 Kernel 的 Playwright 执行器：

kernel browsers playwright execute "$SESSION_ID" '
  const frame = page.frameLocator("#payment-iframe");
  await frame.locator("#card-number").fill("4111111111111111");
  await frame.locator("#submit").click();
'

完成 frame 交互后，使用 agent-browser -p kernel frame main 返回主文档。

等待策略

智能等待对于实现快速、可靠的自动化至关重要。 使用基于条件的等待代替固定超时，可将执行时间缩短 50% 以上，同时提高可靠性。

智能等待（推荐）

# Wait for page load states
agent-browser -p kernel wait --load domcontentloaded  # DOM ready
agent-browser -p kernel wait --load networkidle       # Network settled

# Wait for specific URL pattern (great for redirects after login)
agent-browser -p kernel wait --url "**/dashboard"
agent-browser -p kernel wait --url "**/order-confirmation"

# Wait for text to appear (great for dynamic content)
agent-browser -p kernel wait --text "Password"        # Field appeared
agent-browser -p kernel wait --text "Order confirmed" # Success message

# Wait for JavaScript condition
agent-browser -p kernel wait --fn "window.appReady === true"
agent-browser -p kernel wait --fn "document.querySelector('.spinner') === null"

# Wait for element by CSS selector
agent-browser -p kernel wait "#login-form"
agent-browser -p kernel wait ".results-loaded"

固定等待（最后手段）

# Only when no condition is available
agent-browser -p kernel wait 2000

元素引用最佳实践

元素引用（@e1、@e2 等）是临时的，并会发生变化：

• 页面导航后
• DOM 发生重大更新后
• 不同浏览器会话之间

交互前务必获取最新快照：

agent-browser -p kernel snapshot -i
# Now use the refs from this snapshot
agent-browser -p kernel click @e5

筛选快照

# Filter for specific elements
agent-browser -p kernel snapshot -i | grep -i "button\|submit"

# Scope to a specific area
agent-browser -p kernel snapshot -s "#main-content" -i

登录模式

单页表单（优化）

用户名和密码位于同一页面：

agent-browser -p kernel open https://example.com/login
agent-browser -p kernel wait --load domcontentloaded

# Use semantic selectors for stability
agent-browser -p kernel find label "Email" fill "[email protected]"
agent-browser -p kernel find label "Password" fill "secret123"
agent-browser -p kernel find role button click --name "Sign In"

# Wait for actual redirect, not arbitrary timeout
agent-browser -p kernel wait --url "**/dashboard"

两步表单（优化）

先输入用户名，再在第二个屏幕上输入密码：

agent-browser -p kernel open https://example.com/login
agent-browser -p kernel wait --load domcontentloaded

# Step 1: Username
agent-browser -p kernel find label "Username" fill "myuser"
agent-browser -p kernel press Enter

# Wait for password field to appear (not a fixed sleep!)
agent-browser -p kernel wait --text "Password"

# Step 2: Password
agent-browser -p kernel find label "Password" fill "secret123"
agent-browser -p kernel press Enter

# Wait for successful redirect
agent-browser -p kernel wait --url "**/home"

模态框登录

登录表单显示在模态覆盖层中：

# Click login link to open modal
agent-browser -p kernel find text "Log In" click
agent-browser -p kernel wait --text "Password"  # Wait for modal

# Fill modal fields
agent-browser -p kernel find label "Email" fill "[email protected]"
agent-browser -p kernel find label "Password" fill "password123"
agent-browser -p kernel find role button click --name "Sign In"
agent-browser -p kernel wait --url "**/dashboard"

备用方案：使用 JavaScript 处理棘手的模态框

某些模态框不会公开无障碍标签：

agent-browser -p kernel eval "document.querySelector('.login-link').click()"
agent-browser -p kernel wait 1000

agent-browser -p kernel eval "
  document.getElementById('username').value = '[email protected]';
  document.getElementById('username').dispatchEvent(new Event('input', {bubbles: true}));
  document.getElementById('password').value = 'password123';
  document.getElementById('password').dispatchEvent(new Event('input', {bubbles: true}));
  document.querySelector('button[type=submit]').click();
"
agent-browser -p kernel wait --url "**/dashboard"

处理新标签页

某些链接会在新标签页中打开：

# Click link that opens new tab
agent-browser -p kernel click @e38
agent-browser -p kernel tab 1           # Switch to new tab (0-indexed)
agent-browser -p kernel wait 2000
agent-browser -p kernel snapshot -i     # Interact with new tab

截图和调试

# Take screenshot
agent-browser -p kernel screenshot ~/Downloads/page.png

# Full page screenshot
agent-browser -p kernel screenshot ~/Downloads/full.png --full

# View console messages
agent-browser -p kernel console

# View page errors
agent-browser -p kernel errors

# Get current URL
agent-browser -p kernel get url

会话管理

清理

关闭你打开的同名 agent-browser 会话。这会保存配置文件更改并删除其 Kernel 浏览器：

agent-browser -p kernel close
# Named session: agent-browser -p kernel --session site1 close

如果 agent-browser 不可用或关闭失败，请显式删除孤立会话：

kernel browsers delete "$SESSION_ID"

如果可能有其他 agent-browser 会话正在运行，请勿使用 close --all。

多个会话

使用命名会话并行运行浏览器会话：

agent-browser -p kernel --session site1 open https://site1.com
agent-browser -p kernel --session site2 open https://site2.com
agent-browser -p kernel session list

常见问题

1. 导航后引用会变化：点击链接、提交表单或 DOM 发生重大更新后，重新获取快照。
2. 等待操作结果：异步操作后，使用 URL、文本、加载状态或 JavaScript 条件进行等待。
3. 提供方设置在启动时生效：更改 KERNEL_HEADLESS、KERNEL_STEALTH 或超时设置前，先关闭当前会话。
4. 配置文件持久化需要使用 CDP 变通方案：KERNEL_PROFILE_NAME 目前无法正常工作。关闭 agent-browser，然后删除由 CLI 创建的 Kernel 会话，以完成 --save-changes。
5. 隐身模式并非适用于所有网站：比较代理路由，使用手动登录，或遇到难以处理的框架时改用直接的 Playwright。

快速参考

# Start a standard provider session (for persistence, use the CDP workflow above)
export KERNEL_TIMEOUT_SECONDS=600
agent-browser -p kernel open https://example.com

# Basic interaction with semantic selectors (recommended)
agent-browser -p kernel wait --load domcontentloaded
agent-browser -p kernel find label "Email" fill "[email protected]"
agent-browser -p kernel find label "Password" fill "secret"
agent-browser -p kernel find role button click --name "Submit"
agent-browser -p kernel wait --url "**/success"

# Alternative: snapshot + refs (for exploration)
agent-browser -p kernel snapshot -i
agent-browser -p kernel fill @eN "text"
agent-browser -p kernel click @eM

# Resolve the underlying session before manual intervention
CDP_URL="$(agent-browser -p kernel get cdp-url)"
CDP_ENDPOINT="${CDP_URL%%\?*}"
SESSION_ID="$(kernel browsers list --status active --limit 100 -o json |
  jq -r --arg endpoint "$CDP_ENDPOINT" \
    '.[] | select((.cdp_ws_url | split("?")[0]) == $endpoint) | .session_id' |
  head -n 1)"
test -n "$SESSION_ID"
kernel browsers view "$SESSION_ID"

# Cleanup (delete by ID only if close fails)
agent-browser -p kernel close

选择器速查表

# Buttons and links
agent-browser -p kernel find role button click --name "Submit"
agent-browser -p kernel find role link click --name "Next"
agent-browser -p kernel find text "Click here" click

# Form inputs
agent-browser -p kernel find label "Email" fill "[email protected]"
agent-browser -p kernel find placeholder "Search" type "query"
agent-browser -p kernel find testid "username-input" fill "myuser"

# Smart waits
agent-browser -p kernel wait --load domcontentloaded
agent-browser -p kernel wait --text "Success"
agent-browser -p kernel wait --url "**/dashboard"
agent-browser -p kernel wait --fn "window.loaded === true"