Nova Act SDK

适用于 Amazon Nova Act 的 Python SDK。

Amazon Nova Act 是一项新的 AWS 服务，用于构建和管理可靠的 AI 代理集群，以大规模自动化生产级 UI 工作流。Nova Act 可在浏览器中完成重复性 UI 工作流，并在适当的时候升级到人工主管处理。您可以通过结合自然语言的灵活性与 Python 代码来定义工作流。只需几个步骤：首先在 nova.amazon.com/act 的 Web 演示环境中探索，在您的 IDE 中开发和调试，部署到 AWS，并在 AWS 控制台中监控您的工作流。

（预览版）Nova Act 还可通过 API 调用、远程 MCP 或代理框架（如 Strands Agents）与外部工具集成。

⚠️ 重要提示：版本低于 3.0 的 Nova Act SDK 已不再受支持。用户必须升级到最新版本才能获得安全更新和新功能。

请按照以下升级说明操作：

# 升级到最新版本
pip install --upgrade nova-act

# 检查当前版本
pip show nova-act

目录

• 先决条件
• Nova Act IDE 扩展
• Nova Act 身份验证与安装
• 快速入门
• 如何向 Nova Act 发出指令
• 工作流
• 从网页中提取信息
• 人工介入流程 (HITL)
• 工具
• 并行运行多个会话
• 身份验证、Cookie 和持久化浏览器状态
• 处理敏感数据
• 验证码
• 在网站上搜索
• 文件上传和下载
• 处理浏览器对话框
• 处理日期
• 设置浏览器用户代理
• 使用代理
• 工时跟踪工具
• 日志记录和查看追踪信息
• 录制会话视频
• 将会话数据存储到 Amazon S3
• 导航页面
• 查看无头模式下的会话
• 将 Nova Act SDK 与 Amazon Bedrock AgentCore 浏览器工具一起使用
• 已知限制
• 披露声明
• 报告 Bug
• 参考：Nova Act 构造函数参数
• 参考：控制浏览器
• 参考：Nova Act CLI

先决条件

1. 操作系统：MacOS Sierra+、Ubuntu 22.04+、WSL2 或 Windows 10+
2. Python 版本：3.10 或更高

注意： Nova Act 支持英语。

设置

使用 IDE 扩展快速设置

借助 Nova Act 扩展，加速您的开发流程。该扩展可自动配置 Nova Act 开发环境，并将完整的代理开发体验直接带入您的 IDE，支持聊天生成脚本、浏览器会话调试以及逐步测试等功能。有关安装说明和详细文档，请访问 扩展仓库 或 官网。

身份验证

API 密钥认证

注意：当您使用 Nova Act Playground 和/或选择使用 API 密钥认证的 Nova Act 开发工具时，访问和使用须遵守 nova.amazon.com 的使用条款。

请前往 https://nova.amazon.com/act 生成 API 密钥。

要将其保存为环境变量，请在终端中执行：

export NOVA_ACT_API_KEY="your_api_key"

基于 IAM 的认证

注意：当您选择使用 AWS IAM 认证的开发工具和/或将工作流部署到 Nova Act AWS 服务时，您的 AWS 服务条款和/或客户协议（或其他管理您使用 AWS 服务的协议）将适用。

Nova Act 也支持使用 IAM 凭证进行身份验证。有关详细信息，请参阅 Amazon 的 Nova Act 用户指南文档。要使用基于 IAM 的凭证，请使用工作流构造（参见 工作流）。请注意，如果您的环境中已配置 AWS 凭证，SDK 将实例化一个默认的 boto 会话。

安装

pip install nova-act

或者，您也可以自行构建 nova-act。克隆此仓库后，执行：

pip install .

【可选】安装 Google Chrome

Nova Act 最适合与 Google Chrome 配合使用，但没有权限自动安装该浏览器。如果您已经安装了 Google Chrome，或者可以接受使用 Chromium 浏览器，则可以跳过此步骤。否则，您可以在安装 Nova Act 的同一环境中运行以下命令来安装 Google Chrome。更多信息请访问 https://playwright.dev/python/docs/browsers#google-chrome--microsoft-edge。

playwright install chrome

快速入门

注：首次运行 NovaAct 时，可能需要 1 到 2 分钟才能启动。这是因为 NovaAct 需要 安装 Playwright 模块。后续运行只需几秒钟即可启动。您可以通过设置 NOVA_ACT_SKIP_PLAYWRIGHT_INSTALL 环境变量来关闭此功能。

脚本模式

from nova_act import NovaAct

with NovaAct(starting_page="https://nova.amazon.com/act/gym/next-dot/search") as nova:
    nova.act("查找2月22日从波士顿飞往沃尔夫的航班")

SDK 将执行以下操作：(1) 打开 Chrome 浏览器，(2) 按照提示完成任务，然后 (3) 关闭 Chrome 浏览器。运行的详细信息将以控制台日志消息的形式输出。

有关可传递给 NovaAct 的其他运行时选项，请参阅【初始化 NovaAct】部分。

交互模式

使用交互式 Python 是一种很好的实验方式：

% python
Python 3.10.16 (main, Dec  3 2024, 17:27:57) [Clang 16.0.0 (clang-1600.0)] on darwin
输入 "help", "copyright", "credits" 或 "license" 以获取更多信息。
>>> from nova_act import NovaAct
>>> nova = NovaAct(starting_page="https://nova.amazon.com/act/gym/next-dot/search")
>>> nova.start()
>>> nova.act("查找2月22日从波士顿飞往沃尔夫的航班")

请注意，当 act() 正在运行时，请勿与浏览器进行交互，因为底层模型将无法感知您的操作！

注意：在使用交互模式时，按下 ctrl+x 可以退出代理操作，同时保持浏览器打开状态以便再次调用 act()。而按下 ctrl+c 则会退出浏览器，并需要重新启动 NovaAct。

异步模式

Nova Act 提供了基于 asyncio 的异步实现。从 nova_act.asyncio 中导入 NovaAct，并使用 async with 和 await：

import asyncio
from nova_act.asyncio import NovaAct

async def main():
    async with NovaAct(starting_page="https://nova.amazon.com/act/gym/next-dot/search") as nova:
        await nova.act("查找2月22日从波士顿飞往沃尔夫的航班")

asyncio.run(main())

示例

samples 文件夹中包含多个使用 Nova Act 完成各种任务的示例，包括：

• 在房地产网站上搜索公寓，利用地图网站计算每个公寓到火车站的距离，并将这些信息整合到一个结果集中。此示例 展示了如何并行运行多个 NovaAct 实例（详情见下文）。
• 使用工具提供的数据预订航班，并返回预订号。此示例 演示了如何将 Python 函数实现为工具，用于向工作流提供数据。
• 允许用户登录电子邮件应用，并批准打印邮件数量。此示例 展示了如何通过 HITL（人工参与）回调实现，将人类纳入工作流中。

