Stagehand 工具

概览

StagehandTool 将 Stagehand 框架与 CrewAI 集成，使智能体能够通过自然语言指令与网站交互并自动执行浏览器任务。

概览

Stagehand 是 Browserbase 构建的强大浏览器自动化框架，可让 AI 智能体：

• 导航到网站
• 点击按钮、链接和其他元素
• 填写表单
• 从网页中提取数据
• 观察并识别元素
• 执行复杂工作流

StagehandTool 封装了 Stagehand Python SDK，通过三个核心原语为 CrewAI 智能体提供浏览器控制能力：

1. Act：执行点击、输入或导航等操作
2. Extract：从网页中提取结构化数据
3. Observe：识别并分析页面上的元素

先决条件

在使用此工具之前，请确保你具备：

1. 一个 Browserbase 账户，包含 API key 和 project id
2. 一个 LLM 的 API key（OpenAI 或 Anthropic Claude）
3. 已安装 Stagehand Python SDK

安装所需依赖：

pip install stagehand-py

使用

基本实现

StagehandTool 可以通过两种方式实现：

1. 使用上下文管理器（推荐）

Tip

推荐使用上下文管理器，因为即使发生异常，它也能确保资源被正确清理。

from crewai import Agent, Task, Crew
from crewai_tools import StagehandTool
from stagehand.schemas import AvailableModel

# 使用上下文管理器和你的 API keys 初始化工具
with StagehandTool(
    api_key="your-browserbase-api-key",
    project_id="your-browserbase-project-id",
    model_api_key="your-llm-api-key",  # OpenAI 或 Anthropic API key
    model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST,  # 可选：指定使用哪个模型
) as stagehand_tool:
    # 创建一个使用该工具的智能体
    researcher = Agent(
        role="Web Researcher",
        goal="Find and summarize information from websites",
        backstory="I'm an expert at finding information online.",
        verbose=True,
        tools=[stagehand_tool],
    )

    # 创建一个使用该工具的任务
    research_task = Task(
        description="Go to https://www.example.com and tell me what you see on the homepage.",
        agent=researcher,
    )

    # 运行 crew
    crew = Crew(
        agents=[researcher],
        tasks=[research_task],
        verbose=True,
    )

    result = crew.kickoff()
    print(result)

2. 手动资源管理

from crewai import Agent, Task, Crew
from crewai_tools import StagehandTool
from stagehand.schemas import AvailableModel

# 使用你的 API keys 初始化工具
stagehand_tool = StagehandTool(
    api_key="your-browserbase-api-key",
    project_id="your-browserbase-project-id",
    model_api_key="your-llm-api-key",
    model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST,
)

try:
    # 创建一个使用该工具的智能体
    researcher = Agent(
        role="Web Researcher",
        goal="Find and summarize information from websites",
        backstory="I'm an expert at finding information online.",
        verbose=True,
        tools=[stagehand_tool],
    )

    # 创建一个使用该工具的任务
    research_task = Task(
        description="Go to https://www.example.com and tell me what you see on the homepage.",
        agent=researcher,
    )

    # 运行 crew
    crew = Crew(
        agents=[researcher],
        tasks=[research_task],
        verbose=True,
    )

    result = crew.kickoff()
    print(result)
finally:
    # 显式清理资源
    stagehand_tool.close()

命令类型

StagehandTool 支持三种不同的命令类型，适用于特定网页自动化任务：

1. Act 命令

act 命令类型（默认）支持点击按钮、填写表单和导航等网页交互。

# 执行操作（默认行为）
result = stagehand_tool.run(
    instruction="Click the login button",
    url="https://example.com",
    command_type="act"  # 默认值，因此可以省略
)

# 填写表单
result = stagehand_tool.run(
    instruction="Fill the contact form with name 'John Doe', email '[email protected]', and message 'Hello world'",
    url="https://example.com/contact"
)

2. Extract 命令

extract 命令类型用于从网页中提取结构化数据。

# 提取所有产品信息
result = stagehand_tool.run(
    instruction="Extract all product names, prices, and descriptions",
    url="https://example.com/products",
    command_type="extract"
)

# 使用选择器提取特定信息
result = stagehand_tool.run(
    instruction="Extract the main article title and content",
    url="https://example.com/blog/article",
    command_type="extract",
    selector=".article-container"  # 可选 CSS 选择器
)

3. Observe 命令

observe 命令类型用于识别并分析网页元素。

# 查找可交互元素
result = stagehand_tool.run(
    instruction="Find all interactive elements in the navigation menu",
    url="https://example.com",
    command_type="observe"
)

# 识别表单字段
result = stagehand_tool.run(
    instruction="Identify all the input fields in the registration form",
    url="https://example.com/register",
    command_type="observe",
    selector="#registration-form"
)

配置选项

使用以下参数来自定义 StagehandTool 行为：

stagehand_tool = StagehandTool(
    api_key="your-browserbase-api-key",
    project_id="your-browserbase-project-id",
    model_api_key="your-llm-api-key",
    model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST,
    dom_settle_timeout_ms=5000,  # 等待更长时间让 DOM 稳定
    headless=True,  # 以无头模式运行浏览器
    self_heal=True,  # 尝试从错误中恢复
    wait_for_captcha_solves=True,  # 等待验证码解决
    verbose=1,  # 控制日志详细程度（0-3）
)

最佳实践

1. 尽量具体：提供详细指令以获得更好结果
2. 选择合适的命令类型：为任务选择正确的命令类型
3. 使用选择器：利用 CSS 选择器提高准确性
4. 拆分复杂任务：将复杂工作流拆分成多个工具调用
5. 实现错误处理：为潜在问题添加错误处理

故障排查

常见问题与解决方案：

• 会话问题：验证 Browserbase 和 LLM 提供方的 API key
• 找不到元素：为较慢的页面增加 dom_settle_timeout_ms
• 操作失败：先使用 observe 找到正确元素
• 数据不完整：细化指令或提供更具体的选择器

其他资源

关于 CrewAI 集成的问题：

• 加入 Stagehand 的 Slack 社区
• 在 Stagehand 仓库 提交 issue
• 访问 Stagehand 文档