Amazon Nova Act Python SDK

3.3.316.0 · active · verified Thu Apr 16

Amazon Nova Act is a Python SDK for building and deploying highly reliable AI agents that automate browser-based workflows at scale using natural language. It allows developers to define workflows by combining natural language prompts with Python code, integrate external tools using a decorator, and manage fleets of AI agents. The library is actively developed, with the current version being 3.3.316.0, and receives regular updates.

Common errors

```
ModuleNotFoundError: No module named 'nova_act'
```
cause The `nova-act` package is not installed in the current Python environment or the environment is not activated.

fix Ensure you are in the correct virtual environment and run `pip install nova-act`.
```
Error: NOVA_ACT_API_KEY environment variable is not set.
```
cause The required `NOVA_ACT_API_KEY` environment variable has not been set or is not accessible in the current shell session.

fix Generate an API key from `nova.amazon.com/act` and set it in your terminal before running your script: `export NOVA_ACT_API_KEY="your_api_key"`.
```
AccessDeniedException: User: arn:aws:iam::[...] is not authorized to perform: nova-act:ListWorkflowRuns on resource: my-workflow-definition
```
cause The AWS IAM user or role does not have the necessary permissions to perform the requested Nova Act action.

fix Verify that your IAM policy includes the required `nova-act` permissions for the specific API action being attempted.
```
Command '[.../.nova-act-env/bin/python', '-m', 'ensurepip', ...]' returned non-zero exit status 1
```
cause This error can occur when using Python environments installed with `uv` (a fast Python package installer), leading to virtual environment creation errors during Nova Act setup.

fix If encountering this with `uv`, consider using a standard Python installation or another virtual environment tool, or consult `uv` documentation for compatibility with `ensurepip`.

Warnings

breaking Nova Act SDK versions older than 3.0 are no longer supported. Users must upgrade to the latest version to receive security updates and new features.
Fix: Upgrade using `pip install --upgrade nova-act`.
gotcha The first time you run Nova Act, it may take 1-2 minutes to start as it downloads and installs Playwright browser modules. Subsequent runs will be much faster.
Fix: Be patient on the first run. For deployments, consider pre-installing Playwright browsers or setting `NOVA_ACT_SKIP_PLAYWRIGHT_INSTALL` environment variable to manage installation explicitly.
gotcha Do not manually interact with the browser while `nova.act()` is running, as the AI model will not be aware of your manual changes, which can lead to unpredictable behavior.
Fix: Allow the AI agent to complete its task without interference. If interaction is needed, use interactive mode or design workflows to incorporate human input explicitly.
gotcha Your API key grants access to Nova Act under your AWS account. Protect it carefully; do not embed it directly in your code, commit it to version control, or share it.
Fix: Always use environment variables (e.g., `export NOVA_ACT_API_KEY="your_api_key"`) or AWS IAM-based authentication for managing credentials securely.
gotcha For complex or multi-step tasks, it is best practice to break them down into smaller, more specific `act()` calls. Combining too many actions into a single `act()` prompt can reduce reliability and lead to unexpected outcomes.
Fix: Divide large tasks into logical, granular `nova.act()` statements, each typically resulting in 3-5 browser actions (e.g., click, type, scroll).

Install

pip install nova-act Install SDK

Imports

NovaAct
```
from nova_act import NovaAct
```
ActError
```
from nova_act import ActError
```
BaseModel
```
from pydantic import BaseModel
```
Used for defining schemas for structured data extraction, requires `pip install pydantic`.

Quickstart

This quickstart demonstrates how to initialize the `NovaAct` client with an API key, navigate to a starting page, and execute a natural language instruction using `nova.act()`. The `NOVA_ACT_API_KEY` environment variable is required for authentication.

import os
from nova_act import NovaAct

# Ensure your Nova Act API key is set as an environment variable
# export NOVA_ACT_API_KEY="your_api_key"
api_key = os.environ.get('NOVA_ACT_API_KEY', '')

if not api_key:
    print("Error: NOVA_ACT_API_KEY environment variable is not set.")
    print("Please visit nova.amazon.com/act to generate an API key and set it: export NOVA_ACT_API_KEY='your_api_key'")
else:
    try:
        with NovaAct(starting_page="https://example.com", api_key=api_key) as nova:
            print("Opening example.com and performing an action...")
            nova.act("Find the main heading on the page and click it.")
            print("Action completed.")
    except Exception as e:
        print(f"An error occurred: {e}")

view raw JSON →