agent-browser 会话管理实战多会话隔离、状态持久化与 Tab 固定Session Management【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/gh_mirrors/agen/agent-browser导读会话Session是 agent-browser面向 AI Agent 的浏览器自动化 CLI中管理浏览器隔离与状态的核心抽象。本文基于仓库skill-data/core/references/session-management.md展开系统讲解命名会话的创建与隔离属性、共享 Chrome 下的 Tab 固定--pin-tab语义、--restore状态自动持久化、手动状态文件、常用实战模式以及清理与最佳实践。读完本文你将能基于当前仓库的源码与命令实现为自己的 Agent 技能设计出稳定、可并发、可恢复的多浏览器会话方案。什么是会话隔离的浏览器上下文在 agent-browser 中每个--session name对应一个独立的浏览器会话。从源码与 CLI 结构看会话 ID 是连接 daemon、隔离浏览器上下文、承载状态持久化键的入口--session未指定时使用默认会话default session指定后所有命令都路由到对应会话的浏览器。会话之间互相隔离每个会话拥有完全独立的浏览器状态包括CookiesLocalStorage / SessionStorageIndexedDB缓存Cache浏览历史打开的标签页Open tabs这意味着同一台机器上可以并行运行多个互不干扰的浏览器非常适合多用户流程测试、并发爬取、A/B 对比等场景。重要提示一个会话 ID 本身只用于隔离 daemon 与浏览器实例并不自动启用状态持久化。如果没有配置恢复键restore keydaemon 关闭时会直接丢弃临时的浏览器状态与打开的标签页。持久化由下文介绍的--restore机制负责。命名会话Named Sessions用session id派生稳定会话 IDAgent 技能skill应当派生一个稳定 ID并在每条命令中复用。官方推荐的做法是SESSION$(agent-browser session id --scope worktree --prefix my-skill) agent-browser --session $SESSION --restore open https://app.example.com/loginsession id的 scope 解析逻辑在 cli/src/main.rs 的resolve_session_id_scope中worktree推荐默认优先取 Git worktree 根目录其次 Git 根目录最后取规范化后的当前目录。之所以是 Agent 的推荐默认值是因为并行 Agent 运行通常使用 worktree 隔离同一 worktree 内的 Agent 共享同一个稳定 IDcwd使用当前工作目录的规范化路径git-root严格使用 Git 根目录不在 Git 工作树内时报错。此外--prefix用于给 ID 加语义前缀--json可输出机器可读结果resolve_session_id_scope支持--scope worktree|cwd|git-root三种取值其他值会报 Unknown session id scope。多会话并行示例# Session 1: 认证流程 agent-browser --session auth open https://app.example.com/login # Session 2: 公开浏览独立的 cookies、存储 agent-browser --session public open https://example.com # 命令按会话隔离 agent-browser --session auth fill e1 userexample.com agent-browser --session public get text body两个会话拥有各自的 cookies 与存储互不串扰。共享 Chrome 下的 Tab 固定Tab Pinning in a Shared Browser完全隔离 vs 共享浏览器完全隔离发生在每个会话各自启动自己的浏览器时。但当多个会话通过--cdp port共享同一个 Chrome 时cookies 与存储是共享的只有标签页选择能区分会话。此时需要--pin-tab让每个会话固定在自己的标签页上agent-browser --session agent1 --cdp 9222 --pin-tab open https://site-a.com agent-browser --session agent2 --cdp 9222 --pin-tab open https://site-b.com会话会记住自己绑定的标签页按 CDP target id 记录持久化在会话的状态目录中因此 daemon 重启后也能重新挂到自己的标签页而不是去占用最近激活的那个。--pin-tab的严格语义--pin-tab环境变量AGENT_BROWSER_PIN_TAB1会让绑定变为严格模式无绑定时附加会打开一个新标签页而不是占用已有标签页若绑定的标签页被关闭命令会以tab_gone错误失败而不是静默作用到其他标签页。JSON 输出包含code: tab_gone、data.targetId以及可选的data.lastUrl该状态下恢复命令仍然可用运行tab new url绑定新标签页或用tab list切换到一个已有标签页其他会话或用户打开的标签页永远不会抢占被固定会话的激活标签页。从源码看--pin-tab是**按会话粘性sticky**的只需在会话创建时传一次后续命令与 daemon 重启都会保持严格语义需要显式关闭时传--no-pin-tab。会话的 pinned 状态保存在会话状态数据中见 cli/src/native/tab_binding.rs 的pinned字段其设计注释明确说明--pin-tab的粘性行为。关于lastUrl与跨会话引用结构化的lastUrl只限于清洗过的 HTTP(S) URL 与about:blankHTTP(S) URL 会移除凭据、查询串与片段data:等不透明 URL 会被省略在批量 JSON 中恢复对象出现在result而不是data下当某个会话需要引用另一个会话的标签页时使用tab list --json中的各标签页targetId——target id 在 daemon 重启后保持稳定与tN短 id 不同重跑共享标签页脚本如 #1530 的复现时每个会话的第一条命令都要加--pin-tab。不加时open有意保留旧行为、直接导航共享的激活标签页原脚本仍会冲突。使用--auto-connect而非--cdp附加时同理。会话状态持久化Session State Persistence自动恢复Automatic Restore--restore# 裸 --restore 使用当前 --session 作为持久化键 SESSION$(agent-browser session id --scope worktree --prefix next-dev-loop) agent-browser --session $SESSION --restore open https://app.example.com/dashboard当配置了--restore或其他恢复键时状态会在导航前加载并在关闭、daemon 关闭、空闲超时、兼容的重启时保存。浏览器打开期间还会周期性保存在命令稳定后至多每AGENT_BROWSER_AUTOSAVE_INTERVAL_MS一次默认 30000ms设为0则仅在关闭时保存所以用户手动关掉浏览器窗口也能留下最近的存档。空闲会话在配置了持久化时也会按同一间隔持续保存从而捕获页面自发产生的变化如 token 刷新。daemon 默认在没有命令或 dashboard 输入一小时后退出--idle-timeout time或AGENT_BROWSER_IDLE_TIMEOUT_MS可调节0表示禁用。默认超时豁免Headed 浏览器、Safari/iOS WebDriver 会话、用户附加的浏览器不受默认超时约束provider 拥有的云端浏览器不豁免。默认保存策略为--restore-save auto如果恢复失败或校验失败则跳过自动保存never则连周期性自动保存也一并禁用。恢复校验Restore Checks恢复后可校验页面是否真的恢复到了期望状态agent-browser --session $SESSION --restore --restore-check-url **/dashboard open https://app.example.com/dashboard agent-browser --session $SESSION --restore --restore-check-text Dashboard open https://app.example.com/dashboard agent-browser --session $SESSION --restore --restore-check-fn !!localStorage.getItem(session) open https://app.example.com/dashboard三个校验维度对应 flags 解析中的restore_check_url/restore_check_text/restore_check_fn见 cli/src/flags.rs--restore-check-url globURL 匹配 glob 模式--restore-check-text text页面包含指定文本--restore-check-fn js在页面上下文执行 JS 条件表达式。诊断session infoagent-browser --session $SESSION session info --json用于检查 daemon 与恢复状态输出示例见 cli/src/output.rs 附近的 CLI 帮助文本。恢复失败时可先用它定位问题参考核心技能文档中的故障排查Authentication expires mid-workflow 场景。手动状态文件Manual State Files当需要显式、可移植的 JSON 文件时使用state save、state load与--state pathagent-browser state save ./auth-state.json agent-browser state load ./auth-state.json agent-browser --state path open https://example.com注意不要让 Agent 手工构造~/.agent-browser/sessions/下的路径可复用的 Agent 会话应优先使用--restore。手动文件适合一次性迁移、跨机器搬运登录态等场景CLI 帮助中也给出agent-browser --auto-connect state save ./auth.json的取态技巧。常见实战模式Common Patterns模式一认证会话复用Authenticated Session Reuse#!/bin/bash SESSION$(agent-browser session id --scope worktree --prefix app) agent-browser --session $SESSION --restore open https://app.example.com/dashboard同一稳定 ID --restore让登录态跨命令、跨 daemon 重启存活。这是解决认证中途过期的核心手段配合session info --json诊断。模式二并发爬取Concurrent Scraping#!/bin/bash # 并发爬取多个站点 # 启动所有会话 agent-browser --session site1 open https://site1.com agent-browser --session site2 open https://site2.com agent-browser --session site3 open https://site3.com wait # 从每个会话提取 agent-browser --session site1 get text body site1.txt agent-browser --session site2 get text body site2.txt agent-browser --session site3 get text body site3.txt # 清理 agent-browser --session site1 close agent-browser --session site2 close agent-browser --session site3 close利用会话级隔离Shell 后台并行启动互不干扰的浏览器会话。模式三A/B 测试会话A/B Testing Sessions# 测试不同的用户体验 agent-browser --session variant-a open https://app.com?varianta agent-browser --session variant-b open https://app.com?variantb # 对比 agent-browser --session variant-a screenshot /tmp/variant-a.png agent-browser --session variant-b screenshot /tmp/variant-b.png两个会话持有独立 cookies 与存储可并行体验同一应用的不同变体。默认会话Default Session省略--session时命令使用默认会话# 以下使用同一个默认会话 agent-browser open https://example.com agent-browser snapshot -i agent-browser close # 关闭默认会话需要特别留意的是默认未命名会话是一个单例共享浏览器——它与机器上其他 Agent 共享并跨对话持久存在。在核心技能skill-data/core/SKILL.md中明确警告在默认会话中工作可能中途劫持其他 Agent 的页面或把人类用户留下的页面导航走。因此最佳实践是在首个命令前就设置命名会话export AGENT_BROWSER_SESSION$(agent-browser session id --scope worktree --prefix task)会话清理Session Cleanup# 关闭指定会话 agent-browser --session auth close # 列出活跃会话 agent-browser session listclose只关闭指定会话需要全部关闭时使用close --all。最佳实践Best Practices1. 语义化命名会话# 好目的清晰 agent-browser --session github-auth open https://github.com agent-browser --session docs-scrape open https://docs.example.com # 避免无意义命名 agent-browser --session s1 open https://github.com2. 始终清理# 用完即关 agent-browser --session auth close agent-browser --session scrape close即使配置了空闲超时也应在任务结束后显式close或close --all释放资源。3. 安全处理状态文件# 不要提交状态文件包含认证令牌 echo *.auth-state.json .gitignore # 使用后删除 rm /tmp/auth-state.json状态文件/存档中包含登录态与令牌等同机密文件处理。核心技能文档同样强调不要把秘密回显到日志敏感认证建议使用--restore配合 auth vault见 references/authentication.md。4. 为长任务设置超时# 为自动化脚本设置超时 timeout 60 agent-browser --session long-task get text body防止脚本卡死无限占用资源。相关资源核心技能总览skill-data/core/SKILL.md含 Persist session across runs、Run multiple browsers in parallel 等直接相关小节认证与登录模式skill-data/core/references/authentication.md会话状态持久化实现cli/src/native/state.rssave_state、save_auto_state_transactional、load_stateTab 绑定与--pin-tab粘性实现cli/src/native/tab_binding.rs全局 flags 解析--restore*、--pin-tab、--idle-timeout、--state、--namespace等cli/src/flags.rssession id的 scope 解析worktree / cwd / git-rootcli/src/main.rs【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/gh_mirrors/agen/agent-browser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考