更多关于如何使用 Nova Act SDK 的示例，请参阅此 Github 仓库。

如何提示 act()

使用 Nova Act 完成端到端任务最简单的方式，是在一个提示中直接指定整个目标，并可辅以一些引导性提示。然而，代理需要按顺序执行许多步骤才能达成目标，而过程中一旦出现任何问题或不确定性，都可能导致工作流偏离预期。我们发现，当任务能在少于 30 步内完成时，Nova Act 的表现最为稳定。

请确保提示清晰直接，明确说明您希望 Nova Act 执行的具体操作，包括是否需要返回某些信息（有关从网页提取信息的更多信息，请参阅 此处）。尽量完整地指定代理应做出的选择以及应在表单字段中填写的值。在测试过程中，如果发现 act() 运行偏离预期，可以通过添加提示来改进（例如，如何使用遇到的特定 UI 元素、如何到达网站上的某个功能，或应避免哪些路径），这就像指导一位对任务和网站不熟悉的新人一样。如果代理总是绕远路，或者始终无法保证稳定可靠的结果，则可以将任务拆分为多个阶段，并在代码中将它们连接起来。

1. 明确且简洁地描述代理应执行的操作

❌ 不要这样写：

nova.act("让我们看看 VTA 提供了哪些路线")

✅ 应该这样写：

nova.act("导航到‘路线’选项卡")

❌ 不要这样写：

nova.act_get("我想去见朋友。我得查一下橙线什么时候会来下一班。")

✅ 应该这样写：

nova.act_get(f"查找政府中心站之后 {time} 的橙线下一班发车时间")

2. 提供完整的指令

❌ 不要这样写：

nova.act("帮我预订一家价格低于 100 美元且星级最高的酒店")

✅ 应该这样写：

nova.act(f"在休斯敦为两名成人预订一间每晚房价低于 100 美元、星级最高的酒店，入住日期为 {startdate} 至 {enddate}。首选两张大床，但一张特大床也可以。当进入客户信息或支付页面时停止。")

3. 将大型任务拆分为更小的任务

❌ 不要这样写：

nova.act("帮我预订一家价格低于 100 美元且星级最高的酒店，然后找到最近的租车公司并取车，最后在附近找一家午餐店并在 12:30 预订座位")

✅ 应该这样写：

hotel_address = nova.act_get(f"在休斯敦为两名成人预订一间每晚房价低于 100 美元、星级最高的酒店，入住日期为 {startdate} 至 {enddate}。首选两张大床，但一张特大床也可以。预订成功后返回酒店地址。").response
nova.act(f"在 {hotel_address} 附近为两人预订 12:30 的餐厅")
nova.act(f"在 {hotel_address} 附近寻找租车公司，并访问其官网")
nova.act(f"从 {hotel_address} 附近的租车公司租一辆小型汽车，租期为 {startdate} 至 {enddate}, 取车时间为 12:00，还车时间为 12:00。")

如果代理仍然难以完成任务，可以进一步细分：

nova.act(f"在休斯敦为两名成人搜索 {startdate} 至 {enddate} 期间的酒店")
nova.act("按客户平均评分排序")
hotel_address = nova.act_get("预订第一家房价不超过 100 美元的酒店。如果有选择，优先两张大床。预订成功后返回酒店地址。").response
nova.act(f"在 {hotel_address} 附近预订 12:30 的午餐")
nova.act(f"搜索 {hotel_address} 附近的租车公司，并访问最近的一家官网")
nova.act(f"租一辆小型汽车，租期为 {startdate} 至 {enddate}, 取车时间为 12:00，还车时间为 12:00。")

工作流

工作流定义了代理的端到端任务。工作流由 act() 语句和用于编排自动化逻辑的 Python 代码组成。

nova-act SDK 提供了一系列便捷的封装工具，用于管理部署在 NovaAct AWS 服务上的工作流。只需调用 CreateWorkflowDefinition API（或使用 AWS 控制台），即可获取 WorkflowDefinition 并开始使用。

上下文管理器

使用 NovaAct 服务协调工作流的核心类型是 Workflow。该类提供一个 上下文管理器，用于处理对 Amazon Nova Act 服务中必要工作流 API 操作的调用。当您的运行开始时，它会调用 CreateWorkflowRun；当运行结束时，则会以适当的状态调用 UpdateWorkflowRun。此对象通过构造函数参数传递给 NovaAct 客户端，以便所有调用的 API 都能与正确的工作流和运行相关联（例如 CreateSession、CreateAct、InvokeActStep、UpdateAct 等）。以下示例展示了如何使用它：

import os
from nova_act import NovaAct, Workflow

def main():
    with Workflow(
        workflow_definition_name="<your-workflow-name>",
        model_id="nova-act-latest"
    ) as workflow:
        with NovaAct(
            starting_page="https://nova.amazon.com/act/gym/next-dot/search",
            workflow=workflow,
        ) as nova:
            nova.act("查找2月22日从波士顿飞往沃尔夫的航班")

重试处理

默认情况下，当 Nova Act 请求超时时，Nova Act SDK 会重试一次。您可以通过向 Workflow 构造函数传递一个 boto_config 对象来覆盖此行为。您还可以使用该对象来覆盖默认的 60 秒读取超时时间。例如，要将请求重试 4 次（总共 5 次尝试），并设置 90 秒的超时时间：

boto_config = Config(retries={"total_max_attempts": 5, "mode": "standard"}, read_timeout=90)
with Workflow(
    boto_config=boto_config,
    workflow_definition_name="<your-workflow-name>",
    model_id="nova-act-latest"
) as workflow:

请注意，重试相同的 Nova Act 请求可能会导致成本增加，因为请求可能被执行多次。有关重试的更多信息，包括重试模式，请参阅 botocore 重试文档。

装饰器

为方便起见，SDK 还提供了一个 装饰器，可用于标注在给定工作流下运行的函数。该装饰器利用 ContextVars 将正确的 Workflow 对象注入到函数内的每个 NovaAct 实例中；无需再提供 workflow 关键字参数！以下语法提供了与上一示例相同的功能：

from nova_act import NovaAct, workflow

@workflow(
    workflow_definition_name="<your-workflow-name>",
    model_id="nova-act-latest",
)
def main():
    with NovaAct(starting_page="https://nova.amazon.com/act/gym/next-dot/search") as nova:
        nova.act("查找2月22日从波士顿飞往沃尔夫的航班")

使用 boto_session_kwargs 配置 AWS 凭证

Workflow 类接受一个可选的 boto_session_kwargs 参数，用于自定义 boto3 会话的配置。默认情况下，如果未提供此参数，当存在 AWS 凭证时，工作流将使用 {"region_name": "us-east-1"}。

如果您需要自定义 AWS 会话（例如使用特定的配置文件或显式提供凭证），可以将自定义字典传递给 boto_session_kwargs。此方法适用于 上下文管理器 和 装饰器 版本：

