A Python SDK for Amazon Nova Act.
Amazon Nova Act is available as a new AWS service to build and manage fleets of reliable AI agents for automating production UI workflows at scale. Nova Act completes repetitive UI workflows in the browser and escalates to a human supervisor when appropriate. You can define workflows by combining the flexibility of natural language with Python code. Start by exploring in the web playground at nova.amazon.com/act, develop and debug in your IDE, deploy to AWS, and monitor your workflows in the AWS Console, all in just a few steps.
(Preview) Nova Act also integrates with external tools through API calls, remote MCP, or agentic frameworks, such as Strands Agents.
⚠️ Important: 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.
Please follow the upgrade instructions below:
```bash
Upgrade to the latest version
pip install --upgrade nova-act
Check your current version
pip show nova-act ```
Note: Nova Act supports English.
Accelerate your development process with the Nova Act extension. The extension automates the setup of your Nova Act development environment and brings the entire agent development experience directly into your IDE, enabling chat-to-script generation, browser session debugging, and step-by-step testing capabilities. For installation instructions and detailed documentation, visit the extension repository or website.
Note: When using the Nova Act Playground and/or choosing Nova Act developer tools with API key authentication, access and use are subject to the nova.amazon.com Terms of Use.
Navigate to https://nova.amazon.com/act and generate an API key.
To save it as an environment variable, execute in the terminal:
export NOVA_ACT_API_KEY="your_api_key"
Note: When choosing developer tools with AWS IAM authentication and/or deploying workflows to the Nova Act AWS service, your AWS Service Terms and/or Customer Agreement (or other agreement governing your use of the AWS Service) apply.
Nova Act also supports authentication using IAM credentials. For details please refer to the Amazon Nova Act User Guide documentation. To use IAM-based credentials use the Workflow constructs (see Worfklows). Please note the SDK will instantiate a default boto session if AWS credentials are already configured in your environment.
pip install nova-act
Alternatively, you can build nova-act. Clone this repo, and then:
pip install .
Nova Act works best with Google Chrome but does not have permission to install this browser. You may skip this step if you already have Google Chrome installed or are fine with using Chromium. Otherwise, you can install Google Chrome by running the following command in the same environment where you installed Nova Act. For more information, visit https://playwright.dev/python/docs/browsers#google-chrome--microsoft-edge.
playwright install chrome
Note: The first time you run NovaAct, it may take 1 to 2 minutes to start. This is because NovaAct needs to install Playwright modules. Subsequent runs will only take a few seconds to start. This functionality can be toggled off by setting the NOVA_ACT_SKIP_PLAYWRIGHT_INSTALL environment variable.
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")
The SDK will (1) open Chrome, (2) perform the task as described in the prompt, and then (3) close Chrome. Details of the run will be printed as console log messages.
Refer to the section Initializing NovaAct to learn about other runtime options that can be passed into NovaAct.
Using interactive Python is a nice way to experiment:
% python
Python 3.10.16 (main, Dec 3 2024, 17:27:57) [Clang 16.0.0 (clang-1600.0.26.4)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> 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")
Please don't interact with the browser when an act() is running because the underlying model will not know what you've changed!
Note: When using interactive mode,
ctrl+xcan exit the agent action leaving the browser intact for anotheract()call.ctrl+cdoes not do this -- it will exit the browser and require aNovaActrestart.
Nova Act provides an async implementation for use with asyncio. Import NovaAct from nova_act.asyncio and use async with and 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("Find flights from Boston to Wolf on Feb 22nd")
asyncio.run(main())
The samples folder contains several examples of using Nova Act to complete various tasks, including:
For more samples showing how to use Nova Act SDK, please refer to this Github repository
The simplest way to use Nova Act to achieve an end-to-end task is by specifying the entire goal, possibly with hints to guide the agent, in one prompt. However, the agent then must take many steps sequentially to achieve the goal, and any issues or nondeterminism along the way can throw the workflow off track. We have found that Nova Act works most reliably when the task can be accomplished in fewer than 30 steps.
Make sure the prompt is direct and spells out exactly what you want Nova Act to do, including what information you want it to return, if any (read more on data extraction here). Aim to completely specify the choices the agent should make and what values it should put in form fields. During your testing, if you see act() going off track, enhance the prompt with hints (e.g. how to use certain UI elements it encounters, how to get to a particular function on the website, or what paths to avoid) — just like you would do with a new team member who might be unfamiliar with the task and the website. If the agent is taking a long winding path or you are unable to get repeated reliability, break the task up into stages and connect these in code.
1. Be direct and succinct in what the agent should do
❌ DON'T
nova.act("Let's see what routes vta offers")
✅ DO
nova.act("Navigate to the routes tab")
❌ DON'T
nova.act_get("I want to go and meet a friend. I should figure out when the Orange Line comes next.")
✅ DO
nova.act_get(f"Find the next departure time for the Orange Line from Government Center after {time}")
2. Provide complete instructions
❌ DON'T
nova.act("book me a hotel that costs less than $100 with the highest star rating")
✅ DO
nova.act(f"book a hotel for two adults in Houston between {startdate} and {enddate} that costs less than $100 per night with the highest star rating. two queen beds preferred but single king also ok. stop when you get to the enter customer details or payment page.")
3. Break up large acts into smaller ones
❌ DON'T
nova.act("book me a hotel that costs less than $100 with the highest star rating then find the closest car rental and get me car there, finally find a lunch spot nearby and book it at 12:30pm")
✅ DO
hotel_address = nova.act_get(f"book a hotel for two adults in Houston between {startdate} and {enddate} that costs less than $100 per night with the highest star rating. two queen beds preferred but single king also ok. return the address of the hotel you booked.").response
nova.act(f“book a restaurant near {hotel_address} at 12:30pm for two people”)
nova.act(f“rent a small sized car between {startdate} and {enddate} from a car rental place near {hotel_address}”)
And if the agent still struggles, break it down:
nova.act(f"search for hotels for two adults in Houston between {startdate} and {enddate}")
nova.act("sort by avg customer review")
hotel_address = nova.act_get("book the first hotel that is $100 or less. prefer two queen beds if there is an option. return the address of the hotel you booked.").response
nova.act(f“book a restaurant near {hotel_address} at 12:30pm on {startdate} for two people”)
nova.act(f“search for car rental places near {hotel_address} and navigate to the closest one’s website”)
nova.act(f“rent a small sized car between {startdate} and {enddate}, pickup time 12pm, drop-off 12pm.”)
A workflow defines your agent's end-to-end task. Workflows are comprised of act() statements and Python code that orchestrate the automation logic.
The nova-act SDK provides a number of convenience wrappers for managing workflows deployed with the NovaAct AWS service. Simply call the CreateWorkflowDefinition API (or use the AWS Console) and get a WorkflowDefinition to get started.
The core type driving workflow coordination with the NovaAct service is Workflow. This class provides a context manager which will handle calling the necessary workflow API operations from the Amazon Nova Act service. It calls CreateWorkflowRun when your run starts and UpdateWorkflowRun with the appropriate status when it finishes. It is provided to the NovaAct client via a constructor argument, so that all called APIs will be associated with the correct workflow + run (CreateSession, CreateAct, InvokeActStep, UpdateAct etc.). See the following example for how to use it:
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("Find flights from Boston to Wolf on Feb 22nd")
if name == "main":
main()
By default, when a Nova Act request times out, the Nova Act SDK will retry it once. This can be overridden by passing in a boto_config object to the Workflow constructor. You can also use this object to override the default 60 second read_timeout. For example, to retry a request 4 times (for a total of 5 attempts) with a 90
$ claude mcp add nova-act \
-- python -m otcore.mcp_server <graph>