1. 项目缘起：当AI Agent需要一双“看得见”的手

最近在折腾AI Agent项目时，遇到了一个核心瓶颈：我的Agent能说会道，逻辑清晰，但一到需要它去网页上点个按钮、填个表单、查个数据的时候，它就“傻眼”了。它知道该做什么，但不知道如何操作浏览器。这就像给一个顶级厨师配了一个全自动厨房，但他却不知道怎么打开燃气灶和烤箱。为了解决这个“最后一公里”的问题，我开始系统性地研究如何为AI Agent赋予浏览器自动化的能力，并最终沉淀出一套可复用的技能库，我称之为 BrowserAct Skills 。

这个技能库的核心目标，是让AI Agent能够像真人一样，理解网页的结构和内容，并执行精确的交互操作。它不是一个独立的工具，而是AI Agent大脑（通常是大型语言模型）与物理世界（网页）之间的“手眼协调系统”。通过这套系统，Agent可以自主完成信息查询、数据录入、流程审批、监控报警等一系列需要与Web界面打交道的任务。无论是想做一个自动比价机器人、一个7x24小时运行的RPA流程，还是一个能帮你处理日常琐事的智能助手，BrowserAct Skills都是其不可或缺的核心组件。

2. 核心组件选型：为什么是Playwright？

为AI Agent选择浏览器自动化工具，远不止是“哪个库更好用”那么简单。这关系到Agent的稳定性、执行效率、隐蔽性以及未来的可扩展性。我对比了市面上主流的几个方案：Selenium、Puppeteer和Playwright。

Selenium 是老牌劲旅，生态成熟，支持语言多。但对于AI Agent场景，它的缺点也很明显：执行速度相对较慢，对现代Web应用（尤其是大量使用JavaScript和动态加载的SPA）的支持有时会力不从心，且需要额外的WebDriver进行桥接，增加了部署和管理的复杂度。

Puppeteer 由Chrome团队开发，直接通过DevTools Protocol控制Chrome/Chromium，性能强大，对Chrome生态的支持是原生的。它一度是我的首选。然而，它的“血统”也限制了它——主要专注于Chromium系浏览器。虽然也有社区项目尝试支持Firefox和WebKit，但体验和稳定性无法与官方支持相提并论。

最终，我选择了 Playwright 。原因如下：

1. 跨浏览器原生支持 ：Playwright由微软团队开发，从一开始就为Chromium、Firefox和WebKit（Safari的引擎）提供了统一且稳定的API。这意味着你的Agent技能可以无缝运行在几乎所有主流浏览器上，无需为不同浏览器编写适配代码。对于需要模拟真实用户环境或应对特定网站兼容性要求的场景，这是决定性优势。

2. 自动等待与智能选择器 ：Playwright内置了强大的自动等待机制。在执行如 click 、 fill 等操作前，它会自动等待元素可交互（可见、启用、稳定）。这极大地简化了代码，避免了在AI Agent指令中频繁插入 sleep 或复杂的状态判断逻辑。其选择器引擎也非常强大，支持文本选择（ text= ）、CSS、XPath，还能自动生成稳健的选择器，这对于由LLM动态生成操作指令的场景至关重要。

3. 网络拦截与Mock能力 ：Agent在执行任务时，可能需要对网络请求进行监听、修改或Mock。Playwright提供了完整的网络API，可以轻松拦截请求、修改响应、模拟离线状态等。这对于测试、数据抓取（在合规前提下）或绕过某些前端验证逻辑非常有用。

4. 移动端模拟与设备描述符 ：Playwright内置了丰富的设备描述符（如iPhone、Pixel等），可以一键模拟移动端浏览器环境，包括视口、User-Agent、触摸事件等。这让Agent能够处理响应式网站或专门的移动端任务。

5. 执行速度与资源控制 ：Playwright启动浏览器上下文（Context）的速度很快，并且可以严格控制在同一个浏览器实例中运行多个独立的、隔离的会话（Context），每个会话拥有独立的cookie、localStorage，互不干扰。这非常适合需要同时处理多个任务的Agent。