使用上下文管理器：

from nova_act import NovaAct, Workflow

def main():
    with Workflow(
        workflow_definition_name="<your-workflow-name>",
        model_id="nova-act-latest",
        boto_session_kwargs={
            "profile_name": "my-aws-profile",
            "region_name": "us-east-1"
        }
    ) as workflow:
        with NovaAct(
            starting_page="https://nova.amazon.com/act/gym/next-dot/search",
            workflow=workflow,
        ) as nova:
            nova.act("查找2月22日从波士顿飞往沃尔夫的航班")

使用装饰器：

from nova_act import NovaAct, workflow

@workflow(
    workflow_definition_name="<your-workflow-name>",
    model_id="nova-act-latest",
    boto_session_kwargs={
        "profile_name": "my-aws-profile",
        "region_name": "us-east-1"
    }
)
def main():
    with NovaAct(starting_page="https://nova.amazon.com/act/gym/next-dot/search") as nova:
        nova.act("查找2月22日从波士顿飞往沃尔夫的航班")

注意： 如果您未提供 boto_session_kwargs 且未使用 API 密钥，工作流将自动使用 boto3 加载 AWS 凭证（有关 boto3 如何加载 AWS 凭证的详细信息，请参阅 此处）。

最佳实践

多线程

Workflow 类可以直接用于多线程工作流。请参阅以下示例：

from nova_act import NovaAct, Workflow

def multi_threaded_helper(workflow: Workflow):
    with NovaAct(..., workflow=workflow) as nova:
       # nova 将运行相应的工作流
 
with Workflow(
    workflow_definition_name="my-workflow",
    model_id="nova-act-latest"
) as workflow:
    t = Thread(target=multi_threaded_helper, args=(workflow,))
    t.start()
    t.join()

由于 @workflow 装饰器利用 ContextVar 来注入上下文，而 ContextVar 本身被设计为线程专属，因此用户需要将上下文传递给那些将在不同于包装函数定义的线程中运行的函数。请参阅以下示例：

from contextvars import copy_context
from nova_act import NovaAct, workflow

def multi_threaded_helper():
    with NovaAct(...) as nova:
       # nova 将运行相应的工作流
 
@workflow(
    workflow_definition_name="my-workflow"
    model_id="nova-act-latest",
)
def multi_threaded_workflow():
    ctx = copy_context()
    t = Thread(target=ctx.run, args=(multi_threaded_helper,))
    t.start()
    t.join()

multi_threaded_workflow()

或者，也可以直接使用 workflow 参数手动注入上下文，就像直接使用 Workflow 类时那样：

from nova_act import NovaAct, get_current_workflow, workflow

def multi_threaded_helper(workflow: Workflow):
    with NovaAct(..., workflow=workflow) as nova:
       # nova 将运行相应的工作流
 
@workflow(
    workflow_definition_name="my-workflow"
    model_id="nova-act-latest",
)
def multi_threaded_workflow():
    t = Thread(target=multi_threaded_helper, args=(get_current_workflow(),))
    t.start()
    t.join()

multi_threaded_workflow()  

多进程

目前，Workflow 构造不支持在多进程之间传递，因为它将 boto3 的 Session 和 Client 作为实例变量保存，而这些对象无法被 pickle 序列化。对此的支持即将推出！

Nova Act CLI

Nova Act CLI 提供了一个简化的命令行界面，用于将 Python 工作流部署到 AWS AgentCore Runtime，并自动处理容器化、ECR 管理、IAM 角色以及多区域部署等工作。有关安装和使用说明，请参阅 Nova Act CLI README。

常用构建模块

从网页中提取信息

使用 pydantic，并让 act_get 根据特定模式对浏览器页面上的问题作出响应。

• 当你期望任何结构化响应时，即使只是布尔值（是/否），也务必使用模式。如果没有提供模式，返回的对象将不会包含响应。
• 将提取信息的提示放在单独的 act() 调用中。

为方便起见，act_get() 函数与 act() 的功能相同，但会提供一个默认的 STRING_SCHEMA，因此无论是否提供特定模式，返回的对象中始终会包含响应。我们建议在所有提取任务中使用 act_get()，以确保类型安全。

示例：

from nova_act import NovaAct
from pydantic import BaseModel

class Measurement(BaseModel):
    value: float
    unit: str

class PlanetData(BaseModel):
    gravity: Measurement
    average_temperature: Measurement

with NovaAct(
        starting_page="https://nova.amazon.com/act/gym/next-dot"
    ) as nova:
        planet = 'Proxima Centauri b'
        result = nova.act_get(
            f"前往 {planet} 页面，返回其重力和平均温度。",
            schema=PlanetData.model_json_schema(),
        )

        # 将响应解析为数据模型
        planet_data = PlanetData.model_validate(result.parsed_response)

        # 对解析后的数据进行处理
        print(f"✓ {planet} 数据：\n{planet_data.model_dump_json(indent=2)}")

如果只需要布尔值响应，可以使用便捷的 BOOL_SCHEMA 常量：

示例：

from nova_act import NovaAct, ActInvalidModelGenerationError, BOOL_SCHEMA
with NovaAct(starting_page="https://nova.amazon.com/act") as nova:
    try:
        result = nova.act_get("我是否已登录？", schema=BOOL_SCHEMA)
    except ActInvalidModelGenerationError as e:
        # act 响应未匹配模式 ¯\_(ツ)_/¯
        print(f"无效结果：{e}")
    else:
        # result.parsed_response 现在是一个布尔值
        if result.parsed_response:
            print("您已登录")
        else:
            print("您未登录")

人机协作（HITL）

Nova Act 的人机协作（HITL）功能可在自动化 Web 工作流中实现无缝的人工监督。HITL 已集成到 Nova Act SDK 中，供您在工作流中实现（并非作为 AWS 托管服务提供）。当您的工作流遇到需要人工判断或干预的场景时，HITL 可以提供工具和用户界面，供监督人员协助、验证或接管流程。

HITL 模式

人工审批

人工审批允许在自动化流程中进行异步的人工决策。当 Nova Act 遇到需要人工判断的决策点时，它会捕获当前页面的截图，并通过基于浏览器的界面呈现给人工审核员。当您需要二元或多项选择决策（批准/拒绝、是/否，或从预定义选项中选择）时，可使用此模式。

UI 接管

UI 接管允许实时控制远程浏览器会话。当 Nova Act 遇到需要人工交互的任务时，它会通过实时流媒体界面将浏览器控制权交给人工操作员。操作员可以使用鼠标和键盘实时与浏览器进行交互。

实现 HITL

请参阅 Amazon Nova Act 用户指南中的 HITL 文档，了解如何在生产工作流中实现 HITL。

使用 SDK 实现 HITL

要在 Nova Act SDK 中实现 HITL 模式，需定义一个继承自 HumanInputCallbacksBase 的类，并实现其两个抽象方法 approve 和 ui_takeover。然后将该类的实例传递给 NovaAct 构造函数的 human_input_callbacks 参数。

