{"id":7454,"library":"nova-act","title":"Amazon Nova Act Python SDK","description":"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.","status":"active","version":"3.3.316.0","language":"en","source_language":"en","source_url":"https://github.com/aws/nova-act","tags":["AI agents","browser automation","AWS","natural language processing","UI automation","playwright"],"install":[{"cmd":"pip install nova-act","lang":"bash","label":"Install SDK"}],"dependencies":[{"reason":"Required for the SDK to run.","package":"python","version":">=3.10","optional":false},{"reason":"Commonly used for structured data extraction with `act_get()` schema definitions.","package":"pydantic","optional":true}],"imports":[{"symbol":"NovaAct","correct":"from nova_act import NovaAct"},{"symbol":"ActError","correct":"from nova_act import ActError"},{"note":"Used for defining schemas for structured data extraction, requires `pip install pydantic`.","symbol":"BaseModel","correct":"from pydantic import BaseModel"}],"quickstart":{"code":"import os\nfrom nova_act import NovaAct\n\n# Ensure your Nova Act API key is set as an environment variable\n# export NOVA_ACT_API_KEY=\"your_api_key\"\napi_key = os.environ.get('NOVA_ACT_API_KEY', '')\n\nif not api_key:\n    print(\"Error: NOVA_ACT_API_KEY environment variable is not set.\")\n    print(\"Please visit nova.amazon.com/act to generate an API key and set it: export NOVA_ACT_API_KEY='your_api_key'\")\nelse:\n    try:\n        with NovaAct(starting_page=\"https://example.com\", api_key=api_key) as nova:\n            print(\"Opening example.com and performing an action...\")\n            nova.act(\"Find the main heading on the page and click it.\")\n            print(\"Action completed.\")\n    except Exception as e:\n        print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade using `pip install --upgrade nova-act`.","message":"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.","severity":"breaking","affected_versions":"<3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Always use environment variables (e.g., `export NOVA_ACT_API_KEY=\"your_api_key\"`) or AWS IAM-based authentication for managing credentials securely.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Divide large tasks into logical, granular `nova.act()` statements, each typically resulting in 3-5 browser actions (e.g., click, type, scroll).","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you are in the correct virtual environment and run `pip install nova-act`.","cause":"The `nova-act` package is not installed in the current Python environment or the environment is not activated.","error":"ModuleNotFoundError: No module named 'nova_act'"},{"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\"`.","cause":"The required `NOVA_ACT_API_KEY` environment variable has not been set or is not accessible in the current shell session.","error":"Error: NOVA_ACT_API_KEY environment variable is not set."},{"fix":"Verify that your IAM policy includes the required `nova-act` permissions for the specific API action being attempted.","cause":"The AWS IAM user or role does not have the necessary permissions to perform the requested Nova Act action.","error":"AccessDeniedException: User: arn:aws:iam::[...] is not authorized to perform: nova-act:ListWorkflowRuns on resource: my-workflow-definition"},{"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`.","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.","error":"Command '[.../.nova-act-env/bin/python', '-m', 'ensurepip', ...]' returned non-zero exit status 1"}]}