Skip to main content
AI Agent Execute enables autonomous browser automation within your Playwright tests. Unlike atomic actions (click, fill, select), the agent handles complex, multi-step workflows across pages—allowing you to describe a high-level task and let the agent execute it end-to-end.
Why use agents? Agents excel at workflows where the exact path varies: searching, filtering, multi-page forms, checkout flows, and application processes. They complement Playwright’s deterministic approach by providing flexibility when UI paths diverge or evolve.

Installation

The agent API is available through the Stably Playwright test integration:

Basic Usage

The agent is provided as a test fixture (or you can create one via context.newAgent() / browser.newAgent()). Use the act() method to execute high-level instructions:

How It Works

agent.act() invokes an autonomous AI that:
  1. Observes the current page state using visual context
  2. Plans the next action based on your instruction and page content
  3. Executes browser actions (click, type, navigate, etc.)
  4. Repeats until the task completes or reaches the maxCycles limit
  5. Works across pages: The agent can navigate between different pages and domains to complete the task
The agent uses computer-use-capable models to understand web interfaces visually and semantically, similar to how humans browse.

Method Signature

Parameters

  • prompt (string, required) - The high-level task to accomplish
  • options (object, required) - Agent configuration
Options:
  • page (Page, required) - The starting page for the agent. The agent may create additional pages as needed
  • maxCycles (number, optional) - Maximum number of thinking cycles the agent can perform. Each cycle includes observing the page, planning, and executing actions. Default: 30
  • model (string, optional) - AI model to use for agent reasoning. Supported models: anthropic/claude-sonnet-4-5-20250929, google/gemini-2.5-computer-use-preview-10-2025. Default: anthropic/claude-sonnet-4-5-20250929

Common Use Cases

Multi-Step Forms

Agents handle complex, multi-page forms without explicit step-by-step instructions:

Search and Filter Workflows

Let the agent navigate dynamic search results and apply filters:

Cross-Page Navigation

Agents can traverse multiple pages to complete tasks:

Conditional Workflows

Handle branching paths without explicit conditionals:

Set Up / Tear Down

Use agents to automate test setup and cleanup workflows:
This approach is especially useful when:
  • Manual setup involves multiple steps across different pages
  • Setup data varies between test runs (dynamic content, user accounts)
  • You want to reduce test code duplication

Configuration

Control agent behavior using maxCycles:
For complex tasks requiring many steps, increase maxCycles:
Provide detailed instructions in the prompt itself:

Multi-Page Capabilities

Unlike single-page actions, agents can navigate across pages and domains to complete tasks:
The agent tracks context across page navigations and maintains task progress throughout the journey.

Creating Agents from Context or Browser

While the agent fixture is the most convenient way to use agents in tests, you can also create agents manually from a BrowserContext or Browser:
Most tests should use the agent fixture for simplicity. Manual agent creation is useful when you need to operate on multiple Playwright BrowserContexts.

Best Practices

Start on the Right Page

Navigate to a relevant starting point before executing tasks:

Be Specific with Instructions

Provide detailed, unambiguous instructions for better results:

Break Down Very Complex Tasks

For extremely complex workflows, break into sequential agent executions:

Combine with Assertions

Use Playwright assertions to verify agent outcomes:

Troubleshooting

Agent Stops Before Completing Task

Problem: Agent stops before finishing the requested task Solutions:
  • Increase maxCycles for complex workflows (default is 30)
  • Break very complex tasks into smaller sequential executions
  • Ensure the starting page is relevant to reduce wasted navigation cycles

Agent Performs Unexpected Actions

Problem: Agent clicks wrong elements or takes unintended paths Solutions:
  • Make instructions more specific about what to click or avoid
  • Provide domain-specific context in the prompt
  • Start from a more focused page to reduce ambiguity
  • Switch to another model

Task Times Out or Takes Too Long

Problem: Agent execution is slower than expected Solutions:
  • Ensure the starting page is close to the target workflow
  • Reduce the scope of the task or break it into smaller pieces
  • Check network conditions—slow page loads affect agent performance
  • Switch to a faster model (e.g. google/gemini-2.5-computer-use-preview-10-2025)

Task Execution Issues

Problem: Task fails or doesn’t complete as expected Solutions:
  • Check if the UI changed mid-execution (dynamic content, popups)
  • Increase maxCycles if the agent ran out of cycles
  • Review the error message for specific failure points

When to Use Agents

  • Use agent.act() when:
    • The workflow spans multiple pages or domains
    • The exact path varies based on dynamic content
    • You want to describe intent rather than prescribe steps
    • The UI is exploratory (search, browse, filter, compare)
  • Use standard Playwright actions when:
    • The flow is deterministic and well-defined
    • Performance is critical (agents are slower than direct actions)
    • You need precise control over each step
    • The page structure is stable and predictable
Agents complement Playwright’s deterministic approach—use them where flexibility and autonomy provide value.

References