### Install Nova Act from Source

Source: https://github.com/aws/nova-act/blob/main/README.md

Install Nova Act by building it from the cloned repository. This is useful for development or when needing the latest unreleased changes.

```bash
pip install .
```

--------------------------------

### Interactive Mode Setup

Source: https://github.com/aws/nova-act/blob/main/README.md

Ideal for experimentation and development. This mode allows for step-by-step interaction with the agent in a Python shell.

```python
>>> 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")
```

--------------------------------

### Check Docker Version

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Verify that Docker is installed and accessible on your system. This is a prerequisite for building and running containers.

```bash
docker --version
```

--------------------------------

### Logging Configuration

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Placeholder for logging setup and configuration utilities within the CLI.

```python
# Logging setup and configuration utilities

```

--------------------------------

### Initialize NovaAct with basic parameters

Source: https://github.com/aws/nova-act/blob/main/README.md

Initializes NovaAct with a starting URL. The `headless` parameter controls whether the browser runs in the background. Ensure `ignore_https_errors=True` is passed if using local file URLs.

```python
nova = NovaAct("https://www.example.com")
# or for local files:
# nova = NovaAct("file://path/to/your/file.html", ignore_https_errors=True)
```

--------------------------------

### Basic Workflow Orchestration with NovaAct

Source: https://github.com/aws/nova-act/blob/main/README.md

Use this snippet to start a new workflow run and interact with the NovaAct service. It sets up the `Workflow` context manager and the `NovaAct` client.

```python
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()
```

--------------------------------

### State File Structure Example

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Illustrates the structure of the workflows.json state file, which stores workflow configurations per AWS account and region.

```json
{
  "workflows": {
    "my-workflow": {
      "name": "my-workflow",
      "directory_path": "/path/to/build/dir/",
      "created_at": "2024-10-30T12:51:39.000Z",
      "workflow_definition_arn": "arn:aws:nova-act:us-east-1:123456789012:workflow-definition/my-workflow",
      "deployments": {
        "agentcore": {
          "deployment_arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my_workflow_abc123",
          "image_uri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/nova-act-cli-default:my-workflow-20241030-125139",
          "image_tag": "my-workflow-20241030-125139"
        }
      },
      "metadata": null,
      "last_image_tag": "my-workflow-20241030-125139"
    }
  },
  "last_updated": "2024-10-30T12:51:39.000Z",
  "version": "1.0"
}
```

--------------------------------

### Install Nova Act Package

Source: https://github.com/aws/nova-act/blob/main/README.md

Install the Nova Act Python package using pip. This is the standard method for adding the library to your project.

```bash
pip install nova-act
```

--------------------------------

### Install Nova Act CLI

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Install the Nova Act CLI package using pip. This command includes the necessary dependencies for CLI functionality.

```bash
pip install "nova-act[cli]"
```

--------------------------------

### Example Workflow Using Environment Variable

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

This Python code demonstrates how to access environment variables passed via the `AC_HANDLER_ENV` payload field.

```python
import os

def main(payload):
    api_key = os.environ.get("NOVA_ACT_API_KEY")
    # Use api_key in your workflow
```

--------------------------------

### Implement URL State Guardrails

Source: https://github.com/aws/nova-act/blob/main/README.md

Control which URLs the agent can access during execution using a callback function. This example blocks specific domains and allows others.

```python
from nova_act import NovaAct, GuardrailDecision, GuardrailInputState
from urllib.parse import urlparse
import fnmatch

def url_guardrail(state: GuardrailInputState) -> GuardrailDecision:
    hostname = urlparse(state.browser_url).hostname
    if not hostname:
        return GuardrailDecision.BLOCK

    # Example URL block-list
    blocked = ["*.blocked-domain.com", "*.another-blocked-domain.com"]
    if any(fnmatch.fnmatch(hostname, pattern) for pattern in blocked):
        return GuardrailDecision.BLOCK

    # Example URL allow-list
    allowed = ["allowed-domain.com", "*.another-allowed-domain.com"]
    if any(fnmatch.fnmatch(hostname, pattern) for pattern in allowed):
        return GuardrailDecision.PASS

    return GuardrailDecision.BLOCK

with NovaAct(starting_page="https://allowed-domain.com", state_guardrail=url_guardrail) as nova:
    # The following will be blocked if agent tries to visit a blocklisted domain or leave one of the allowlisted domains
    nova.act("Navigate to the homepage")
```

--------------------------------

### Install Google Chrome for Playwright

Source: https://github.com/aws/nova-act/blob/main/README.md

