nova-act

library3.4.187.0pypypi✓ verified 84d ago

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.

llm-agents aws

pip install nova-act

package ↗homepage ↗

INSTALL

IMPORT

SIG · NOVA-ACT

nova-act

llm-agentspythonv3.4.187.0

Install

32.7s avg

Import

4594ms

Disk

276MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 39.8s

py 3.11

✓ —

✓ 32.95s

py 3.12

✓ —

✓ 28.98s

py 3.13

✓ —

✓ 29.23s

py 3.9

✕ build_error

276MB installed

● package 276MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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`.

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}")

Debug

Known issues

breakingNova 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`.

affects: <3.0.0

gotchaThe 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.

affects: All

gotchaDo 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.

affects: All

gotchaYour 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.

affects: All

gotchaFor 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).

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'nova_act'

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.

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

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

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`.

Upgrade

Version history

3.4.187.0latest on PyPI · released Apr 30, 2026

Audit

Dependencies

pythonrequiredRequired for the SDK to run.

pydanticoptionalCommonly used for structured data extraction with `act_get()` schema definitions.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/nova-act/ ↗

homepagehttps://nova.amazon.com/act ↗