• approve：用于触发人工审批模式的回调（例如，审批费用报告或采购申请）。
• ui_takeover：用于触发 UI 接管模式的回调（例如，解决 CAPTCHA 挑战）。

from nova_act import NovaAct, Workflow
from nova_act.tools.human.interface.human_input_callback import (
    ApprovalResponse, HumanInputCallbacksBase, UiTakeoverResponse,
)

class MyHumanInputCallbacks(HumanInputCallbacksBase):
    def approve(self, message: str) -> ApprovalResponse:
        ... 

    def ui_takeover(self, message: str) -> UiTakeoverResponse:
        ...

with NovaAct(
    starting_page=...,
    tty=False,
    human_input_callbacks=MyHumanInputCallbacks(),
) as nova:
    ...
    print(f"任务完成：{result.response}")

有关实际示例，请参阅 此示例。

浏览器之外的工具使用（预览）

（预览）Nova Act 允许您将浏览器之外的外部工具，如 API 调用或数据库查询，集成到工作流中。Nova Act SDK 支持将 Python 函数用作工具，在工作流步骤中调用。要使 Python 函数可用作工具，只需使用 @tool 装饰器对其进行标注。您可以将工具列表传递给 NovaAct 构造函数的 tools 参数。

from nova_act import NovaAct, tool

@tool
def my_tool(str: input) -> str:
   ...

with NovaAct(
    starting_page=...,
    tools=[my_tool],
)

有关实际示例，请参阅 此示例。

用户还可以通过利用 Strands MCP 客户端，从 MCP 服务器提供工具：

from mcp import StdioServerParameters, stdio_client
from nova_act import NovaAct
from strands.tools.mcp import MCPClient

with MCPClient(
    lambda: stdio_client(
        StdioServerParameters(command="uvx", args=["awslabs.aws-documentation-mcp-server@latest"])
    )
) as aws_docs_client:
    with NovaAct(
        starting_page="https://aws.amazon.com/", tools=aws_docs_client.list_tools_sync(),
    ) as nova:
        print(
            nova.act_get(
                "使用 'search_documentation' 工具告诉我关于 Amazon Bedrock 的信息，以及如何用 Python 使用它。
                忽略网页浏览器；不要点击、滚动、输入等。"
            )
        )

进阶：需要浏览器控制的工具

如果您的自定义工具需要直接与浏览器交互（类似于 HITL 工具），可以将其标记为 requires_unlocked_actuator_context = True。这会在工具执行期间暂时暂停执行器的内部钩子，从而允许外部进程控制浏览器。

from nova_act import NovaAct, tool

@tool
def my_browser_control_tool(message: str) -> str:
    """需要直接访问浏览器的工具。"""
    # ... 外部与浏览器交互
    return "完成"

# 将工具标记为需要解锁上下文
my_browser_control_tool.requires_unlocked_actuator_context = True

with NovaAct(starting_page=..., tools=[my_browser_control_tool]) as nova:
    nova.act("使用 my_browser_control_tool 做点什么")

执行器会在下一次代理动作时自动重新锁定上下文。

处理 ActError 错误

一旦 NovaAct 客户端启动，在执行 act() 时可能会遇到错误。所有这些错误类型都包含在 nova_act.types.act_errors 模块中，并按以下类别组织：

1. ActAgentError：表示请求的提示未能完成；用户可以尝试使用不同的请求重试。
   • 示例包括：ActAgentFailed（代理因任务无法完成而引发错误）、ActInvalidModelGenerationError（模型生成了无法解析的输出）或 ActExceededMaxStepsError（act() 未在配置的最大步骤数内完成）。
2. ActExecutionError：表示在执行代理的有效输出时遇到了本地错误。
   • 示例包括：ActActuationError（客户端在驱动浏览器时遇到异常）或 ActCanceledError（用户取消了执行）。
3. ActClientError：表示对 Nova Act 服务的请求无效；用户可以尝试使用不同的请求重试。
   • 示例包括：ActGuardrailsError（请求被我们的 RAI 安全护栏阻止）或 ActRateLimitExceededError（请求被限流；应降低请求频率）。
4. ActServerError：表示 Nova Act 服务在处理请求时遇到了错误。
   • 示例包括：ActInternalServerError（处理请求时发生内部错误）、ActBadResponseError（服务返回了形状无法识别的响应）或 ActServiceUnavailableError（无法连接到服务）。

用户可以捕获 ActAgentError 和 ActClientError 并使用适当的请求重试；对于 ActExecutionError 和 ActServerError，请向团队提交问题以进行调查，包括 (1) 您使用的 SDK 版本、(2) 您的平台和操作系统、(3) 完整的错误堆栈跟踪，以及 (4) 复现步骤。

并行运行多个会话

一个 NovaAct 实例一次只能操作一个浏览器。然而，通过使用多个 NovaAct 实例，可以同时操作多个浏览器！这些实例非常轻量级。你可以利用这一点来并行化任务的某些部分，从而实现一种针对互联网的浏览器“map-reduce”模式。这个示例 展示了如何并行运行多个会话。

身份验证、Cookie 和持久化的浏览器状态

Nova Act 支持通过覆盖其默认设置来处理已身份验证的浏览器会话。默认情况下，当 Nova Act 运行时，它会克隆 Chromium 的用户数据目录，并在运行结束时将其删除。要使用已身份验证的会话，你需要指定一个包含已身份验证会话的现有目录，并禁用克隆功能（这也会禁用对该目录的删除）。

具体步骤如下：

1. （可选）为用户数据目录创建一个新的本地目录，例如 /tmp/user-data-dir。你也可以跳过此步骤，直接使用现有的 Chromium 配置文件。
2. 在实例化 NovaAct 时，通过 user_data_dir 参数指定该目录。
3. 在实例化 NovaAct 时，通过传递参数 clone_user_data_dir=False 来禁用对该目录的克隆。
4. 指示 Nova Act 打开你要进行身份验证的网站。
5. 在这些网站上完成身份验证。有关输入敏感信息的更多信息，请参阅下文的 [输入敏感信息]。
6. 停止你的 Nova Act 会话。

下次你运行 Nova Act 并将 user_data_dir 设置为你在第一步中创建的目录时，你将从一个已身份验证的会话开始。在后续运行中，你可以决定是否启用或禁用克隆功能。如果你正在并行运行多个 NovaAct 实例，则每个实例都需要创建自己的副本，因此在这种情况下必须启用克隆功能（clone_user_data_dir=True）。

以下是一个示例脚本，展示了如何传递这些参数：

import os

from nova_act import NovaAct

os.makedirs(user_data_dir, exist_ok=True)

with NovaAct(starting_page="https://nova.amazon.com/act", user_data_dir=user_data_dir, clone_user_data_dir=False) as nova:
    input("请登录到你的网站，然后按回车键...")
    # 在此处添加你的 nova.act() 语句。