注意：关于“Playwright能被网站识别出来吗？”这个问题，答案是：可以，但可以通过一些手段进行缓解。默认情况下，Playwright启动的浏览器带有一些特定的自动化特征（如 navigator.webdriver 属性为true）。一些反爬虫严格的网站会检测这些特征。解决方案包括使用 stealth 插件、启动带用户数据目录的持久化上下文来模拟真实用户，或者结合代理IP轮换等策略。但对于大多数企业内部应用或公开信息查询场景，默认配置已足够。

基于以上原因， BrowserAct Skills 的技能底层均基于Playwright构建，以确保能力基线的一致性和高度可扩展性。

3. BrowserAct Skills 技能库架构设计

一个完整的浏览器自动化技能，不能只是简单封装几个Playwright的API调用。它需要被AI Agent安全、可靠、灵活地调用。我的设计围绕以下几个核心层次展开：

3.1 技能抽象层：定义Agent的“动作词汇表”

这是最上层，面向AI Agent的“思考”部分。我们将复杂的浏览器操作抽象成一个个原子技能（Skill）或复合技能（Workflow）。

• 原子技能 ：最小单位的操作。例如：

  • navigate_to(url) : 导航到指定网址。
  • extract_text(selector) : 提取指定元素的文本。
  • click_element(selector) : 点击元素。
  • fill_form(selector, text) : 向输入框填充文本。
  • screenshot(selector) : 对页面或元素截图。
  • get_page_state() : 获取当前页面的URL、标题和主要文本内容摘要（供LLM判断状态）。

• 复合技能/工作流 ：由多个原子技能按逻辑组合而成。例如：

  • login_to_site(credentials) : 可能包含导航、等待加载、填写用户名密码、点击登录、验证登录成功等多个原子步骤。
  • search_and_collect(keyword, max_results) : 在电商网站完成搜索、翻页、提取商品信息列表。

每个技能都有明确的输入参数、输出结果和可能发生的异常。AI Agent（LLM）通过一个标准的接口（如JSON-RPC、函数调用Function Calling）来调用这些技能。

3.2 执行引擎层：Playwright的封装与增强

这一层负责将上层的技能描述，翻译成具体的Playwright操作，并处理所有底层细节。

• 上下文管理 ：管理浏览器实例（Browser）、上下文（Context）和页面（Page）的生命周期。实现连接的复用、异常恢复和资源清理。
• 稳健性执行 ：内置重试机制。例如，点击操作因为元素临时被遮挡而失败时，引擎会自动重试几次，而不是立即报错。
• 状态感知 ：在执行技能前后，自动捕获页面状态（如URL变化、弹窗出现、主要元素可见性），并将这些状态反馈给上层或记录日志，用于故障排查和Agent的下一步决策。
• 结果解析与标准化 ：将Playwright返回的原始数据（如ElementHandle、Response对象）解析并格式化为Agent容易理解的标准化数据（如字符串、字典、列表）。

3.3 控制与编排层：连接AI大脑与技能手

这是整个系统的中枢，负责接收AI Agent的指令，调度合适的技能执行，并管理执行流程。

1. 指令解析与规划 ：AI Agent（如基于GPT、Claude等LLM构建）发出自然语言或结构化指令（如“去京东搜索iPhone 15，并返回前三名的价格”）。控制层需要理解意图，并将其分解为一个可执行的技能序列（规划）。这可以通过LLM自身的规划能力，或结合预定义的工作流模板来实现。

2. 技能路由与执行 ：根据规划，依次调用技能库中对应的原子或复合技能。并处理技能之间的数据传递（例如，将 search 技能得到的商品列表URL，传递给 extract_detail 技能）。