Install Google Chrome using Playwright, which is recommended for optimal Nova Act functionality. This step is optional if you have Chrome or prefer Chromium.

```bash
playwright install chrome
```

--------------------------------

### Using NovaAct with Local Default Chrome Browser

Source: https://github.com/aws/nova-act/blob/main/README.md

Configure NovaAct to use your local Chrome browser by specifying the user data directory and disabling cloning. This example demonstrates starting NovaAct, performing an action, and then stopping.

```python
>>> from nova_act import NovaAct, rsync_from_default_user_data
>>> working_user_data_dir = "/Users/$USER/your_choice_of_path"
>>> rsync_from_default_user_data(working_user_data_dir)
>>> nova = NovaAct(use_default_chrome_browser=True, clone_user_data_dir=False, user_data_dir=working_user_data_dir, starting_page="https://nova.amazon.com/act/gym/next-dot/search")
>>> nova.start()
>>> nova.act_get("Find flights from Boston to Wolf on Feb 22nd")
...
>>> nova.stop()
>>> quit()
```

--------------------------------

### Setup Persistent Chromium Profile

Source: https://github.com/aws/nova-act/blob/main/README.md

Instantiates NovaAct with a persistent user data directory and disables cloning for single-machine use. Use this when you want to maintain browser state across sessions.

```python
import os

from nova_act import NovaAct

os.makedirs(user_data_dir, exist_ok=True)

with NovaAct(starting_page="https://nova.amazon.com/act", user_data_dir=user_data_dir, clone_user_data_dir=False) as nova:
    input("Log into your websites, then press enter...")
    # Add your nova.act() statements here.

print(f"User data dir saved to {user_data_dir=}")
```

--------------------------------

### S3 Client Interface

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Client for interacting with the Simple Storage Service (S3). Supports checking bucket existence, getting bucket location, and creating buckets.

```python
class S3Client:
    def __init__(region: str)
    def bucket_exists(bucket_name: str) -> bool
    def get_bucket_location(bucket_name: str) -> str
    def create_bucket(bucket_name: str) -> None
```

--------------------------------

### Check Nova Act SDK Version

Source: https://github.com/aws/nova-act/blob/main/README.md

Check the currently installed version of the Nova Act SDK using pip. This is useful for verifying the upgrade or understanding your current environment.

```bash
pip show nova-act
```

--------------------------------

### Integrate MCP Server Tools with Nova Act

Source: https://github.com/aws/nova-act/blob/main/README.md

Leverage an MCP server to provide tools to Nova Act. This example shows using an AWS documentation MCP client to list and use tools within a NovaAct workflow.

```python
from mcp import StdioServerParameters, stdio_client
from nova_act import NovaAct
from strands.tools.mcp import MCPClient

with MCPClient(
    lambda: stdio_client(
        StdioServerParameters(command="uvx", args=["awslabs.aws-documentation-mcp-server@latest"])
    )
) as aws_docs_client:
    with NovaAct(
        starting_page="https://aws.amazon.com/", tools=aws_docs_client.list_tools_sync(),
    ) as nova:
        print(
            nova.act_get(
                "Use the 'search_documentation' tool to tell me about Amazon Bedrock and how to use it with Python."
                "Ignore the web browser; do not click, scroll, type, etc."
            )
        )
```

--------------------------------

### Configuring Retries and Timeouts for Workflows

Source: https://github.com/aws/nova-act/blob/main/README.md

Customize retry behavior and read timeouts for Nova Act requests by passing a `boto_config` object to the `Workflow` constructor. This example sets up 5 total attempts and a 90-second read timeout.

```python
boto_config = Config(retries={"total_max_attempts": 5, "mode": "standard"}, read_timeout=90)
with Workflow(
    boto_config=boto_config,
    workflow_definition_name="<your-workflow-name>",
    model_id="nova-act-latest"
) as workflow:
```

--------------------------------

### Breaking Down Complex Tasks - Stage 2 (Granular)

Source: https://github.com/aws/nova-act/blob/main/README.md

Further break down a task into very small, distinct `act` calls for maximum reliability. This example shows searching, sorting, booking a hotel, booking a restaurant, and renting a car in separate, sequential steps.

```python
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.”)
```

--------------------------------

### Quick Deploy Workflow

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Automatically creates a workflow for immediate deployment. The generated name includes a timestamp.

```bash
act workflow deploy --source-dir /path/to/code
# Generates name like: workflow-20251130-120945
```

--------------------------------

### Complete Booking Instructions

Source: https://github.com/aws/nova-act/blob/main/README.md

