Amazon Nova Act Python SDK

State guardrails allow you to control which URLs the agent can visit. You provide a callback function that receives a GuardrailInputState and returns a GuardrailDecision. If the callback returns GuardrailDecision.BLOCK, the act() method will raise an ActStateGuardrailError.

This is useful for preventing the agent from navigating to unauthorized domains or sensitive pages.

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:
    # This will be blocked if agent tries to visit a blocklisted domain
    nova.act("Navigate to the homepage")

Because this tool controls a real browser with access to your authenticated state (cookies, local storage, etc.), follow these security guidelines:

• API Keys: Never commit keys to source control. Use act browser setup to store them in ~/.act_cli/browser/config.yaml (permissions 0o600).
• JavaScript Execution: The evaluate command can read cookies and modify the DOM. Never run untrusted JavaScript.
• Sensitive Data in Logs: network-log and console-log capture data in memory. While network-log hides Authorization and Cookie headers from output, they remain in process memory. Use export with caution as it bundles sensitive content.
• HTTPS Security: By default, --ignore-https-errors is enabled. For security-sensitive workflows, use --no-ignore-https-errors to enforce strict certificate validation.
• Chrome Arguments: Avoid dangerous flags like --disable-web-security or --no-sandbox unless you fully understand the security implications.

The Workflow class is compatible with multi-threading, but because the @workflow decorator relies on ContextVars (which are thread-specific), you must explicitly propagate the context to new threads.

There are two ways to handle this:

1. Using copy_context(): Capture the current context and use ctx.run() to execute the helper function in the new thread.
2. Manual Injection: Use get_current_workflow() to retrieve the active workflow and pass it directly to the helper function, which then passes it to the NovaAct constructor.

Note: Multi-processing is currently not supported because the Workflow object contains non-pickleable boto3 Session and Client instances.

from contextvars import copy_context
from threading import Thread
from nova_act import NovaAct, workflow, get_current_workflow

# Option 1: Using copy_context (for decorated functions)
@workflow(workflow_definition_name="my-workflow", model_id="nova-act-latest")
def multi_threaded_workflow():
    ctx = copy_context()
    t = Thread(target=ctx.run, args=(multi_threaded_helper,))
    t.start()
    t.join()

# Option 2: Manual injection (using get_current_workflow)
def multi_threaded_helper(workflow):
    with NovaAct(..., workflow=workflow) as nova:
       pass

@workflow(workflow_definition_name="my-workflow", model_id="nova-act-latest")
def multi_threaded_workflow_manual():
    t = Thread(target=multi_threaded_helper, args=(get_current_workflow(),))
    t.start()
    t.join()

Nova Act supports Human-in-the-loop (HITL) to allow human supervision within autonomous workflows. You implement this by extending the HumanInputCallbacksBase class and providing implementations for the required abstract methods. Pass an instance of your class to the human_input_callbacks argument in the NovaAct constructor.

Supported Patterns:

• Human approval: Triggered via the approve method. Used for asynchronous decisions like Approve/Reject or Yes/No. The system captures a screenshot for the reviewer.
• UI takeover: Triggered via the ui_takeover method. Enables real-time human control of the remote browser session (e.g., solving CAPTCHAs) via a live-streaming interface.

from nova_act import NovaAct
from nova_act.tools.human.interface.human_input_callback import (
    ApprovalResponse, HumanInputCallbacksBase, UiTakeoverResponse,
)

class MyHumanInputCallbacks(HumanInputCallbacksBase):
    def approve(self, message: str) -> ApprovalResponse:
        # Implement logic to handle approval
        ...

    def ui_takeover(self, message: str) -> UiTakeoverResponse:
        # Implement logic to handle UI takeover
        ...

with NovaAct(
    starting_page="https://example.com",
    tty=False,
    human_input_callbacks=MyHumanInputCallbacks(),
) as nova:
    # Your workflow here
    pass