print(f"用户数据目录已保存至 {user_data_dir=}")

该脚本包含在安装包中：python -m nova_act.samples.setup_chrome_user_data_dir。

使用本地默认的 Chrome 浏览器运行

如果你的本地默认 Chrome 浏览器安装了某些扩展程序或安全功能，而这些是你的工作流需要访问的网站所必需的，那么你可以通过以下 NovaAct 参数配置 SDK，使其使用你机器上安装的 Chrome 浏览器，而不是由 SDK 管理的浏览器。

重要提示：

• 此功能目前仅适用于 MacOS。
• 这将退出你当前运行的 Chrome 浏览器，并以新的参数重新启动它。会话结束时，Chrome 将被退出。
• 如果你的 Chrome 浏览器打开了许多标签页，建议在运行自动化之前关闭不必要的标签页，因为重启过程中 Chrome 的性能可能会受到大量打开标签的影响。

在使用此功能启动 Nova Act 之前，你必须将系统 Chrome 用户数据目录中的文件复制到你选择的位置。这是因为 Chrome 不允许通过 CDP 连接到使用系统默认用户数据目录启动的实例。

手动操作可以通过以下命令完成：

rsync -a --exclude="Singleton*" /Users/$USER/Library/Application\ Support/Google/Chrome/ <你选择的位置>

你也可以使用便捷函数 rsync_from_default_user_data(<你选择的位置>) 来在脚本中创建和更新该目录。请注意，调用 rsync_from_default_user_data 会覆盖目标目录中的更改，并使其成为 /Users/$USER/Library/Application\ Support/Google/Chrome/ 的精确镜像，即用源目录中同名的文件覆盖目标目录中的文件，并删除目标目录中不存在的文件。如果你想将 Nova Act 在工作目录中对配置文件所做的更改永久保存回系统默认目录，那么在停止 Nova Act 后，你必须通过自己的实现将这些更改再次同步回系统默认目录。

使用此功能时，必须指定 clone_user_data_dir=False，并将填充好相应文件的工作目录作为 user_data_dir 传入。这是因为在该模式下，NovaAct 不会为你克隆或删除 user_data_dir。

>>> from nova_act import NovaAct, rsync_from_default_user_data
>>> working_user_data_dir = "/Users/$USER/your_choice_of_path"
>>> rsync_from_default_user_data(working_user_data_dir)
>>> nova = NovaAct(use_default_chrome_browser=True, clone_user_data_dir=False, user_data_dir=working_user_data_dir, starting_page="https://nova.amazon.com/act/gym/next-dot/search")
>>> nova.start()
>>> nova.act_get("查找2月22日从波士顿飞往沃尔夫的航班")
...
>>> nova.stop()
>>> quit()

输入敏感信息

要输入密码或其他敏感信息（例如信用卡号和社保号码），不要直接向模型提供这些敏感信息。而是让模型专注于你想要填写的表单元素。然后直接使用 Playwright API 来输入数据，例如 client.page.keyboard.type(sensitive_string)。你可以通过任何你希望的方式获取这些数据：在命令行中使用 getpass 提示输入、通过命令行参数传递，或者设置环境变量。

请注意，在没有系统级密钥环（如 Libsecret 或 KWallet）的 Linux 系统上，任何使用基于 Chromium 的浏览器密码管理器保存的密码或其他敏感数据都会以明文形式存储在用户的配置文件目录中。

注意： 如果你指示 Nova Act 对任何显示敏感信息的浏览器界面执行操作，包括通过 Playwright API 提供的信息，这些信息都将被包含在收集的截图中。

# 登录。
nova.act("输入用户名 janedoe 并点击密码字段")
# 从命令行获取密码并通过 Playwright 输入。（不会通过网络发送。）
nova.page.keyboard.type(getpass())
# 现在用户名和密码已经填写完毕，请求 NovaAct 继续操作。
nova.act("登录")

安全选项

NovaAct 启动时采用安全的默认行为，但根据您的使用场景，您可能希望放宽这些限制。

允许导航到本地 file:// URL

要启用本地文件导航，请在 SecurityOptions.allowed_file_open_paths 中定义一个或多个文件路径模式：

from nova_act import NovaAct, SecurityOptions

NovaAct(starting_page="file://home/nova-act/site/index.html", SecurityOptions(allowed_file_open_paths=['/home/nova-act/site/*']))

允许文件上传

要允许代理将文件上传到网站，请在 SecurityOptions.allowed_file_upload_paths 中定义一个或多个文件路径模式：

from nova_act import NovaAct, SecurityOptions

NovaAct(starting_page="https://example.com", SecurityOptions(allowed_file_upload_paths=['/home/nova-act/shared/*']))

文件路径结构

文件路径参数支持以下格式：

• ["/home/nova-act/shared/*"] - 允许从特定目录访问
• ["/home/nova-act/shared/file.txt"] - 允许访问特定文件路径
• ["*"] - 对所有路径启用
• [] - 禁用该功能（默认）

状态护栏

状态护栏允许您控制代理在执行过程中可以访问的 URL。您可以提供一个回调函数，在每次观察后检查浏览器状态，并决定是否允许继续执行。如果被阻止，act() 将引发 ActStateGuardrailError。这有助于防止代理导航到未经授权的域名或敏感页面。

from nova_act import NovaAct, GuardrailDecision, GuardrailInputState
from urllib.parse import urlparse
import fnmatch

def url_guardrail(state: GuardrailInputState) -> GuardrailDecision:
    hostname = urlparse(state.browser_url).hostname
    if not hostname:
        return GuardrailDecision.BLOCK

    # 示例 URL 阻止列表
    blocked = ["*.blocked-domain.com", "*.another-blocked-domain.com"]
    if any(fnmatch.fnmatch(hostname, pattern) for pattern in blocked):
        return GuardrailDecision.BLOCK

    # 示例 URL 允许列表
    allowed = ["allowed-domain.com", "*.another-allowed-domain.com"]
    if any(fnmatch.fnmatch(hostname, pattern) for pattern in allowed):
        return GuardrailDecision.PASS

    return GuardrailDecision.BLOCK

with NovaAct(starting_page="https://allowed-domain.com", state_guardrail=url_guardrail) as nova:
    # 如果代理尝试访问被列入阻止列表的域名或离开允许列表中的域名，以下操作将被阻止
    nova.act("导航到主页")

验证码

如果您的脚本在某些地方遇到验证码，应使用 ui_takeover 回调函数（参见 HITL），以便将解决验证码的步骤转交给人工处理。

在网站上搜索

nova.go_to_url(website_url)
nova.act("搜索猫")

如果模型难以找到搜索按钮，您可以指示它按下回车键以启动搜索：

nova.act("搜索猫。按回车键启动搜索。")

文件上传和下载

您可以使用 Playwright 下载网页上的文件。

通过下载操作按钮：