For complex actions like booking, provide all constraints and preferences upfront. Specify details such as number of guests, dates, price limits, and room types to ensure accurate fulfillment.

```python
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.")
```

--------------------------------

### Define Main CLI Entry Point

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Sets up the primary entry point for the Nova Act CLI application, including version information.

```python
@click.group(cls=StyledGroup)
@click.version_option(version=VERSION)
def main() -> None:
    # Nova Act CLI main entry point
    pass
```

--------------------------------

### Initialize NovaAct with advanced parameters

Source: https://github.com/aws/nova-act/blob/main/README.md

Initializes NovaAct with advanced configurations including user data directory, API key, logging, proxy settings, and human input callbacks.

```python
nova = NovaAct(
    starting_page="https://www.example.com",
    headless=True,
    user_data_dir="/path/to/user/data",
    nova_act_api_key="YOUR_API_KEY",
    logs_directory="/path/to/logs",
    record_video=True,
    proxy={
        "server": "http://user:password@proxyserver.com:8080",
        "username": "user",
        "password": "password"
    },
    human_input_callbacks=my_callbacks
)
```

--------------------------------

### AgentCoreDeploymentService.deploy

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Initiates the deployment process using AgentCore.

```APIDOC
## AgentCoreDeploymentService.deploy

### Description
Initiates the deployment process using AgentCore.

### Method
Python SDK Method

### Signature
`deploy() -> AgentCoreDeployment`

### Parameters
None
```

--------------------------------

### Deploy Workflow with Custom Build Directory and Overwrite

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Deploy a workflow using a custom build directory and overwrite existing build artifacts without prompting using the `--overwrite-build-dir` flag.

```bash
act workflow deploy --source-dir /path/to/code --build-dir /tmp/my-build --overwrite-build-dir
```

--------------------------------

### Workflow Deployer Methods

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Provides methods for deploying workflows. `deploy_workflow` takes a DeploymentRequest and returns WorkflowInfo, while `quick_deploy` simplifies deployment from a source path.

```python
    def deploy_workflow(request: DeploymentRequest) -> WorkflowInfo
    def quick_deploy(source_path: str, entry_point: Optional[str] = None, **kwargs) -> WorkflowInfo
```

--------------------------------

### Direct Navigation Prompt

Source: https://github.com/aws/nova-act/blob/main/README.md

Use direct and succinct commands for simple navigation tasks. This ensures the agent understands the immediate action required.

```python
nova.act("Navigate to the routes tab")
```

--------------------------------

### CLI Command: Deploy Workflow

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Implements the command-line interface for deploying a workflow. Accepts various options for source directory, entry point, region, build directory, and build behavior.

```python
@click.command()
@click.option('--name')
@click.option('--source-dir')
@click.option('--entry-point')
@click.option('--region')
@click.option('--build-dir')
@click.option('--force', is_flag=True)
@click.option('--no-build', is_flag=True)
def deploy(name: Optional[str], source_dir: Optional[str], **kwargs) -> None
```

--------------------------------

### Create and Manage NovaAct Workflows (Recommended)

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Use named workflow management for repeated deployments and console visibility. This involves creating, deploying, and running workflows with specified names and source directories.

```bash
# 1. Create workflow configuration
act workflow create --name my-workflow
```

```bash
# 2. Deploy the workflow
act workflow deploy --name my-workflow --source-dir /path/to/project
```

```bash
# 3. Run the deployed workflow
act workflow run --name my-workflow --payload '{"input": "data"}'
```

--------------------------------

### IAM Client Interface

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Client for interacting with the Identity and Access Management (IAM) service. Supports role management operations like getting, creating, attaching policies, and checking existence.

```python
class IAMClient:
    def __init__(region: str)
    def get_role(role_name: str) -> GetRoleResponse
    def create_role(role_name: str, assume_role_policy_document: str, description: str | None = None) -> CreateRoleResponse
    def attach_role_policy(role_name: str, policy_arn: str) -> None
    def role_exists(role_name: str) -> bool
```

--------------------------------

### CLI Command: Show Workflow

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Implements the command-line interface for displaying detailed information about a specific workflow. Requires the workflow name and supports output formatting.

```python
@click.command()
@click.option('--name', required=True)
@click.option('--region')
@click.option('--format', type=click.Choice(['table', 'json']))
def show(name: str, region: Optional[str], format: str) -> None
```

--------------------------------

### Set Environment Variable for Headless Debugging

Source: https://github.com/aws/nova-act/blob/main/README.md

