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 viacontext.newAgent() / browser.newAgent()). Use the act() method to execute high-level instructions:
How It Works
agent.act() invokes an autonomous AI that:
- Observes the current page state using visual context
- Plans the next action based on your instruction and page content
- Executes browser actions (click, type, navigate, etc.)
- Repeats until the task completes or reaches the
maxCycleslimit - Works across pages: The agent can navigate between different pages and domains to complete the task
Method Signature
Parameters
prompt(string, required) - The high-level task to accomplishoptions(object, required) - Agent configuration
page(Page, required) - The starting page for the agent. The agent may create additional pages as neededmaxCycles(number, optional) - Maximum number of thinking cycles the agent can perform. Each cycle includes observing the page, planning, and executing actions. Default: 30model(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:- 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 usingmaxCycles:
maxCycles:
Multi-Page Capabilities
Unlike single-page actions, agents can navigate across pages and domains to complete tasks:Creating Agents from Context or Browser
While theagent 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
maxCyclesfor 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
maxCyclesif 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
References
- Stably Playwright SDK:
@stablyai/playwright-test - Related: AI Assertions
- Inspiration: Stagehand Agent Documentation