Swarms × Stagehand 浏览器自动化集成实战Wrapper Agent、工具函数、MCP 服务与多智能体工作流【免费下载链接】swarmsThe Enterprise-Grade Multi-Agent Orchestration Framework. Website: https://swarms.ai项目地址: https://gitcode.com/GitHub_Trending/swar/swarms本篇技术指南以仓库 examples/tools/stagehand 目录为核心系统讲解如何将 StagehandAI 驱动的浏览器自动化框架无缝接入 Swarms 多智能体编排框架。读完本文你将掌握四种集成模式——包装为 Agent、拆分为独立工具、通过 MCP 服务器标准化接入、以及构建多智能体浏览器自动化工作流并能够直接在本地或云端Browserbase环境中落地电商比价、竞品分析、自动化测试与新闻聚合等实战场景。一、集成能力总览Stagehand 提供基于自然语言的浏览器自动化能力与 Swarms 结合后可实现自然语言网页自动化只需给出点击提交按钮提取商品价格这类指令即可驱动浏览器完成操作多智能体浏览器工作流多个 Agent 可同时自动化不同的网站互不干扰灵活的集成方式既可包装为 Swarms 兼容的 Agent也可作为单个工具或通过 MCP 服务器标准化接入复杂自动化场景覆盖电商监控、竞品分析、自动化测试、数据采集等。该集成在仓库中对应四个示例文件与配套测试结构如下文件集成方式核心价值1_stagehand_wrapper_agent.pyWrapper Agent最简单的集成继承 SwarmsAgent基类2_stagehand_tools_agent.py独立工具将 Stagehand 方法拆成可被 Agent 调度的细粒度工具3_stagehand_mcp_agent.pyMCP Server通过 Model Context Protocol 标准化接入支持多会话4_stagehand_multi_agent_workflow.py多智能体工作流组合并发/串行/重编排模式完成复杂任务依赖声明见 requirements.txtswarms8.0.0、stagehand0.1.0、python-dotenv1.0.0、pydantic2.0.0、loguru0.7.0另含httpx0.24.0MCP 示例可选与pytest7.0.0、pytest-asyncio0.21.0测试用。二、环境准备1. 安装依赖pip install swarms stagehand如需运行示例建议直接安装示例目录内的依赖集合pip install -r examples/tools/stagehand/requirements.txt2. 配置环境变量# 本地浏览器自动化基于 Playwright export OPENAI_API_KEYyour-openai-key # 云端浏览器自动化基于 Browserbase export BROWSERBASE_API_KEYyour-browserbase-key export BROWSERBASE_PROJECT_IDyour-project-id示例代码统一通过python-dotenv的load_dotenv()加载环境变量因此也可以把上述变量写入项目根目录的.env文件。从源码看StagehandConfig会依次使用构造参数与环境变量兜底见 1_stagehand_wrapper_agent.py例如api_keybrowserbase_api_key or os.getenv(BROWSERBASE_API_KEY)即显式传入的参数优先级最高。3. 启动 Stagehand MCP 服务器仅 MCP 模式需要cd stagehand-mcp-server npm install npm run build npm start服务器默认运行在http://localhost:3000/mcp。三、方式一Wrapper Agent 包装为 Swarms 智能体这是最简单的集成方式定义一个继承 SwarmsAgent基类的StagehandAgent把浏览器自动化能力整体封装成 Agent 的run()方法。from examples.stagehand.stagehand_wrapper_agent import StagehandAgent # 创建一个浏览器自动化 Agent browser_agent StagehandAgent( agent_nameWebScraperAgent, model_namegpt-5.4, envLOCAL, # 或 BROWSERBASE 使用云端执行 ) # 用自然语言控制浏览器 result browser_agent.run( Navigate to news.ycombinator.com and extract the top 5 story titles )该模式的特点继承自 SwarmsAgent基类源码中为class StagehandAgent(SwarmsAgent)见 1_stagehand_wrapper_agent.py自动管理浏览器生命周期首次调用run()时通过_init_stagehand()惰性初始化 Stagehand 实例Stagehand(config)后执行await stagehand.init()并设置_initialized标志防止重复初始化自然语言任务解析run()内部通过asyncio.run()桥接异步实现_execute_browser_task()会根据任务文本中的关键词分派不同浏览器操作。源码级解析任务如何被解析执行StagehandAgent.run()返回 JSON 字符串内部状态结构为{task: ..., status: ..., data: {...}}。分派逻辑见 1_stagehand_wrapper_agent.py可概括为任务关键词执行动作底层 Stagehand 调用navigate/go to/visit/open从任务文本中提取 URL 并跳转page.goto(url)extract去除 extract 后的描述作为提取提示page.extract(prompt)click/press执行点击等操作page.act(task)search解析搜索词先observe定位搜索框再点击、输入、回车page.observe()page.act()组合observe/find观察页面元素返回描述与选择器page.observe(task)其他通用操作page.act(task)URL 提取采用两层正则回退先用rhttps?://[^\s]匹配完整 URL若未命中且任务文本包含.com/.org/.net等域名特征再用r(\w\.\w)提取域名并自动补全为https://前缀。浏览器资源释放通过cleanup()完成同时__del__析构函数也会兜底调用cleanup()确保对象被回收时浏览器能够关闭见 1_stagehand_wrapper_agent.py。值得注意的是_async_run()的finally分支刻意保持浏览器开启以便后续任务复用同一页面会话。四、方式二将 Stagehand 方法拆分为独立工具这种方式把 Stagehand 的act、extract、observe等方法各自封装为独立的 Swarms 工具交给标准Agent调度让 LLM 自行决定何时用哪个工具控制粒度更细。from swarms import Agent from examples.stagehand.stagehand_tools_agent import ( NavigateTool, ActTool, ExtractTool, ObserveTool, ScreenshotTool ) browser_agent Agent( agent_nameBrowserAutomationAgent, model_namegpt-5.4, tools[ NavigateTool(), ActTool(), ExtractTool(), ObserveTool(), ScreenshotTool(), ], ) result browser_agent.run( Go to google.com, search for Python tutorials, and extract the first 3 results )可用工具一览工具对应 Stagehand 能力说明NavigateToolpage.goto(url)跳转到指定 URLActToolpage.act(action)执行点击、输入、滚动等动作ExtractToolpage.extract(query)从页面提取数据ObserveToolpage.observe(query)查找并观察页面元素ScreenshotToolPlaywrightpage.screenshot()捕获页面截图CloseBrowserToolstagehand.close()清理浏览器资源源码级解析BrowserState 单例与工具实现该模式的核心是BrowserState单例类见 2_stagehand_tools_agent.py它通过__new__保证全进程只有一份浏览器实例多个工具共享同一页面会话init_browser()惰性初始化用StagehandConfig组装配置并执行stagehand.init()重复调用不会重复创建get_page()返回当前页面实例未初始化时抛出RuntimeErrorclose()关闭浏览器并复位_initialized标志。工具函数本身是同步入口 异步实现的经典组合例如navigate_browser(url) - asyncio.run(_navigate_browser_async(url))异步实现内部做三件事确保浏览器已初始化、为无协议 URL 自动补https://前缀、调用page.goto()。browser_extract()会把dict/list类型结果json.dumps(indent2)序列化为 JSON 字符串方便 LLM 直接消费browser_observe()将观测结果规范化为{description, selector, method}结构browser_screenshot()通过page.page拿到底层 Playwright 页面对象保存截图并自动补充.png扩展名。在实际示例的__main__中这些工具以普通函数形式navigate_browser、browser_act、browser_extract、browser_observe、browser_screenshot、close_browser直接传入Agent(..., tools[...])并配合专门编写的系统提示词指导 Agent 使用工具例如Always start by navigating to a URL before trying to interact with a pageWhen done with tasks, close the browser。五、方式三通过 Stagehand MCP Server 标准化接入MCPModel Context Protocol模式把浏览器能力包装成标准化的服务器工具Agent 自动发现并调用无需在 Agent 内直接 import Stagehand。同时 MCP 服务器自带多会话管理与截图资源。from examples.stagehand.stagehand_mcp_agent import StagehandMCPAgent mcp_agent StagehandMCPAgent( agent_nameWebResearchAgent, mcp_server_urlhttp://localhost:3000/mcp, ) result mcp_agent.run( Create 3 browser sessions and: 1. Session 1: Check Python.org for latest version 2. Session 2: Check PyPI for trending packages 3. Session 3: Check GitHub Python trending repos Compile a Python ecosystem status report. )MCP 模式特性自动工具发现Agent 连接 MCP 服务器后自动获取可用工具列表多会话浏览器管理createSession/listSessions/closeSession支持并行会话内置截图资源服务器可直接提供截图能力常用任务提示模板针对导航、提取、观察等任务预置 prompt。源码级解析mcp_url参数与多会话群在源码实现中StagehandMCPAgent并未直接操作 Stagehand而是把mcp_urlmcp_server_url传给 SwarmsAgent见 3_stagehand_mcp_agent.py由 Swarms 框架统一管理 MCP 连接。Agent的构造参数中mcp_url支持传入 URL 字符串、MCPConnection对象或字典见 swarms/structs/agent.py框架会把 MCP 服务器暴露的工具合并进 Agent 的工具集。示例还定义了MultiSessionBrowserSwarm群见 3_stagehand_mcp_agent.py它创建三个分工明确的 Agent——DataExtractor结构化数据提取、FormFiller表单填写与 Web 应用交互、WebMonitor网站变更监控与截图每个 Agent 的系统提示词都要求Always create your own session for tasks to work independently from other agents保证并行互不干扰。distribute_tasks()以轮询round-robin方式把任务列表分发给各 Agent。MCP 服务器的系统提示词中列出了可供调用的工具navigate、act、extract、observe、screenshot以及会话管理三件套createSession、listSessions、closeSession多会话模式下还有navigate_session、act_session、extract_session、observe_session等按会话定位的操作。六、方式四构建多智能体浏览器自动化工作流这是集成的高级形态把多个StagehandAgent与普通分析型Agent组合进 Swarms 的工作流编排结构中实现并发采集 → 智能分析 → 报告生成的完整流水线。示例位于 4_stagehand_multi_agent_workflow.py提供了四个可直接调用的工作流工厂函数。1. 电商价格对比工作流create_price_comparison_workflow()from examples.stagehand.stagehand_multi_agent_workflow import ( create_price_comparison_workflow, ) price_workflow create_price_comparison_workflow() result price_workflow.run( Compare prices for iPhone 15 Pro on Amazon and eBay )其结构为两段式串联先用ConcurrentWorkflow并发运行AmazonScraperAgent与EbayScraperAgent并行抓取两个站点再把采集结果交给PriceAnalysisAgent普通 LLM Agent系统提示词定位为价格分析专家输出比价结论与购买建议。整体用SequentialWorkflow(agents[scraping_workflow, analysis_agent])串联。2. 竞品分析工作流create_competitive_analysis_workflow()competitive_workflow create_competitive_analysis_workflow() result competitive_workflow.run( Analyze OpenAI, Anthropic, and DeepMind websites and social media )该工作流用AgentRearrange实现显式路由三个 Agent——company_researcher公司信息抓取、social_media_agent社媒分析、report_compiler报告编写——通过流程字符串company_researcher - social_media_agent - report_compiler固定执行顺序形成抓取 → 分析 → 汇总的线性管道。3. 自动化测试工作流create_automated_testing_workflow()UITestingAgent、FormValidationAgent、AccessibilityTestingAgent三个浏览器 Agent 通过ConcurrentWorkflow并发执行 UI、表单、无障碍三类测试测试结果由TestReportCompiler统一汇总输出失败项、告警与修复建议。4. 新闻聚合与情感分析工作流create_news_aggregation_workflow()为 TechCrunch、HackerNews、Reddit 各创建一个StagehandAgent并发抓取随后由SentimentAnalyzer判定新闻情感倾向积极/消极/中性再由TrendIdentifier归纳新兴趋势与热点话题形成并发抓取 → 情感分析 → 趋势识别的完整链路。工作流模式汇总工作流编排模式浏览器 Agent分析 Agent电商监控ConcurrentWorkflowSequentialWorkflow21竞品分析AgentRearrange线性流21自动化测试ConcurrentWorkflowSequentialWorkflow31新闻聚合ConcurrentWorkflowSequentialWorkflow32这些编排类在仓库中的实现分别位于 swarms/structs/concurrent_workflow.py、swarms/structs/sequential_workflow.py 与 swarms/structs/agent_rearrange.py。工作流还配套了 Pydantic 数据模型ProductInfo、MarketAnalysis规范采集结果的结构化输出其中MarketAnalysis包含时间戳、商品列表、价格区间与建议字段保证最终报告可解析、可持久化。七、测试验证仓库为集成提供了两套测试运行方式pytest examples/tools/stagehand/tests/test_stagehand_integration.py -vtest_stagehand_integration.py通过MockStagehand/MockStagehandPage模拟 Stagehand 对象覆盖 Wrapper Agent 的初始化、导航提取任务、搜索任务与 cleanup 后再运行覆盖NavigateTool/ActTool/ExtractTool/ObserveTool四个工具的调用链路覆盖 MCP Agent 初始化、MultiSessionBrowserSwarm创建与轮询任务分发并验证四个工作流工厂的编排结构如价格对比工作流应为2 个 Agent、首元素为并发工作流、竞品分析工作流flow字符串精确匹配等。test_stagehand_simple.py不依赖外部包的结构性测试校验示例文件必需 import、class StagehandAgent(SwarmsAgent):继承模式、工具函数签名如def navigate_browser(url: str) - str:、MCP 模式中的mcp_url参数、URL 提取正则逻辑以及 README 关键章节与 requirements 依赖的完整性。需要注意示例代码中的导入路径以examples.stagehand.*形式书写而本仓库中文件实际位于examples/tools/stagehand/目录运行时请按实际目录调整导入路径或把示例目录加入 Python 路径。八、典型应用场景电商自动化价格监控与跨站比价库存跟踪自动化采购流程评论聚合研究与分析竞争情报采集市场调研自动化社交媒体监控新闻与趋势分析质量保障自动化 UI 测试跨浏览器兼容性测试表单校验测试无障碍Accessibility合规检查数据采集规模化网页抓取实时数据监控结构化数据提取截图文档留档九、最佳实践资源管理任务结束后务必清理浏览器实例browser_agent.cleanup() # Wrapper Agent 使用错误处理Stagehand 自带自我修复self-healing能力但关键操作仍建议包裹 try-except 块示例源码中每个工具的异步实现均已捕获异常并返回可读错误消息。并行执行跨多站点同时自动化时使用ConcurrentWorkflow编排多个浏览器 Agent四个工作流示例即是标准范式。会话管理复杂多页面工作流如同一会话内连续访问多个仓库页面优先使用 MCP 服务器的会话管理能力按会话定位操作。限速与礼貌抓取对目标网站保持尊重必要时在请求之间加入延迟。十、故障排查常见问题浏览器无法启动确认 Playwright 已正确安装playwright installMCP 连接失败确认 MCP 服务器运行在正确的端口默认http://localhost:3000/mcp并已执行npm run build完成构建。超时错误在StagehandConfig或 Agent 初始化中调大超时时间。调试模式开启详细日志便于定位问题agent StagehandAgent( agent_nameDebugAgent, verboseTrue, # 启用详细日志 )示例源码全程使用loguru记录关键节点日志初始化、导航、关闭浏览器等配合verboseTrue即可观察到完整的执行轨迹。十一、结语本文以 examples/tools/stagehand 目录为骨架完整覆盖了 Stagehand 与 Swarms 的四种集成范式Wrapper Agent 适合快速上手与单一 Agent 场景独立工具模式适合精细控制与工具复用MCP 模式适合标准化与多会话并行多智能体工作流则面向电商监控、竞品分析、自动化测试与新闻聚合等规模化场景。从 Wrapper Agent 的自然语言任务解析到BrowserState单例的共享页面管理再到mcp_url参数与AgentRearrange流程编排仓库源码与测试用例共同验证了每条链路的行为。读者可在此基础上将浏览器自动化能力无缝注入自己的多智能体系统中。【免费下载链接】swarmsThe Enterprise-Grade Multi-Agent Orchestration Framework. Website: https://swarms.ai项目地址: https://gitcode.com/GitHub_Trending/swar/swarms创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考