Set this environment variable before starting your Nova Act workflow to enable remote debugging for headless browser sessions. This allows you to inspect the browser's activity.

```bash
export NOVA_ACT_BROWSER_ARGS="--remote-debugging-port=9222"
```

--------------------------------

### AgentCore Build Context Preparation

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Prepares the build context for AgentCore workflows using Docker. Specify workflow details during initialization.

```python
class BuildContextPreparer:
    def __init__(workflow_name: str, project_path: str, entry_point: str)
    def build_workflow_image(build_dir: Optional[str] = None, force: bool = False) -> str
```

--------------------------------

### Programmatic browser control with Playwright Page

Source: https://github.com/aws/nova-act/blob/main/README.md

Access the Playwright Page object directly via `nova.page` to perform programmatic actions like taking screenshots, getting page content, or typing into input fields.

```python
screenshot_bytes = nova.page.screenshot()
dom_string = nova.page.content()
nova.page.keyboard.type("hello")
```

--------------------------------

### Run Workflow with Log Tailing

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Execute a workflow and enable log tailing to view real-time logs during execution using the `--tail-logs` flag.

```bash
act workflow run --name my-workflow --payload '{}' --tail-logs
```

--------------------------------

### Configure AWS CLI

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Set up your AWS credentials and default region. This is a common first step for troubleshooting credential errors.

```bash
aws configure
```

--------------------------------

### Extracting Structured Data with act_get and Pydantic

Source: https://github.com/aws/nova-act/blob/main/README.md

Use act_get with a Pydantic model schema to extract complex structured data from a web page. Ensure a schema is provided for structured responses. This example extracts gravity and average temperature for a planet.

```python
from nova_act import NovaAct
from pydantic import BaseModel

class Measurement(BaseModel):
    value: float
    unit: str

class PlanetData(BaseModel):
    gravity: Measurement
    average_temperature: Measurement

with NovaAct(
        starting_page="https://nova.amazon.com/act/gym/next-dot"
    ) as nova:
        planet = 'Proxima Centauri b'
        result = nova.act_get(
            f"Go to the {planet} page and return the gravity and average temperature.",
            schema=PlanetData.model_json_schema(),
        )

        # Parse the response into the data model
        planet_data = PlanetData.model_validate(result.parsed_response)

        # Do something with the parsed data
        print(f"✓ {planet} data:\n{planet_data.model_dump_json(indent=2)}")
```

--------------------------------

### Theme System Interfaces and Implementations

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Defines the protocol for CLI themes, enumerates available theme names, and provides concrete implementations for default, minimal, and no-styling themes.

```python
class ThemeName(str, Enum):
    DEFAULT = "default"
    MINIMAL = "minimal"
    NONE = "none"
```

```python
class Theme(Protocol):
    enabled: bool
    def apply_info(text: str) -> str
    def apply_success(text: str) -> str
    def apply_error(text: str) -> str
    def apply_warning(text: str) -> str
    def apply_header(text: str) -> str
    def apply_value(text: str) -> str
    def apply_secondary(text: str) -> str
    def apply_command(text: str) -> str
```

```python
class DefaultTheme:
    """Default color theme matching current CLI appearance"""
    enabled: bool = True
    # Implements all Theme protocol methods with colors
```

```python
class MinimalTheme:
    """Minimal theme with reduced colors"""
    enabled: bool = True
    # Implements all Theme protocol methods with minimal styling
```

```python
class NoTheme:
    """No styling theme for automation/scripting"""
    enabled: bool = False
    # Implements all Theme protocol methods returning plain text
```

```python
def get_theme(name: str | ThemeName) -> Theme
```

```python
def set_active_theme(theme_name: ThemeName) -> None
```

```python
def get_active_theme() -> Theme
```

--------------------------------

### Configuration Path Utilities

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Provides functions for generating standard directory and file paths used for CLI configuration and state management.

```python
from pathlib import Path

def get_cli_config_dir() -> Path:
    pass
def get_state_dir() -> Path:
    pass
def get_account_dir(account_id: str) -> Path:
    pass
def get_region_dir(account_id: str, region: str) -> Path:
    pass
def get_state_file_path(account_id: str, region: str) -> Path:
    pass
def get_cli_config_file_path() -> Path:
    pass
```

--------------------------------

### Deploy Workflow with Default S3 Bucket

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Deploy your workflow code. The CLI will automatically create an S3 bucket for artifact storage if one does not exist. The bucket name follows the pattern `nova-act-{account-id}-{region}`.

```bash
act workflow deploy --source-dir /path/to/code
```

--------------------------------

