Skip to main content
Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.
This article explains how to configure and use the Browser Automation tool with Foundry agents to automate web browsing workflows.
The Browser Automation Tool comes with significant security risks. When you use the Browser Automation Tool, an AI spins up remote browsers sessions to perform actions and can use credentials you explicitly share with the agent, such as to email, financial accounts, social networks, and enterprise systems. The AI agent may make mistakes and may be fooled by malicious data it may encounter on the Internet.You’re responsible for reviewing and testing your applications and implementing your own responsible AI mitigations. By using the Browser Automation Tool, you are acknowledging that you bear responsibility and liability for any use of it and all outcomes. Use judgment in deciding which credentials you provide to your browser sessions. See the Foundry Agent Service transparency note.
Browser Automation Tool (BAT) enables scalable, reliable browser-based automation within Foundry agents. BAT is available as an MCP tool powered by Playwright workspaces as its headless browser infrastructure layer. It integrates seamlessly with modern agentic workflows while providing enterprise-grade security, observability, and extensibility. Browser Automation Tool (BAT) provides a comprehensive platform for browser automation through:
  • Playwright Workspaces (a Generally Available service) as the infrastructure layer
  • Real-time debugging with Live View
  • Take control for human-in-the-loop scenarios
  • Support for private website browsing (Private preview)
  • Built-in observability for reliability and optimization
  • Flexible orchestration layers
The private website feature in Playwright Workspaces is currently available in private preview. Interested users can fill out this form to enroll for the private preview.

​
Usage support

The following table shows SDK and setup support.
Microsoft Foundry supportPython SDKC# SDKJavaScript SDKJava SDKREST APIBasic agent setupStandard agent setup
✔️✔️✔️✔️✔️✔️✔️✔️

​
How it works

The interaction starts when the user sends a query to an agent connected to the Browser Automation tool. For example, “Show me all available yoga classes this week from the following URL <url>.” When the agent receives the request, Foundry Agent Service creates an isolated browser session using your provisioned Playwright workspace. Each session is sandboxed for privacy and security. The browser performs Playwright-driven actions, such as navigating to relevant pages and applying filters or parameters based on user preferences (such as time, location, and instructor). By combining the model with Playwright, the model can parse HTML or XML into DOM documents, make decisions, and perform actions like selecting UI elements, typing, and navigating websites. Exercise caution when using this tool. An example flow is:
  1. A user sends a request to the model that includes a call to the Browser Automation tool with the URL you want to go to.
  2. The Browser Automation tool receives a response from the model. If the response has action items, those items contain suggested actions to make progress toward the specified goal. For example, an action might be a screenshot so the model can assess the current state with an updated screenshot or click with X/Y coordinates indicating where the mouse should be moved.
  3. The Browser Automation tool executes the action in a sandboxed environment.
  4. After executing the action, the Browser Automation tool captures the updated state of the environment as a screenshot.
  5. The tool sends a new request with the updated state, and repeats this loop until the model stops requesting actions or the user decides to stop. The Browser Automation tool supports multi-turn conversations, allowing the user to refine their request and complete form filling and web scraping scenarios.

​
Prerequisites

Before you begin, make sure you have:
  • An Azure subscription. Create one for free.
  • Contributor or Owner role on a resource group.
  • A Foundry project with a configured endpoint.
  • An AI model deployed in your project (for example, gpt-5.4).
  • A Playwright workspace resource.
  • A project connection set up for your Playwright workspace.

​
SDK requirements

For Python examples, install the required packages: 
pip install "azure-ai-projects>=2.0.0"
The .NET SDK is currently in preview. For more information, see the quickstart.

​
Configuration

Get your project endpoint: Open your project in the Foundry portal, and copy the endpoint from the project overview page. The format is https://{account-name}.services.ai.azure.com/api/projects/{project-name}. Connection ID format: Use /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}. You can find this value on the tool’s details page after you connect the Browser Automation tool.

​
Set up Browser Automation

