/microsoft-foundry

Tool — Browser Automation (type: browser_automation_preview) — preview

Browser automation backed by an Azure Playwright workspace. Auth is ProjectManagedIdentity; the connection kind is PlaywrightWorkspace. For the toolbox concept, versions, and endpoint, see toolbox.md.

The tool uses the nested shape: a browser_automation_preview: { connection: { project_connection_id: ... } } object under the tool entry (not a top-level connections: array).

🚦 Before creating a toolbox/connection either way, read create-hosted.md → Toolbox creation boundary.

Prerequisite — an Azure Playwright workspace + connection

An Azure Playwright workspace must exist first (create it in the Azure portal / via the Microsoft.AzurePlaywrightService resource provider — workspace creation may be gated in some subscriptions). Then create a PlaywrightWorkspace connection on the project that points at it; the tool references that connection by project_connection_id.

A. Imperative CLI

Steps 1–3 of toolbox.md § The flow. Write the toolbox spec to a file — azd ai toolbox create --from-file takes a path (stdin - is not supported).

# 0. Install the CLI extension (once)
azd extension install azure.ai.toolboxes

# Write the toolbox spec to a file
cat > ba.yaml <<'EOF'
description: browser automation toolbox
tools:
  - type: browser_automation_preview
    name: browser
    browser_automation_preview:
      connection:
        project_connection_id: my-playwright-conn   # the PlaywrightWorkspace connection
EOF

Create a new toolbox (first version auto-promoted):

azd ai toolbox create agent-tools --from-file ba.yaml --project-endpoint "$FOUNDRY_PROJECT_ENDPOINT"

The CLI also accepts a connections: [{ name: my-playwright-conn }] alias, which it expands into the nested tool above — but the raw toolbox API accepts only the tools: shape.

B. Declarative azure.yaml

Declare the toolbox as a host: azure.ai.toolbox service in azure.yaml; azd deploy upserts it (and auto-promotes the new version). Needs only an existing Foundry project (via FOUNDRY_PROJECT_ENDPOINT + AZURE_SUBSCRIPTION_ID in the azd env) — no azd provision, no infra: block. The PlaywrightWorkspace connection must already exist (see prerequisite).

name: my-agent-project
services:
  agent-tools:
    host: azure.ai.toolbox
    tools:
      - type: browser_automation_preview
        name: browser
        browser_automation_preview:
          connection:
            project_connection_id: my-playwright-conn

  # A hosted agent in the same project consumes the toolbox by name
  my-agent:
    host: azure.ai.agent
    uses:
      - agent-tools
    environmentVariables:
      - name: TOOLBOX_NAME
        value: agent-tools

azd deploy agent-tools

Verify & deploy

After creating the toolbox either way, verify its MCP endpoint end-to-end — see test-endpoint.md. Browser automation surfaces as MCP sub-tools under your name prefix (e.g. browser___create_session, joined by three underscores). Calling them needs a working Playwright workspace + connection.

References

• Browser automation tool documentation
• toolbox.md § Supported tool types