### CLI Output Styling Utilities

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Provides functions for styling output messages in the CLI using Click's styling capabilities.

```python
import click

def success(message: str) -> None:
    pass
def warning(message: str) -> None:
    pass
def error(message: str) -> None:
    pass
def info(message: str) -> None:
    pass
def header(text: str) -> str:
    pass
def value(text: str) -> str:
    pass
def secondary(text: str) -> str:
    pass
def command(text: str) -> str:
    pass
def styled_error_exception(message: str) -> click.ClickException:
    pass

# Note: Now uses theme system via get_active_theme()
# Initializes theme from config or environment via _initialize_theme()
```

--------------------------------

### CLI Command: List Workflows

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Implements the command-line interface for listing all available workflows. Supports specifying the region and output format (table or JSON).

```python
@click.command()
@click.option('--region')
@click.option('--format', type=click.Choice(['table', 'json']))
def list_workflows(region: Optional[str], format: str) -> None
```

--------------------------------

### Deploy Workflow with Custom ECR Repository

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Use the `--ecr-repo` option to specify a custom ECR repository for storing the container image.

```bash
act workflow deploy --ecr-repo 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo
```

--------------------------------

### Skip Building Workflow

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Use the `--no-build` flag to skip the build process and use an existing container image for deployment.

```bash
act workflow deploy --no-build
```

--------------------------------

### CLI Command: Create Workflow

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Implements the command-line interface for creating a new workflow. Requires a name and optionally accepts a region.

```python
@click.command()
@click.option('--name', required=True)
@click.option('--region')
def create(name: str, region: Optional[str]) -> None
```

--------------------------------

### Import Patterns for NovaAct CLI Commands

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/browser/README.md

Illustrates the standard import statements used within NovaAct CLI command files and how subpackages are re-exported.

```python
# In command files
from nova_act.cli.browser.services import SessionManager
from nova_act.cli.browser.services.browser_actions import BrowserActions
from nova_act.cli.browser.utils.session import command_session
from nova_act.cli.browser.types import CommandParams

# commands/__init__.py re-exports from subpackages:
from nova_act.cli.browser.commands.browsing import ask, execute, ...
from nova_act.cli.browser.commands.extraction import diff, evaluate, extract, ...
from nova_act.cli.browser.commands.session import session
from nova_act.cli.browser.commands.setup import doctor, setup
```

--------------------------------

### Configure Proxy for Nova Act

Source: https://github.com/aws/nova-act/blob/main/README.md

Set up proxy configurations for browser sessions when initializing NovaAct. Supports basic and authenticated proxies.

```python
# Basic proxy without authentication
proxy_config = {
    "server": "http://proxy.example.com:8080"
}

# Proxy with authentication
proxy_config = {
    "server": "http://proxy.example.com:8080",
    "username": "myusername",
    "password": "mypassword"
}

nova = NovaAct(
    starting_page="https://example.com",
    proxy=proxy_config
)
```

--------------------------------

### Theme System Interface

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Provides functionalities for managing and applying CLI themes for styling output.

```APIDOC
## Theme System

### Description
Manages CLI themes for styling output, offering different visual styles.

### Functions
- `get_theme(name: str | ThemeName) -> Theme`: Retrieves a theme by its name.
- `set_active_theme(theme_name: ThemeName) -> None`: Sets the active theme for the CLI.
- `get_active_theme() -> Theme`: Returns the currently active theme.

### Types
- `ThemeName`: Enum for predefined theme names (DEFAULT, MINIMAL, NONE).
- `Theme`: Protocol defining the interface for theme objects, including methods for applying different text styles (info, success, error, etc.).
- `DefaultTheme`, `MinimalTheme`, `NoTheme`: Concrete implementations of the `Theme` protocol.
```

--------------------------------

### Deploy Workflow with Specific Profile

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Use the `--profile` option before the subcommand to specify an AWS profile for deployment.

```bash
act workflow --profile <aws_profile_name> deploy --name my-workflow --source-dir /path/to/code
```

--------------------------------

### Workflow Deployer Initialization

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Initializes the WorkflowDeployer with various configuration options for deploying workflows. Supports specifying region, role, workflow details, build options, and S3 bucket information.

```python
class WorkflowDeployer:
    def __init__(
        region: str,
        account_id: Optional[str] = None,
        execution_role_arn: str | None = None,
        workflow_name: str | None = None,
        source_dir: str | None = None,
        entry_point: str | None = None,
        ecr_repo: str | None = None,
        no_build: bool = False,
        skip_entrypoint_validation: bool = False,
        build_dir: str | None = None,
        overwrite_build_dir: bool = False,
        s3_bucket_name: str | None = None,
        skip_s3_creation: bool = False,
    )
```