​
Step 1: Create a Playwright workspace

  1. In the Azure portal, create a Playwright Workspace resource.
  2. After the workspace is created, go to Settings > Access Management.
  3. Confirm the Playwright Service Access Token authentication method is enabled.
  4. Select Generate Token, enter a name (for example, foundry-connection), and choose an expiry period.
  5. Copy the token immediately. You can’t view it again after closing the page.
  6. On the workspace Overview page, copy the Browser endpoint (it starts with wss://).
  7. Give the project identity a Contributor role on the Playwright workspace resource, or configure a custom role.

​
Step 2: Connect the Browser Automation tool in Foundry

  1. Go to the Foundry portal and select your project.
  2. Select Build > Tools.
  3. Select Create a toolbox.
  4. Fill in the Name and Description for your toolbox.
  5. Under Tools, click on Add
  6. Select Browser Automation and click Add tool
  7. Enter the required fields
    • Connection name: Unique name for your connection
    • Playwright Workspace: Select the Playwright Workspace resource.
    • Auth Type: Select the authentication type for your connection.
  8. Select Connect.
  9. Click on Publish to save the toolbox
After the toolbox is created, you can view the Project connection ID on the tool’s details page. Use this value as the browser automation connection ID in your code.

​
Code example

After you run a sample, verify the tool was called by using tracing in Microsoft Foundry. For guidance on validating tool invocation, see Best practices for using tools in Microsoft Foundry Agent Service. If you use streaming, you can also look for browser_automation_preview_call events.
  • The .NET SDK is currently in preview. For more information, see the quickstart.
  • This article assumes you already created the Playwright workspace connection. See the prerequisites section.

​
Limitations

  • Trusted sites only: Use this tool only with sites you trust. Avoid pages that prompt for credentials, payments, or other sensitive actions.
  • Page volatility: Web pages can change at any time. Your agent might fail if the page layout, labels, or navigation flows change. Build error handling into your workflows.
  • Complex single-page applications: JavaScript-heavy SPAs with dynamic content might not render correctly.

​
Cost considerations

This tool uses a Playwright workspace resource to run browser sessions. Review the Playwright workspace documentation for pricing and usage details. For guidance on optimizing tool usage, see Best practices for using tools in Microsoft Foundry Agent Service.

​
Troubleshooting

​
The agent doesn’t use the tool

​
Connection or authorization errors

  • Confirm the browser automation connection ID matches the Playwright workspace connection resource ID in your project.
  • Confirm the project identity has access to the Playwright workspace resource.
  • If you recently rotated the Playwright access token, update the Foundry project connection key.

​
Python SDK errors

  • Workspace not found: Verify your project endpoint uses the correct format: https://{account-name}.services.ai.azure.com/api/projects/{project-name}. Don’t use the legacy Azure ML endpoint format.
  • Unexpected keyword argument errors: Ensure you’re using the latest version of azure-ai-projects. Run pip install "azure-ai-projects>=2.0.0" --upgrade to update.
  • Import errors: Install all required packages: pip install "azure-ai-projects>=2.0.0".

​
Requests time out

Browser automation can take longer than typical requests.
  • Increase the client timeout (the C# sample sets a 5-minute timeout).
  • Reduce the scope of your prompt (for example, fewer pages and fewer interactions).

​
Clean up

  • Delete the agent version you created for testing.
  • Revoke or rotate the Playwright access token if you no longer need it.
  • Remove the project connection if it’s no longer required. For more information, see Add a connection in Microsoft Foundry.

​
Example scenarios

  • Form filling: Handles diverse form types with validation, DOM, authentication, compliance, and supporting multi-turn reasoning.
  • Web scraping: Navigates authenticated sites to scrape, compare, and structure data across sources.

​
Transparency note

Review the transparency note when using this tool. The Browser Automation tool is a tool that can perform real-world browser tasks through natural language prompts, enabling automated browsing activities without human intervention. Review the responsible AI considerations when using this tool.

​
Related content