3. 异常处理与恢复 ：当某个技能执行失败（如元素未找到、网络超时），控制层不能直接崩溃。它需要：

   • 捕获异常 ：获取详细的错误信息（错误类型、截图、当前页面HTML片段）。
   • 决策与恢复 ：将错误信息和当前状态反馈给AI Agent，由Agent决定是重试、跳过、执行备用方案还是终止任务。例如，Agent可能会判断“价格元素的选择器变了”，然后尝试使用 extract_text 配合更宽泛的文本匹配来获取价格。
   • 状态回滚 ：对于关键流程，可能需要实现检查点（Checkpoint），以便在失败时回退到上一个稳定状态。

4. 记忆与上下文管理 ：为Agent提供短期记忆，记住之前操作的结果（如登录后的会话cookie、已收集的数据），确保后续技能能在正确的上下文中执行。

3.4 监控与可观测性层

对于长时间运行或重要的Agent任务，必须知道它“正在做什么”以及“做得怎么样”。

• 日志记录 ：详细记录每个技能的调用、参数、开始结束时间、结果和错误。
• 视觉回溯 ：自动在关键步骤（如技能开始/结束、发生错误时）对页面进行截图，甚至录制屏幕视频。这是事后排查问题的“黑匣子”。
• 性能指标 ：收集页面加载时间、技能执行耗时、成功率等指标，用于优化技能性能和发现系统瓶颈。
• 报告生成 ：可以集成类似Allure的报告框架，将一次完整的任务执行过程生成结构化的、可视化的测试报告，清晰展示每个步骤的状态。

4. 实战：构建一个“商品价格监控”Agent技能

让我们用一个具体例子，把上述架构串起来。目标是构建一个技能，让Agent能每天自动监控某电商网站特定商品的价格变化。

4.1 技能分解与实现

首先，我们定义几个核心原子技能，它们将是构建块：

# 伪代码，展示技能接口
class BrowserActSkill:
    async def execute(self, page, params):
        """执行技能的核心方法"""
        pass

class NavigateSkill(BrowserActSkill):
    async def execute(self, page, params):
        url = params['url']
        await page.goto(url, wait_until='networkidle') # 等待网络空闲
        return {'current_url': page.url, 'title': await page.title()}

class ExtractTextSkill(BrowserActSkill):
    async def execute(self, page, params):
        selector = params['selector']
        element = page.locator(selector)
        if await element.count() > 0:
            text = await element.first.text_content()
            return {'text': text.strip()}
        else:
            raise SkillExecutionError(f"Element with selector '{selector}' not found.")

class ScreenshotSkill(BrowserActSkill):
    async def execute(self, page, params):
        selector = params.get('selector', 'body') # 默认为整个页面
        path = params.get('path', f'screenshot_{int(time.time())}.png')
        await page.locator(selector).screenshot(path=path)
        return {'screenshot_path': path}

接着，我们组合这些原子技能，形成一个复合技能 MonitorProductPriceSkill ：

1. 导航到商品页面 ：使用 NavigateSkill 。
2. 等待价格元素加载 ：这里需要一点技巧。价格可能由JS动态加载。我们可以使用Playwright的 page.wait_for_selector 或 page.wait_for_function 来等待特定元素出现或内容不为空。
3. 提取价格文本 ：使用 ExtractTextSkill 。选择器需要提前确定（如 .price 或 [data-price] ）。
4. 解析价格 ：将提取的文本（如“￥5,299”或“$129.99”）转换为浮点数。
5. 截图存档 ：使用 ScreenshotSkill 对价格区域截图，作为价格证据。
6. 返回结构化数据 ：返回商品名称、当前价格、截图路径、监控时间。

4.2 集成AI Agent进行决策

现在，我们有了一个可以获取价格的技能。但一个完整的监控Agent还需要“大脑”：

• 任务触发 ：可以使用定时任务（如cron）每天触发Agent。
• 指令生成 ：Agent的初始指令是固定的：“执行商品价格监控技能，目标URL是[商品链接]”。
• 结果处理 ：Agent收到技能返回的结构化数据（价格）后，需要与历史记录（如存储在数据库或文件中的昨日价格）进行比较。
• 决策与通知 ：如果价格低于设定阈值或发生较大波动，Agent可以调用另一个“发送通知”的技能（如调用邮件API、发送钉钉/飞书消息），告知用户“iPhone 15降价了！”。
• 异常处理 ：如果 MonitorProductPriceSkill 执行失败（比如网站改版导致选择器失效），控制层将错误信息（包含错误截图）反馈给Agent。Agent可以分析错误，尝试调整策略（例如，让它尝试用包含“价格”二字的文本元素来定位），或者直接通知用户“监控任务失败，请检查”。