--------------------------------

### Multi-threading with Workflow Context Manager

Source: https://github.com/aws/nova-act/blob/main/README.md

Demonstrates using the Workflow class in a multi-threaded scenario by passing the workflow object to a helper function. The Workflow class functions as-is for multi-threaded workflows.

```python
from nova_act import NovaAct, Workflow

def multi_threaded_helper(workflow: Workflow):
    with NovaAct(..., workflow=workflow) as nova:
       # nova will have the appropriate workflow run

with Workflow(
    workflow_definition_name="my-workflow",
    model_id="nova-act-latest"
) as workflow:
    t = Thread(target=multi_threaded_helper, args=(workflow,))
    t.start()
    t.join()

```

--------------------------------

### Specific Information Retrieval Prompt

Source: https://github.com/aws/nova-act/blob/main/README.md

When retrieving specific information, provide all necessary details, including context and desired output format. This helps the agent find precise data.

```python
nova.act_get(f"Find the next departure time for the Orange Line from Government Center after {time}")
```

--------------------------------

### Deploy Workflow with Custom S3 Bucket

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Deploy your workflow code and specify a custom S3 bucket name for artifact storage. The bucket must exist and be in the same region as the workflow.

```bash
act workflow deploy --source-dir /path/to/code --s3-bucket-name my-custom-bucket
```

--------------------------------

### Search on a Website

Source: https://github.com/aws/nova-act/blob/main/README.md

Navigate to a URL and perform a search using the 'act' command. If the search button is hard to find, instruct the model to press enter.

```python
nova.go_to_url(website_url)
nova.act("search for cats")
```

```python
nova.act("search for cats. type enter to initiate the search.")
```

--------------------------------

### Deploy Workflow Skipping Entry Point Validation

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Deploy your workflow code while bypassing the automatic validation of the entry point function (e.g., `main()`). Use this if your entry point deviates from the standard pattern.

```bash
act workflow deploy --skip-entrypoint-validation --source-dir /path/to/code
```

--------------------------------

### Manually Create ECR Repository

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Create an ECR repository manually if you are not using the `--ecr-repo` flag or if the CLI fails to create it automatically. This is an alternative to granting broad ECR permissions.

```bash
--ecr-repo
```

--------------------------------

### Add Main Function to Entry Point

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Ensure your workflow's entry point script includes a `main()` function that accepts a `payload` argument. This is required for proper workflow execution unless validation is skipped.

```bash
def main(payload): ...
```

--------------------------------

### Create Workflow with Existing WorkflowDefinition ARN

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Create a new workflow and associate it with an existing `WorkflowDefinition` resource by providing its ARN. Ensure the workflow name matches the name in the ARN.

```bash
act workflow create --name my-workflow \
  --workflow-definition-arn arn:aws:nova-act:us-east-1:123456789012:workflow-definition/my-workflow
```

--------------------------------

### Deploy Workflow with Custom Build Directory

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Specify a custom directory for build artifacts using the `--build-dir` option. This can be used for debugging or reusing build artifacts.

```bash
act workflow deploy --build-dir /tmp/my-build
```

--------------------------------

### Use act() for automated browser actions

Source: https://github.com/aws/nova-act/blob/main/README.md

The `act()` function takes a natural language prompt and actuates on the browser to achieve the goal. Configure `max_steps` to limit the number of actuations and `timeout` for the total duration.

```python
result = nova.act("Find the contact information on the page", max_steps=50, timeout=60)
```

--------------------------------

### Show Workflow

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Displays detailed information about a specific workflow. Output can be formatted as a table or JSON.

```APIDOC
## show

### Description
Shows information about a specific workflow.

### Method
CLI Command

### Endpoint
N/A (CLI Command)

### Parameters
#### Command Line Options
- **--name** (string) - Required - The name of the workflow to show.
- **--region** (string) - Optional - The AWS region to use.
- **--format** (string) - Optional - The output format. Can be 'table' or 'json'.
```

--------------------------------

### User Configuration Manager Interface

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Defines the interface for managing user configurations, including methods to retrieve and save configuration settings.

```python
class UserConfigManager:
    def __init__()
    def get_config() -> UserConfig
    def save_config(config: UserConfig) -> None
```

--------------------------------

### CLI Command: Run Workflow

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Implements the command-line interface for executing a workflow. Supports specifying payload via string or file, and options for log tailing and region.

