nova-act

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
# If you need to observe current state:
act browser ask "What page am I on?" --session-id work
# If you need a zero-inference jump:
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.