这个过程中，AI Agent的价值在于 状态判断、决策制定和有限的适应性调整 ，而BrowserAct Skills则提供了 稳定可靠的浏览器交互执行能力 。

4.3 部署与运行环境考量

对于此类自动化Agent，部署方式很关键：

• 本地运行 ：适合个人使用或开发测试。可以直接在个人电脑上运行Python脚本。但需要保证电脑不关机，且网络稳定。

• 服务器部署 ：更可靠的方式。使用Linux服务器，通过 systemd 或 supervisor 管理进程。Playwright需要在服务器上安装浏览器，可以使用其自带的 playwright install 命令安装依赖。

• 容器化部署 ：最佳实践。使用Docker镜像。官方提供了 mcr.microsoft.com/playwright/python 镜像，内置了所有浏览器依赖。将你的Agent代码和技能库打包进镜像，可以轻松实现水平扩展和环境一致性。

  • 关于“怎么实现playwright + allure部署” ：在Dockerfile中，可以安装Allure命令行工具，并在任务执行完毕后，调用Allure生成报告，并将报告文件输出到挂载的卷中，或上传到静态文件服务器。

• 无头模式与有头模式 ：生产环境通常使用无头模式（ headless=True ）以节省资源。但在调试复杂问题或需要查看具体交互过程时，可以设置为有头模式（ headless=False ），甚至配合 slow_mo 参数慢放操作。

5. 深入技能开发：高级模式与避坑指南

在构建更复杂的技能时，你会遇到一些挑战。以下是我在实践中总结的经验和解决方案。

5.1 处理动态内容与等待策略

现代网页大量使用异步加载，元素不会一次性全部出现。

• 坑1：元素未找到（Element not found） 。这是最常见的问题。

  • 解决方案 ：永远不要使用固定的 sleep 。优先使用Playwright内置的等待。
    1. 自动等待 ： page.click(selector) 本身就会等待元素可点击。
    2. 显式等待 ：对于非交互性元素，或需要等待特定状态，使用 page.wait_for_selector(selector, state='visible') 。 state 参数可以是 'attached' , 'detached' , 'visible' , 'hidden' 。
    3. 网络等待 ：如果元素内容依赖于某个API请求，可以使用 page.wait_for_response(url_pattern) 等待特定请求完成。
    4. 自定义等待 ：使用 page.wait_for_function 等待页面JavaScript状态满足某个条件，例如 page.wait_for_function('document.querySelector(".price").innerText.includes("￥")') 。

• 坑2：iframe和Shadow DOM 。有些元素嵌套在iframe或Shadow DOM内部，常规选择器无法直接定位。

  • 解决方案 ：
    • iframe ：先用 page.frame(name_or_url) 获取frame对象，然后在这个frame对象上使用选择器。
    • Shadow DOM ：Playwright的 locator 可以直接穿透Shadow DOM。使用 page.locator('parent-component::shadow-root child-element') 这样的语法（具体取决于浏览器支持），或者更通用的，使用JavaScript表达式通过 page.evaluate 来操作Shadow DOM内的元素。

5.2 管理状态与会话持久化

很多操作需要登录状态。让Agent每次任务都重新登录是不现实的。