```python
@click.command()
@click.option('--name', required=True)
@click.option('--payload')
@click.option('--payload-file')
@click.option('--tail-logs', is_flag=True)
@click.option('--region')
def run(name: str, payload: Optional[str], **kwargs) -> None
```

--------------------------------

### Run Workflow with Payload File

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Execute a workflow using a specified JSON payload file. Ensure the payload file exists and is correctly formatted.

```bash
act workflow run --name my-workflow --payload-file payload.json
```

--------------------------------

### Basic Browser Commands

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Execute common browser automation tasks using the 'act browser' command. These commands are useful for quick testing and development of UI workflows.

```bash
act browser execute "Go to amazon.com and search for laptops"
```

```bash
act browser goto https://example.com
```

```bash
act browser ask "What is the main heading?"
```

```bash
act browser extract "Get all product prices"
```

```bash
act browser screenshot --output page.png
```

```bash
act browser query "a.nav-link" --properties "text,href"
```

```bash
act browser doctor
```

--------------------------------

### Allow File Uploads

Source: https://github.com/aws/nova-act/blob/main/README.md

Enable Nova Act to upload files by defining allowed file upload path patterns in SecurityOptions.

```python
from nova_act import NovaAct, SecurityOptions

NovaAct(starting_page="https://example.com", SecurityOptions(allowed_file_upload_paths=['/home/nova-act/shared/*']))
```

--------------------------------

### Named Workflow Deployment

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Deploys a workflow using pre-configured settings specified by a name.

```bash
act workflow deploy --name my-workflow --source-dir /path/to/code
```

--------------------------------

### Quick Deploy Python Scripts with NovaAct CLI

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Deploy Python scripts directly without pre-creating a named workflow. The CLI can deploy a single script file, a directory, or a specific entry point within a directory. A workflow with an auto-generated name is created.

```bash
# Deploy a single script file
act workflow deploy --entry-point /path/to/your/script.py
```

```bash
# Deploy a directory with auto-detected entry point
act workflow deploy --source-dir /path/to/your/project
```

```bash
# Deploy with specific entry point
act workflow deploy --source-dir /path/to/project --entry-point my_script.py
```

```bash
# Run the deployed workflow
# The above commands auto-create a workflow name like: workflow-20251130-120945
act workflow run --name <auto-created-workflow-name> --payload '{"input": "test data"}'
```

--------------------------------

### AgentCoreDeploymentService Class Definition

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Defines the service for orchestrating AgentCore deployments. Instantiate with agent name, execution role ARN, region, and account ID.

```python
class AgentCoreDeploymentService:
    def __init__(agent_name: str, execution_role_arn: str | None, region: str, account_id: str, **kwargs)
    def deploy() -> AgentCoreDeployment
```

--------------------------------

### Using an Existing IAM Role

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Deploys a workflow using a pre-existing IAM role specified by its ARN.

```bash
act workflow deploy ... --execution-role-arn "arn:aws:iam::123456789012:role/MyRole"
```

--------------------------------

### Create NovaAct Workflow Definition using AWS SDK (boto3)

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Programmatically create a workflow definition with S3 export configuration using the AWS SDK for Python (boto3). This sets up a resource for the Nova Act service and does not need to be recreated at runtime.

```python
import boto3

# Create boto3 client for Nova Act workflow management
client = boto3.client('nova-act')

# Create workflow definition with S3 export configuration
response = client.create_workflow_definition(
    name='my-workflow',  # Replace with your workflow name
    exportConfig={
        's3BucketName': 'my-bucket',  # Replace with your S3 bucket
        's3KeyPrefix': 'nova-act-workflows'
    }
)

print(f"Created workflow: {response['name']}")
```

--------------------------------

### Run Workflow with Specific Profile

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Use the `--profile` option before the subcommand to specify an AWS profile for running a workflow.

```bash
act workflow --profile <aws_profile_name> run --name my-workflow --payload '{}'
```

--------------------------------

### View Act Run HTML Trace

Source: https://github.com/aws/nova-act/blob/main/README.md

After an act() finishes, it outputs traces in a self-contained HTML file. The location is printed in the console trace.

```sh
> ** View your act run here: /var/folders/6k/75j3vkvs62z0lrz5bgcwq0gw0000gq/T/tmpk7_23qte_nova_act_logs/15d2a29f-a495-42fb-96c5-0fdd0295d337/act_844b076b-be57-4014-b4d8-6abed1ac7a5e_output.html
```

--------------------------------

### List Workflows

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Lists all available workflows in the specified region. Output can be formatted as a table or JSON.

