How to Run a Foundry Browser Agent on Playwright Workspaces

Your agent needs to click through a vendor portal that has no API, and nobody wants to maintain a browser fleet for it. The Browser Automation tool in Microsoft Foundry is now generally available and runs the browser for you. This guide connects Foundry Playwright Workspaces to an agent: a workspace, a project connection, a toolbox with a managed MCP (Model Context Protocol) endpoint, and a first browsing task you can watch live. The steps follow the Browser Automation tool docs and the Playwright Workspaces remote MCP reference.

1. Create the workspace and choose an auth type

Create a Playwright Workspace in the Azure portal, then pick how Foundry authenticates to it:

• API key: fine for prototyping. Under Settings > Access Management, enable Playwright Service Access Token, generate a token and copy it immediately, because you can't view it again.
• Project managed identity: the docs call it the recommended default for enterprise workloads when the connection supports it.

Copy the Browser endpoint (it starts with wss://) from the workspace Overview page. Creating the workspace needs Contributor on the resource group, and creating the connection needs Foundry Project Manager.

To give the project managed identity access:

az role assignment create \\
  --assignee-object-id <foundry-project-managed-identity-object-id> \\
  --assignee-principal-type ServicePrincipal \\
  --role "Playwright Workspace Contributor" \\
  --scope <playwright-workspace-resource-id>

Prefer a custom role holding only the Playwright permissions Foundry needs. The built-in role at workspace scope is the fallback, never a wider scope.

2. Connect Foundry Playwright Workspaces with azd

Create the project connection with the Azure Developer CLI:

azd ai connection create my-browser-conn \\
  --kind PlaywrightWorkspace \\
  --target wss://<your-browser-endpoint>.api.playwright.microsoft.com/playwrightworkspaces/browsers \\
  --auth-type api-key \\
  --key "$PLAYWRIGHT_ACCESS_TOKEN"

Paste your own Browser endpoint into --target. --kind PlaywrightWorkspace must be exact PascalCase. For managed identity, choose it as the Auth Type when you add the tool in the Foundry portal (Build > Tools > Create a toolbox > Browser Automation).

3. Publish the toolbox with azd ai toolbox create

A toolbox lets several agents share the tool behind one managed MCP endpoint. Define it in my-toolbox.yaml:

description: Browser Automation toolbox
tools:
  - type: browser_automation
    project_connection_id: my-browser-conn

Then create it:

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

The first version becomes the default, and the command prints a versioned MCP endpoint ending in /toolboxes/my-toolbox/versions/1/mcp?api-version=v1. Lost it? Run azd ai toolbox show my-toolbox --output json.

4. Give the agent a browsing task

Set TOOLBOX_ENDPOINT to the endpoint from step 3 and register it as a remote-tool connection that passes your Entra identity through:

azd ai connection create browser-toolbox-conn \\
  --kind remote-tool \\
  --target "$TOOLBOX_ENDPOINT" \\
  --auth-type user-entra-token \\
  --audience https://ai.azure.com

Then call the Responses API with the toolbox attached as an MCP tool:

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL_DEPLOYMENT_NAME="<your-deployment-name>"
export TOOLBOX_ENDPOINT="<endpoint-printed-by-azd-ai-toolbox-create>"
AGENT_TOKEN=$(az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv)

curl --max-time 300 --request POST \\
  --url "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/responses" \\
  --header "Authorization: Bearer ${AGENT_TOKEN}" \\
  --header "Content-Type: application/json" \\
  --data @- > response.json <<JSON
{
  "model": "${FOUNDRY_MODEL_DEPLOYMENT_NAME}",
  "tool_choice": "required",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Use the Browser Automation tool to visit https://example.com. Read the page and report its title and the visible description paragraph. Base your answer on the browser results, not on prior knowledge."
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "mcp",
      "server_label": "toolbox",
      "server_url": "${TOOLBOX_ENDPOINT}",
      "require_approval": "never",
      "project_connection_id": "browser-toolbox-conn"
    }
  ]
}
JSON

tool_choice: required forces tool use, and the 300-second --max-time covers long browser tasks. Switch require_approval away from never before you point this at anything real.

5. Open Playwright Workspaces Live View

Print the agent's reply:

jq -r '.output[] | select(.type=="message") | .content[].text' response.json

The agent reports a Live View URL at the start of a run, a real-time view of the browser session. Open it to watch navigation and page state. Take control lets a person step in before the agent continues, which is how you handle a login or CAPTCHA the agent shouldn't touch. Treat the URL as sensitive.

6. Verify tool calls with tracing

A confident answer is not proof the browser ran. Open the run's trace in Microsoft Foundry and confirm the browser tool calls happened: navigate, snapshot, close. You can also list the output item types:

jq -r '.output[].type' response.json

Restrict who can read traces, since they can hold prompts and tool-call data.

7. Run it with low privilege

• Give the workspace identity the narrowest role that works, and enable only the browser tools the task needs. The Playwright docs advise leaving browser_evaluate and browser_run_code off by default, because the latter runs arbitrary code in the browser.
• Treat page content as untrusted, since it can carry prompt-injection text, and require human approval for state-changing actions.

Gotchas

• Regions: Australia East, East Asia, East US, Japan East, Switzerland North, West Europe and West US 3, and your model and project region must support the tool too.
• Private website browsing is still in public preview.
• Per the remote MCP docs, an idle browser session is cleaned up after 15 minutes, and a closed or expired session can't be reopened.
• After you rotate the Playwright token, update the key on the project connection or you get authorization errors.
• Sessions run on the workspace resource, so check Playwright Workspaces pricing before you scale.

A browser agent can click things you never intended, so scoped roles, a watched Live View and traces on every call are what make it safe to run in production.