# 让 Playwright 捕获任何下载，然后触发页面开始下载。
with nova.page.expect_download() as download_info:
    nova.act("点击下载按钮")

# 可以获取下载的临时路径。
print(f"已下载文件 {download_info.value.path()}")

# 现在将下载的文件永久保存到您选择的位置。
download_info.value.save_as("my_downloaded_file")

重要提示：

• 浏览器会显示文件正在下载到 Playwright 定义的临时路径（参阅文档）
  • 该临时路径可通过 download_info.value.path() 获取
• 使用 download_info.value.save_as() 时：
  • 如果提供了完整路径（例如 /path/to/my_downloaded_file），文件将保存到该路径
  • 如果只提供了文件名（例如 my_downloaded_file），文件将保存到运行 Python 脚本的当前工作目录

要下载当前页面：

1. 如果是 HTML，则通过访问 nova.page.content() 可以获取渲染后的 DOM，您可以将其保存为文件。
2. 如果是其他内容类型，例如 PDF，可以使用 nova.page.request 进行下载：

# 使用 Playwright 的请求下载内容。
response = nova.page.request.get(nova.page.url)
with open("downloaded.pdf", "wb") as f:
    f.write(response.body())

NovaAct 可以原生地使用页面上的相应上传操作上传文件。为此，您首先需要允许 NovaAct 访问要上传的文件，然后指示它按文件名上传：

upload_filename = "/upload_path/upload_me.pdf"

with NovaAct(..., security_options=SecurityOptions(allowed_file_upload_paths=["/upload_path/*"])) as nova:
    nova.act(f"使用上传收据按钮上传 {upload_filename}")

重要的安全提示：

请谨慎选择 allowed_file_upload_paths，以尽量减少 NovaAct 对您文件系统的访问权限，从而避免恶意网站或网络内容窃取数据。

处理浏览器对话框

Playwright 默认会自动关闭浏览器原生对话框，例如 alert、confirm 和 prompt。如需手动处理这些对话框，请在 Nova Act 执行触发对话框的操作之前注册一个对话框处理器。例如：

def handle_dialog(dialog):
    """处理对话框，打印其消息并接受它"""
    print(f"对话框消息：{dialog.message}")
    dialog.accept()  # 接受并关闭对话框
    # dialog.dismiss()  # 或取消/关闭对话框

# 注册处理器
nova.page.on("dialog", handle_dialog)
# 触发对话框
nova.act("做一些会导致对话框出现的事情")
# 取消注册处理器
nova.page.remove_listener("dialog", handle_dialog)

有关详细信息，请参阅 Playwright 文档。

选择日期

以绝对时间指定开始和结束日期效果最佳。

nova.act("选择3月23日至3月28日")

设置浏览器用户代理

Nova Act 配备了 Playwright 的 Chrome 和 Chromium 浏览器。这些浏览器使用 Playwright 设置的默认用户代理。您可以通过 user_agent 选项覆盖此设置：

nova = NovaAct(..., user_agent="MyUserAgent/2.7")

使用代理

Nova Act 支持浏览器会话的代理配置。当您需要通过特定的代理服务器路由流量时，这将非常有用：

# 基本代理，无需身份验证
proxy_config = {
    "server": "http://proxy.example.com:8080"
}

# 带认证的代理
proxy_config = {
    "server": "http://proxy.example.com:8080",
    "username": "myusername",
    "password": "mypassword"
}

nova = NovaAct(
    starting_page="https://example.com",
    proxy=proxy_config
)

注意: 如果连接到 CDP 端点，负责启动浏览器和管理生命周期的代码需要配置代理。这些配置参数仅在 NovaAct 创建并启动浏览器时才适用。

日志记录

默认情况下，NovaAct 会输出所有日志级别为 logging.INFO 或更高的日志信息。可以通过设置环境变量 NOVA_ACT_LOG_LEVEL 来覆盖此行为，该变量应指定一个整数值，对应于 Python 日志级别。

查看 act 跟踪信息

在 act() 执行完成后，它会将所执行的操作以自包含的 HTML 文件形式输出。文件的位置会在控制台日志中打印出来。

> ** 在此处查看您的 act 运行结果：/var/folders/6k/75j3vkvs62z0lrz5bgcwq0gw0000gq/T/tmpk7_23qte_nova_act_logs/15d2a29f-a495-42fb-96c5-0fdd0295d337/act_844b076b-be57-4014-b4d8-6abed1ac7a5e_output.html

您可以通过向 NovaAct 传递 logs_directory 参数来更改此目录。

工作时间跟踪工具

time_worked 工具用于跟踪并报告智能体在任务上花费的大致时间，不包括等待人工输入的时间。这有助于您了解智能体的实际执行时间。

工作原理

大致工作时间使用以下基本公式计算：

time_worked = (end_time - start_time) - human_wait_time

当 act() 调用完成（无论成功还是失败）时，会计算以下内容：

• 大致工作时间：总执行时间（结束时间减去开始时间）减去任何等待人工输入的时间
• 人工等待时间：从发出 approve() 或 ui_takeover() 回调请求到智能体继续执行之间所花费的时间

控制台输出

每次 act() 调用结束时，您都会在控制台以及 JSON 和 HTML 报告中看到工作时间摘要：

没有人工输入时：

⏱️ 大致工作时间：11.8秒

有人工输入时：

⏱️ 大致工作时间：28.3秒（不包括4.5秒的人工等待时间）

重要声明

注意: 工作时间的计算是近似的，可能会因系统计时差异、网络延迟或其他因素而出现误差。此指标应被视为帮助理解智能体执行模式的辅助工具，不应用于正式的时间记录或计费目的。

录制会话

您可以通过设置 logs_directory 并在 NovaAct 构造函数中指定 record_video=True，轻松地在本地录制整个浏览器会话。

将会话数据存储到您的 Amazon S3 存储桶

Nova Act 允许您使用 S3Writer 便捷工具将会话数据（HTML 跟踪、截图等）存储到您自己的 Amazon S3 存储桶中：

import boto3
from nova_act import NovaAct
from nova_act.util.s3_writer import S3Writer

# 使用适当的凭证创建 boto3 会话
boto_session = boto3.Session()

# 创建 S3Writer
s3_writer = S3Writer(
    boto_session=boto_session,
    s3_bucket_name="my-bucket",
    s3_prefix="my-prefix/",  # 可选
    metadata={"Project": "MyProject"}  # 可选
)

# 将 S3Writer 与 NovaAct 结合使用
with NovaAct(
    starting_page="https://nova.amazon.com/act/gym/next-dot/search",
    boto_session=boto_session,  // 您也可以在此处使用 API 密钥代替
    stop_hooks=[s3_writer]
) as nova:
    result = nova.act_get("查找2月22日从波士顿飞往狼城的航班")

S3Writer 需要以下 AWS 权限：

• 对存储桶和前缀的 s3:ListObjects 权限
• 对存储桶和前缀的 s3:PutObject 权限

