Nova Act Extension: Build and Test AI Agents Without Leaving Your IDE

The Nova Act extension transforms how you build with Amazon Nova Act by bringing the entire agent development experience directly into IDEs like Visual Studio Code, Kiro, and Cursor. No more switching between tools or losing your train of thought—unify agent development, testing, and debugging into a single IDE environment designed for building reliable AI agents.

Learn more in our blog post or explore Amazon Nova Act.

Nova Act extension demo

Table of Contents

• Key Features
  • Chat-to-Script Generation
  • Step-by-Step Builder
  • Live Debugging
  • Action Viewer
• Requirements
• Getting Started
• IDE Commands
• Chat Commands
• Setting Python Interpreter
• Troubleshooting
• License
• Data Collection
• Support

Key Features

Chat-to-Script Generation: Start With a Conversation

Describe your automation needs in natural language to our @novaAct Copilot Chat participant, and get execution-ready agent scripts in minutes. Instead of starting from scratch with boilerplate code, simply tell the extension what you need.

For instance: "I need an agent that logs into a customer portal, searches for unresolved tickets, and updates their status based on completion criteria." The extension generates a functional script that handles authentication flow, navigation, search functionality, and status updates—giving you a solid foundation to build on.

⚙️ Note: This feature requires GitHub Copilot and may not be availalble in some IDEs. To set it up, see Copilot Quickstart. To configure model access, see Configuring access in GitHub Copilot

Chat-to-Script Generation

Step-by-Step Builder: Build and Test Cell by Cell

Execute your script cell-by-cell with our notebook-style builder. Make a small change without running the entire script again. Focus on specific parts of your workflow—testing different approaches, tweaking parameters, and validating results in real-time.

This modular approach means you can develop incrementally, adding cells, reordering them, and interleaving act() statements with regular Python code to build a robust agent one piece at a time.

Step-by-Step Builder Mode

Iterating in Notebook Cells

When working interactively in a notebook, you can call nova.act() multiple times within the same NovaAct session. Each NovaAct session corresponds to a single browser session.

If you want to start a fresh browser session, you can either:

Call nova.stop() followed by nova.start(), or

Use the notebook’s Restart Notebook button (top right) to tear down the current session and start clean.

💡 Tip: You rarely need to restart unless you want a brand-new browser session. In most workflows, you can call nova.act() multiple times without issue. The main exception is when you Run All Cells — this will attempt to create a second NovaAct instance, which isn’t supported in the Nova Act extension. If that happens, click Restart Notebook to reset.

Live Debugging: Watch Your Agent Think and Act

Bring your code, browser view, and thinking and action logs into a single, cohesive experience within your IDE. Watch your agent execute while simultaneously monitoring its decision-making process—seeing exactly what it sees, why it makes each choice, and where things might go wrong.

Pause execution at any point to make adjustments, then resume testing without starting over. You can even multitask while the agent runs, editing code during execution and re-running cell by cell.

Live Debugging Interface

Action Viewer: Review and Compare Workflow Versions

After your agent completes a run, examine everything that happened at whatever level of detail you need. Select "view your act run" for insights into a single act() statement or "view your session" to analyze the entire end-to-end workflow.

Compare multiple runs side-by-side as you iterate on your scripts. Easily spot improvements or regressions without manually sifting through separate HTML files or log outputs.

Action Viewer for Workflow Analysis

Requirements

• IDE
  • VS Code >= 1.94.0
  • Latest version of Kiro
  • Latest version of Cursor
• Python version >= 3.10
• Operating System: MacOS Sierra+, Ubuntu 22.04+ or Windows 10+
• Sufficient disk space: installing Playwright and its browser dependencies can be large. We recommend at least 2GB of total free disk space for smooth setup

Getting Started

After installation, open the extension to view the welcome page with an interactive walkthrough. You can also access it anytime by running Nova Act: Start Walkthrough from the Command Palette (Cmd+Shift+P / Ctrl+Shift+P).

IDE Commands

The following commands are available in the IDE Command Palette (Cmd+Shift+P / Ctrl+Shift+P).

Chat Commands

Use @novaAct in the IDE chat with these specialized commands:

• /learn - Learn how to use Nova Act for browser automation
  • Sample: @novaAct /learn Teach me about Nova Act
• /shopping - Generate shopping automation workflows
  • Sample: @novaAct /shopping Find the best deals on wireless headphones
• /extract - Extract data from web pages
  • Sample: @novaAct /extract Get the product names and prices from https://example.com search results
• /search - Search and navigate web content
  • Sample: @novaAct /search Look up tutorials on Playwright testing
• /qa - Generate QA test automation scripts
  • Sample: @novaAct /qa Create a login test for the demo site https://example.com
• /formfilling - Automate form filling workflows
  • Sample: @novaAct /formfilling Fill out the signup form on https://example.com/register with test user data

Setting Python Interpreter

The Nova Act extension relies on the Nova Act SDK, which requires Python 3.10 or above. The extension will try to automatically detect a suitable Python interpreter. If a valid Python interpreter cannot be found, you can set it up manually:

VS Code: Follow VS Code Python environment setup to select your Python interpreter.

Kiro / Cursor: Follow the same procedure as VS Code to configure the Python interpreter.

Verify Python Version

You can also check that your Python version is compatible by running:

python --version or python3 --version

Ensure the output shows Python 3.10 or above. If not, install or update Python before proceeding.

Configuration

WebSocket Port

You can customize the WebSocket port used for internal communication through VS Code settings:

1. Open VS Code Settings (Cmd/Ctrl + ,)
2. Search for "Nova Act"
3. Set "Nova Act: Websocket Port" to your desired port (default: 8765)

Alternatively, you can add this to your settings.json:

{
  "novaAct.websocketPort": 8765
}

Note: After changing the port, restart Builder Mode for the changes to take effect.

Troubleshooting

Port Usage

If you get a StartFailed error when running nova.start(), most likely there's a port conflict or you already have a running Nova Act client.

The Nova Act extension uses local ports 9222 (for Chrome DevTools) and 8765 (for internal communication, configurable). If these ports are already in use, Builder Mode may fail to start correctly.

Quick Fix

The Restart Notebook button (top right in Builder Mode) should clear port conflicts automatically and reset your extension state. If this fix does not work for you, proceed with the steps below:

macOS / Linux

lsof -i :9222
lsof -i :8765
kill -9 <PID>

Windows (PowerShell)

netstat -ano | findstr :9222
netstat -ano | findstr :8765
taskkill /PID <PID> /F

License

This project is distributed under the Apache License, Version 2.0

Data Collection

The Nova Act extension uses the telemetry settings you’ve configured in VS Code, Kiro, and Cursor. If enabled, we will collect aggregate telemetry data to help us improve the extension and provide a better experience. You can opt out anytime by managing your settings in VS Code, Kiro, or Cursor.

Support

• 🐛 File a bug
• 🚀 Submit a Feature Request
• 💬 Discussions
• 📖 Documentation

Enjoy automating with Nova Act! 🚀