• 解决方案：使用BrowserContext和存储状态 。

  import asyncio
  from playwright.async_api import async_playwright
  import json
  
  async def main():
      async with async_playwright() as p:
          # 启动浏览器，使用持久化上下文，指定用户数据目录
          browser = await p.chromium.launch_persistent_context(
              user_data_dir='./user_data', # 保存cookie、localStorage的目录
              headless=False
          )
          page = await browser.new_page()
  
          # 第一次运行，需要手动登录
          await page.goto('https://example.com/login')
          # ... 假设手动完成登录 ...
  
          # 关闭浏览器后，user_data_dir 中的状态会被保存。
  
          # 第二次及以后运行，使用相同的 user_data_dir 启动
          # 浏览器会自动加载之前的登录状态，无需再次登录。
          await page.goto('https://example.com/dashboard')
          # 此时应该已经是登录状态了
          await browser.close()
  

  通过复用 user_data_dir ，可以实现会话的持久化。这对于需要登录的网站技能至关重要。可以将不同的Agent或任务分配到不同的 user_data_dir ，实现状态隔离。

5.3 提升性能与稳定性

• 并发控制 ：一个Agent可能需要同时监控多个商品。不要为每个任务都启动一个独立的浏览器，这太耗资源。应该使用一个浏览器实例，创建多个独立的Browser Context。每个Context就像是一个独立的隐身会话，互不干扰，但共享浏览器进程。

  # 创建多个隔离的上下文
  context1 = await browser.new_context()
  page1 = await context1.new_page()
  # 任务1在page1上执行
  
  context2 = await browser.new_context()
  page2 = await context2.new_page()
  # 任务2在page2上执行，cookie和本地存储与page1完全隔离
  

• 超时与重试 ：为所有网络请求和操作设置合理的超时时间，并实现重试逻辑。Playwright的许多方法都接受 timeout 参数。在技能执行层，可以包裹一个重试装饰器。

  import asyncio
  from functools import wraps
  
  def retry_on_failure(max_retries=3, delay=1):
      def decorator(func):
          @wraps(func)
          async def wrapper(*args, **kwargs):
              last_exception = None
              for attempt in range(max_retries):
                  try:
                      return await func(*args, **kwargs)
                  except Exception as e:
                      last_exception = e
                      print(f"Attempt {attempt + 1} failed: {e}")
                      if attempt < max_retries - 1:
                          await asyncio.sleep(delay)
              raise last_exception
          return wrapper
      return decorator
  
  @retry_on_failure(max_retries=2)
  async def robust_click(page, selector):
      await page.click(selector)
  

• 资源清理 ：确保在任务结束后，正确关闭page、context和browser，避免内存泄漏。使用 async with 语句块是很好的实践。

6. 生态整合与未来展望

BrowserAct Skills不是一个孤岛，它可以与更广阔的AI Agent生态整合。

• 与LLM应用框架结合 ：可以轻松集成到LangChain、LlamaIndex、Semantic Kernel等框架中。将这些技能封装成LangChain的Tool或Semantic Kernel的Plugin，让框架来负责技能的编排和LLM的调用。
• 模型上下文协议（MCP） ：这是一个新兴的、用于连接LLM与工具/数据源的协议标准。可以将BrowserAct Skills包装成MCP Server，这样任何兼容MCP的AI Agent平台（如Claude Desktop、某些IDE插件）都能直接发现并调用你的浏览器技能，极大地提升了技能的通用性。
• 低代码/可视化编排 ：对于复杂的业务流程，可以开发一个可视化界面，让用户通过拖拽的方式将原子技能组合成工作流，而无需编写代码。AI Agent则可以负责执行这个预定义的工作流，或者在运行时对其进行动态调整。

开发一个成熟的AI Agent，尤其是涉及浏览器自动化的Agent，确实需要多方面的技术能力：对Playwright等自动化工具的熟练掌握、对异步编程的理解、设计稳定架构的能力、与LLM交互的工程经验，以及运维部署的知识。但起点可以很低，从一个能自动查询天气、获取新闻摘要的小技能开始，逐步迭代，你会发现为AI赋予“手眼”能力，所能开启的自动化场景是无比广阔的。从我自己的实践来看，最大的收获不是省了多少时间，而是建立了一种新的思维方式——如何将模糊的指令，拆解成机器可精确执行的步骤序列，这本身就是对问题解决能力的深度锤炼。