当 NovaAct 会话结束时，所有会话文件将自动上传到指定的 S3 存储桶，并带有提供的前缀。

S3 上传故障排除

S3 存储桶中没有文件？

• 检查初始化过程中是否有“已注册停止钩子”的日志信息
• 确认您的代码路径确实执行了 NovaAct 上下文管理器

页面导航

请使用 nova.go_to_url 代替 nova.page.goto

Playwright Page 的 goto() 方法默认超时时间为 30 秒，这可能导致加载缓慢的网站出现失败。如果页面在此时间内未加载完毕，goto() 会抛出 TimeoutError，从而可能中断您的工作流程。此外，goto() 并不总是与 act 配合良好，因为 Playwright 可能会在页面完全加载之前就认为页面已就绪。 为了解决这些问题，我们实现了一个新的函数 go_to_url()，它可以提供更可靠的导航。您可以在调用 nova.start() 后，通过 nova.go_to_url(url) 来使用它。您还可以在 NovaAct 初始化时使用 go_to_url_timeout 参数来修改起始页面加载以及后续 go_to_url() 调用的默认最大等待时间（以秒为单位）。

查看以无头模式运行的会话

当浏览器以无头模式运行时（headless: True），您可能需要查看智能体正在执行的工作流程进展。为此：

1. 在启动 Nova Act 工作流之前，设置以下环境变量：

export NOVA_ACT_BROWSER_ARGS="--remote-debugging-port=9222"

2. 按照正常方式启动 Nova Act 工作流，同时保持 headless: True。
3. 打开本地浏览器访问 http://localhost:9222/json。
4. 查找类型为 page 的条目，并将其 devtoolsFrontendUrl 复制粘贴到浏览器中。

现在您将能够观察无头浏览器中的活动。您还可以像平常一样与浏览器窗口进行交互，这对于处理验证码非常有帮助。例如，在您的 Python 脚本中：

1. 让 Nova Act 检查是否存在验证码
2. 如果存在，就让脚本暂停一段时间，然后返回步骤 1。在暂停期间……
3. 发送一封电子邮件或短信提醒（例如使用 Amazon Simple Notification Service），其中包含 devtoolsFrontendUrl，表明需要人工干预
4. 人工用户打开 devtoolsFrontendUrl 并解决验证码
5. 下次运行步骤 1 时，Nova Act 会发现验证码已被解决，脚本将继续执行。

请注意，如果您在远程主机上运行 Nova Act，可能需要设置端口转发才能从其他系统访问。

将 Nova Act SDK 与 Amazon Bedrock AgentCore 浏览器工具结合使用

Nova Act SDK 可以与 Amazon Bedrock AgentCore 浏览器工具 配合使用，实现面向生产的规模化浏览器自动化。AgentCore 浏览器工具提供完全托管的云上浏览器自动化解决方案，解决了实时数据访问方面的限制；而 Nova Act SDK 则赋予您构建复杂智能体工作流的灵活性。 有关集成说明，请参阅这篇博客文章。

注意：当 Nova Act SDK 和 Bedrock AgentCore 浏览器运行在不同操作系统上时（例如，SDK 在 macOS 上，AgentCore 浏览器在 Linux 上），键盘命令可能无法正确跨系统转换。这会影响某些 SDK 函数，如 agent_type()，该函数使用依赖操作系统的键盘快捷键（例如“全选”的 ControlOrMeta+A）。这种行为是跨操作系统集成架构的预期结果，在开发使用键盘输入方法的自动化流程时应予以考虑。

已知限制

我们对 Nova Act 的愿景是提供关键能力，以规模化构建实用的智能体。如果您在使用 Nova Act 时遇到任何限制，请通过 nova-act@amazon.com 向我们反馈，帮助我们不断改进。

例如：

• act() 无法与非浏览器应用程序交互；
• act() 无法与浏览器窗口直接交互。这意味着，诸如请求访问您的位置信息之类的浏览器弹出窗口不会干扰 act() 的执行，但如果需要处理，则必须手动确认；
• 屏幕尺寸限制：
  • Nova Act 针对 864×1296 至 1536×2304 的分辨率进行了优化；超出此范围可能会导致性能下降；
  • 您可以使用 screen_width 和 screen_height 参数调整屏幕尺寸（例如，screen_width=1920, screen_height=1080）。

更多详细信息请参阅 Amazon Nova Act 的 AWS AI 服务卡片。

参考

初始化 NovaAct

构造函数接受以下参数：

• starting_page (str)：起始页面的 URL，支持 Web URL（https://）和本地文件 URL（file://）（必填参数）；
  • 注意：使用文件 URL 时，需在构造函数中传入 ignore_https_errors=True。
• headless (bool)：是否以无头模式启动浏览器（默认为 False）。
• user_data_dir (str)：用户数据目录的路径，用于存储浏览器会话数据，如 Cookie 和本地存储（默认为 None）。
• nova_act_api_key (str)：您生成用于身份验证的 API 密钥；如果未设置 NOVA_ACT_API_KEY 环境变量，则此参数为必填项。若同时提供了环境变量和此参数，则优先使用此参数。
• logs_directory (str)：NovaAct 将输出日志、运行信息以及视频（若 record_video 设置为 True）的目录。
• record_video (bool)：是否录制视频并保存到 logs_directory。必须指定 logs_directory 才能进行视频录制。
• proxy (dict)：浏览器代理配置，应为包含以下字段的字典：
  • server（必填）：代理服务器 URL（必须以 http:// 或 https:// 开头）；
  • username（可选）：代理认证用户名；
  • password（可选）：代理认证密码；
  • 注意：连接到 CDP 端点或使用默认 Chrome 浏览器时不支持代理。
• human_input_callbacks（可选）：人工输入回调的实现。若未提供，则不会触发人工输入请求。
• tools（可选）：客户端提供的工具列表。

此操作将创建一个浏览器会话。您可以根据需要创建任意数量的浏览器会话并并行运行，但每个会话必须是单线程的。

控制浏览器

使用 act

act() 接受用户的自然语言提示，并代表用户在浏览器窗口中执行操作以达成目标。参数：

• max_steps (int)：设置 act() 在放弃任务前最多执行的步骤数。建议使用此参数，以防止智能体因尝试不同路径而无限循环。默认值为 30。
• timeout (int)：整个 act 调用的超时时间（单位：秒）。建议优先使用 max_steps，因为每步所需时间可能因模型服务器负载和网站延迟而异。
• observation_delay_ms：在对页面进行观察之前额外增加的毫秒级延迟。有助于等待 UI 动画完成。

返回一个 ActResult 对象。

class ActResult:
    metadata: ActMetadata

class ActMetadata:
    session_id: str | None
    act_id: str | None
    num_steps_executed: int
    start_time: float
    end_time: float
    prompt: string