```APIDOC
## list_workflows

### Description
Lists all available workflows.

### Method
CLI Command

### Endpoint
N/A (CLI Command)

### Parameters
#### Command Line Options
- **--region** (string) - Optional - The AWS region to use.
- **--format** (string) - Optional - The output format. Can be 'table' or 'json'.
```

--------------------------------

### Allow Navigation to Local File URLs

Source: https://github.com/aws/nova-act/blob/main/README.md

Configure Nova Act to allow navigation to local file URLs by specifying allowed file path patterns in SecurityOptions.

```python
from nova_act import NovaAct, SecurityOptions

NovaAct(starting_page="file://home/nova-act/site/index.html", SecurityOptions(allowed_file_open_paths=['/home/nova-act/site/*']))
```

--------------------------------

### Copying Chrome User Data Directory Locally

Source: https://github.com/aws/nova-act/blob/main/README.md

Manually copy the Chrome user data directory using rsync. Ensure to exclude Singleton files.

```bash
rsync -a --exclude="Singleton*" /Users/$USER/Library/Application\ Support/Google/Chrome/ <your choice of location>
```

--------------------------------

### Set CLI Theme in User Config

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Configure CLI theme settings in the `~/.act_cli/config.yml` file. The 'minimal' theme reduces colors for readability.

```yaml
theme:
  name: minimal
  enabled: true
```

--------------------------------

### Create NovaAct Workflow Definition using AWS CLI

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Create a workflow definition with S3 export configuration using the AWS CLI. Ensure your AWS CLI is updated to the latest version.

```bash
aws nova-act create-workflow-definition \
  --name my-workflow \
  --export-config '{ \
    "s3BucketName": "my-bucket", \
    "s3KeyPrefix": "nova-act-workflows" \
  }' \
  --region us-east-1
```

--------------------------------

### Manage Browser Sessions with CLI

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/README.md

Control browser sessions using the act browser commands. Use --session-id for named sessions to manage parallel workflows or default sessions for sequential commands.

```bash
# Default session (reused across commands)
act browser goto https://example.com
act browser execute "Click the login button"
```

```bash
# Named sessions for parallel workflows
act browser goto https://site1.com --session-id session1
act browser goto https://site2.com --session-id session2
```

```bash
# Session lifecycle management
act browser session create --session-id work --starting-page https://example.com
act browser session list
act browser session close --session-id work
act browser session prune --all
```

--------------------------------

### Generic Docker Build Operations

Source: https://github.com/aws/nova-act/blob/main/src/nova_act/cli/CODEBASE.md

Performs generic Docker build operations. Specify the image tag and optionally the build directory and force flag.

```python
class DockerBuilder:
    def __init__(image_tag: str, build_dir: str | None = None, force: bool = False)
    def build(project_path: str, template_dir: Path) -> str
```

--------------------------------

### Persist Browser Session with Local File Provider

Source: https://github.com/aws/nova-act/blob/main/README.md

Saves session state to a local JSON file. Cookies are restored by default. Local storage is restored only if `restore_local_storage=True` is specified.

```python
from nova_act import LocalFileSessionProvider, NovaAct, workflow

@workflow(
    workflow_definition_name=<your-workflow-definition-name>,
    model_id="nova-act-latest",
)
def main():
    provider = LocalFileSessionProvider(profile="my-agent")
    with NovaAct(
        starting_page="https://example.com",
        browser_auth=provider,
    ) as nova:
        result = nova.act_get("Return the page title.")
        print(f"Title: {result.response}")

if __name__ == "__main__":
    main()
```

--------------------------------

### Create a Tool Requiring Direct Browser Control

Source: https://github.com/aws/nova-act/blob/main/README.md

Mark a tool with `requires_unlocked_actuator_context = True` if it needs to interact directly with the browser. The actuator context is automatically re-locked after the tool execution.

```python
from nova_act import NovaAct, tool

@tool
def my_browser_control_tool(message: str) -> str:
    """Tool that needs direct browser access."""
    # ... interact with browser externally
    return "done"

# Mark the tool as requiring unlocked context
my_browser_control_tool.requires_unlocked_actuator_context = True

with NovaAct(starting_page=..., tools=[my_browser_control_tool]) as nova:
    nova.act("Use my_browser_control_tool to do something")
```

--------------------------------

### Export API Key Environment Variable

Source: https://github.com/aws/nova-act/blob/main/README.md

Set your Nova Act API key as an environment variable for authentication. Ensure you replace 'your_api_key' with your actual key.

```sh
export NOVA_ACT_API_KEY="your_api_key"
```