| name | nova-act |
| description | AI-powered browser automation SDK for web scraping, testing, and workflow automation. Use when automating web browsers, extracting data from websites, testing web applications, or building web automation workflows. Supports both API key and AWS credential authentication. |
| license | Apache-2.0 |
| metadata | {"author":"Amazon","displayName":"Amazon Nova Act Browser Automation","keywords":"browser, automation, web, scraping, testing, playwright, selenium, nova, act, aws, amazon, workflow, bot"} |
Onboarding
Official Documentation: Nova Act GitHub README is the source of truth.
Step 1: Authentication Setup
Nova Act supports two authentication methods. You MUST prompt the user for which method they want to use!
- API Key (Quick Start) — Best for development/testing. Generate at https://nova.amazon.com/act?tab=dev_tools, then
export NOVA_ACT_API_KEY="your_key". No decorator needed.
- AWS Credentials + Workflow Definition (Production) — Best for IAM-based access, S3 export. Requires AWS creds +
@workflow decorator. See references/workflow_definitions.md.
Full setup details: references/authentication.md
Step 2: Start Using Nova Act
Route to the right mode:
| User wants to... | Route to |
|---|
| Explore a website interactively | references/browser_cli.md (Option A) |
| Build a coding agent with browser | references/browser_cli.md (Option A) |
| Write a repeatable test script | references/qa_tests.md (Option B) |
| Write a Python automation script | references/qa_tests.md (Option B) + references/data_extraction.md |
| Convert manual tests to automated | references/gherkin_testing.md |
| Understand a codebase via its UI | references/flow_discovery.md |
| Reproduce a bug | references/bug_reproduction.md |
| Iterate on / refine automation prompts | references/workflow_refinement.md |
| Generate mock sites from real site recordings | references/mock_generation.md |
| Deploy to production | references/deployment_cli.md |
Option A: Browser CLI (recommended for exploration and agent tool-use)
pip install 'nova-act[cli]'
act browser execute "Go to https://example.com, find the pricing page, and extract plan names and prices" --session-id work
act browser ask "What page am I on?" --session-id work
act browser goto https://example.com/specific-page --session-id work
Default to execute with a detailed plan. Use individual commands (goto, ask, etc.) for recovery, observation, or zero-inference actions. Pass NovaAct constructor or method args with --nova-arg: e.g. --nova-arg max_steps=5 --nova-arg headless=true. Run any command with --help for all available options.
IMPORTANT: Before running any browser command, ask the user whether they want headed (visible browser) or headless mode, unless they have already specified. Use --headed or --headless accordingly.
⚠️ CRITICAL: NEVER kill Chrome or Chromium processes (e.g., pkill chrome, kill -9 $(pgrep chrome), killall Google Chrome). Nova Act manages its own browser lifecycle. Killing browser processes externally will corrupt session state and break automation. If a browser appears stuck, use act browser sessions to check status, or start a new session.
💡 Localhost HTTPS Testing: When testing against a local HTTPS server (e.g., https://localhost:8443), Chrome will reject self-signed certificates by default. Add --launch-arg=--ignore-certificate-errors --ignore-https-errors to bypass this:
act browser goto https://localhost:8443 --session-id dev --launch-arg=--ignore-certificate-errors --ignore-https-errors
⚠️ Only use --ignore-certificate-errors for localhost development servers. For non-local URLs, valid certificates should be used unless you have a specific reason to bypass validation.
Full command reference: references/browser_cli.md
Option B: Python Script (recommended for repeatable automation)
from nova_act import NovaAct
with NovaAct(starting_page="https://example.com") as nova:
nova.act("click the first link on the page")
result = nova.act_get("What is the page title?")
print(f"Page title: {result.response}")
Full testing guide: references/qa_tests.md
Step 3: Validate Installation
- Python 3.10+:
python --version
- Nova Act SDK:
pip install 'nova-act[cli]' / pip show nova-act
- Google Chrome (Optional):
playwright install chrome
Steering Files
Quickstart: When given a URL to explore or automate, start with references/browser_cli.md.
| File | What It Covers |
|---|
references/browser_cli.md | Browser CLI — commands, sessions, config, page exploration. Default for interactive work and agent tool-use. You MUST read the ENTIRE file — it contains critical CLI best practices, command decision guides, and example transcripts that are essential for correct usage |
references/qa_tests.md | Script writing — QA testing with pytest/unittest, act() vs act_get(), schemas, assertion patterns |
references/deployment_cli.md | Deployment CLI — deploy workflows to AgentCore Runtime on AWS |
references/authentication.md | API key vs IAM, session management |
references/workflow_definitions.md | Workflow definitions with AWS CLI |
references/data_extraction.md | Structured extraction with Pydantic |
references/hitl.md | Human approval and UI takeover patterns |
references/tool_use.md | External tools (@tool decorator, MCP servers) |
references/agentcore_browser.md | Remote browser via AgentCore |
references/playwright_interop.md | Direct Playwright page access, sensitive input, file downloads |
references/session_logs.md | Logs, screenshots, and video recordings |
references/trajectory_analysis.md | Understanding Nova Act trajectories |
references/visual_reporting.md | Visual reporting — post-session markdown reports from steps.yaml, snapshots, and screenshots |
references/gherkin_testing.md | Gherkin testing — .feature file writing, qa-plan compilation, session export → Gherkin conversion |
references/flow_discovery.md | Flow discovery — live app exploration → codebase mapping, developer onboarding docs |
references/bug_reproduction.md | Bug reproduction — reproduce → capture evidence → export → regression test |
references/parallel_sessions.md | Parallel sessions — run multiple browser sessions concurrently with subagents, chunking, session limits |
references/workflow_refinement.md | Workflow refinement — analyze chain-of-thought, identify failure patterns, revise and validate browser automation workflows |
references/mock_generation.md | Mock generation — generate static HTML mock sites from real site trajectories for fast, offline iteration |
This skill uses the Nova Act SDK which is licensed under the Apache-2.0 license.