如果向 act() 传递了模式（act_get() 函数会便捷地提供默认的 STRING_SCHEMA），则返回的对象将是 ActGetResult，它是 ActResult 的子类，包含原始响应和结构化响应：

class ActGetResult(ActResult):
    response: str | None
    parsed_response: JSONType
    valid_json: bool | None
    matches_schema: bool | None

以编程方式操作

NovaAct 直接通过 page 属性暴露了 Playwright 的 Page 对象。

这可用于获取浏览器的当前状态，例如截屏或 DOM，也可以直接对浏览器进行操作：

screenshot_bytes = nova.page.screenshot()
dom_string = nova.page.content()
nova.page.keyboard.type("hello")

免责声明

注意：在使用 Nova Act Playground 和/或选择采用 API 密钥认证的 Nova Act 开发者工具时，访问和使用须遵守 nova.amazon.com 的《使用条款》。当您选择采用 AWS IAM 认证的 Nova Act 开发者工具，以及/或者将工作流部署至 Nova Act AWS 服务时，则适用您的 AWS 服务条款和/或客户协议（或其他规范您使用 AWS 服务的协议）。

1. Nova Act 并非总是能够正确执行任务。
2. ⚠️ 请注意，Nova Act 在其观察到的第三方网站内容中，可能会遇到命令，这些内容可能来自受信任网站上的用户生成内容，例如社交媒体帖子、搜索结果、论坛评论、新闻文章以及文档附件等。此类未经授权的命令被称为“提示注入”，可能导致模型出现错误，或以与指令不符的方式行事，例如忽略您的指示、执行未授权操作，或泄露敏感数据。为降低提示注入带来的风险，务必对 Nova Act 的行为进行监控并审查其操作，尤其是在处理不可信的用户贡献内容时。
3. 我们建议您不要向 Nova Act 提供敏感信息，例如账户密码。请注意，如果您通过 Playwright 调用传递敏感信息，且该信息在浏览器中清晰可见，那么在 Nova Act 执行相应操作时，这些信息可能会被截图记录下来。（请参阅下方“输入敏感信息”部分。）
4. 当您在 nova.amazon.com/act 上选择使用 API 密钥认证的开发者工具时，我们会收集与 Nova Act 的交互信息，包括浏览器内的截图，用于开发和改进我们的服务。如需删除您的 Nova Act 数据，请发送邮件至 nova-act@amazon.com。
5. 请勿分享您在 https://nova.amazon.com/act 上生成的 API 密钥。任何拥有您 API 密钥的人，均可利用该密钥在您的 Amazon 账户下操作 Nova Act。如果您遗失了 API 密钥，或怀疑他人可能已获取该密钥，请前往 https://nova.amazon.com/act 停用现有密钥并重新获取新的密钥。
6. 如果您使用的是我们的默认浏览环境，请在用户代理字符串中查找“NovaAct”以识别我们的代理。如果您在自己的浏览环境中运行 Nova Act，或自定义了用户代理字符串，我们建议您也包含相同的字符串。

报告问题

帮助我们不断改进！如果您发现任何问题，请通过 nova-act@amazon.com 向我们提交问题报告。

请确保在邮件中包含以下内容：

• 问题描述；
• 会话 ID（已在控制台日志中打印）；以及
• 您正在使用的流程脚本。

您的反馈对我们提升所有用户的体验至关重要。

感谢您试用 Nova Act！

Nova Act 快速上手指南

Nova Act 是亚马逊推出的一项新服务，旨在构建和管理可靠的 AI 代理集群，用于大规模自动化生产环境中的 UI 工作流。它结合自然语言提示与 Python 代码，自动在浏览器中完成重复性任务，并在必要时升级至人工监督。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：
  • macOS Sierra 及以上
  • Ubuntu 22.04 及以上
  • WSL2 或 Windows 10+
• Python 版本：3.10 或更高
• 浏览器：推荐使用 Google Chrome（Nova Act 基于 Playwright，需安装对应浏览器驱动）
• 语言支持：目前主要支持英文指令。

安装步骤

1. 安装 SDK

使用 pip 安装最新版本的 nova-act（注意：3.0 以下版本已不再支持）：

pip install --upgrade nova-act

2. 安装浏览器驱动

Nova Act 依赖 Playwright 运行浏览器。首次运行时会自动安装，也可手动预安装 Google Chrome 以获得最佳体验：

playwright install chrome

提示：若首次运行启动较慢（约 1-2 分钟），是因为正在后台安装 Playwright 模块。后续运行将只需几秒钟。如需跳过自动安装，可设置环境变量 NOVA_ACT_SKIP_PLAYWRIGHT_INSTALL。

3. 配置认证

您需要通过 API Key 或 AWS IAM 进行认证。

方式一：API Key（推荐用于本地开发测试）

1. 访问 https://nova.amazon.com/act 生成 API Key。
2. 在终端中将其设置为环境变量：

export NOVA_ACT_API_KEY="your_api_key"

方式二：AWS IAM（推荐用于部署到 AWS 服务） 确保环境中已配置 AWS 凭证（如 ~/.aws/credentials），SDK 将自动创建默认的 boto session。详细配置请参考 AWS 官方文档。

基本使用

Nova Act 提供三种主要使用模式：脚本模式、交互模式和异步模式。

模式一：脚本模式（推荐）

最简单的方式是使用上下文管理器，任务完成后自动关闭浏览器。

from nova_act import NovaAct

with NovaAct(starting_page="https://nova.amazon.com/act/gym/next-dot/search") as nova:
    nova.act("Find flights from Boston to Wolf on Feb 22nd")

模式二：交互模式

适合在 Python REPL 或 Jupyter Notebook 中逐步调试和实验。

from nova_act import NovaAct

# 初始化并启动
nova = NovaAct(starting_page="https://nova.amazon.com/act/gym/next-dot/search")
nova.start()

# 执行动作
nova.act("Find flights from Boston to Wolf on Feb 22nd")

# 提示：在 act() 运行时请勿手动操作浏览器。
# 按 Ctrl+X 可退出当前动作但保留浏览器状态；按 Ctrl+C 会直接关闭浏览器。

模式三：异步模式

适用于需要并发处理或多个会话的场景。

import asyncio
from nova_act.asyncio import NovaAct

async def main():
    async with NovaAct(starting_page="https://nova.amazon.com/act/gym/next-dot/search") as nova:
        await nova.act("Find flights from Boston to Wolf on Feb 22nd")

asyncio.run(main())

💡 编写高效提示词的技巧

为了让 Agent 更可靠地执行任务，建议遵循以下原则：

1. 指令直接明确：避免模糊表述，直接说明要点击的标签或输入的值。
   • ✅ nova.act("Navigate to the routes tab")
   • ❌ nova.act("Let's see what routes are available")
2. 提供完整细节：包含所有必要参数（如日期、人数、价格限制）。
3. 拆分复杂任务：如果任务步骤超过 30 步，建议拆分为多个小的 act() 调用，并通过代码传递中间结果。