Automatizar tarefas do navegador com a ferramenta de Automação do Navegador (versão prévia)

Importante

Itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou ter recursos restritos. Para obter mais informações, consulte Supplemental Terms of Use for Microsoft Azure Previews.

Este artigo explica como configurar e usar a ferramenta de Automação de Navegador com agentes do Foundry para automatizar fluxos de trabalho de navegação na Web.

Dica

Considere adicionar essa ferramenta usando uma caixa de ferramentas. Usando uma caixa de ferramentas, você pode reutilizar a ferramenta entre agentes e runtimes, bem como centralizar o gerenciamento de credenciais, controle de versão e imposição de política por meio de um ponto de extremidade MCP gerenciado. Consulte o início rápido da caixa de ferramentas.

Aviso

A Ferramenta de Automação do Navegador vem com riscos de segurança significativos. Quando você usa a Ferramenta de Automação do Navegador, uma IA cria sessões de navegadores remotos para executar ações e pode usar credenciais que você compartilha explicitamente com o agente, como email, contas financeiras, redes sociais e sistemas empresariais. O agente de IA pode cometer erros e pode ser enganado por dados mal-intencionados que pode encontrar na Internet.

Você é responsável por revisar e testar seus aplicativos e implementar suas próprias mitigações de IA responsáveis. Ao usar a Ferramenta de Automação do Navegador, você reconhece que assume a responsabilidade e a responsabilização por qualquer uso da ferramenta e por todos os resultados decorrentes. Use o julgamento para decidir quais credenciais você fornece para as sessões do navegador. Consulte a nota de transparência do Foundry Agent Service.

A BAT (Ferramenta de Automação do Navegador) permite automação escalonável e confiável baseada em navegador em agentes do Foundry. O BAT está disponível como uma ferramenta MCP com tecnologia de espaços de trabalho do Playwright, que funcionam como camada de infraestrutura de navegador sem periféricos. Ele se integra perfeitamente aos fluxos de trabalho agente modernos, ao mesmo tempo em que fornece segurança, observabilidade e extensibilidade de nível empresarial.

A BAT (Ferramenta de Automação do Navegador) fornece uma plataforma abrangente para automação de navegador por meio de:

  • Workspaces do dramaturgo (um serviço disponível em geral) como a camada de infraestrutura
  • Depuração em tempo real com visualização ao vivo
  • Tenha controle sobre cenários com humano no circuito
  • Suporte para navegação em sites privados (versão prévia privada)
  • Observabilidade interna para confiabilidade e otimização
  • Camadas de orquestração flexíveis

Nota

O recurso de site privado em Workspaces do dramaturgo está disponível atualmente em versão prévia privada. Os usuários interessados podem preencher esse formulário para se inscrever na visualização privada.

Pré-requisitos

Antes de começar, verifique se você tem:

  • Uma assinatura Azure. Crie um gratuitamente.

  • Função de usuário do Foundry no projeto Foundry para o desenvolvimento e uso diário de agentes.

    Importante

    As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

  • Função Gerente de Projeto Foundry no projeto do Foundry se você criar a conexão do projeto.

  • Função Colaborador no grupo de recursos de destino somente enquanto você cria o workspace do Playwright. Essa função é necessária para o provisionamento de recursos. Ative-o bem a tempo por meio de Microsoft Entra Privileged Identity Management (PIM) e desative-o após o provisionamento. Os desenvolvedores do agente diário e os usuários de runtime não precisam dessa função.

  • Um projeto Foundry com um endpoint configurado.

  • Um modelo de IA implantado em seu projeto (por exemplo, gpt-5.4). Confirme se o modelo e a região do projeto dão suporte à Automação do Navegador na Ferramenta com suporte por região e modelo.

  • Um recurso de workspace do Dramaturgo.

  • Uma conexão de projeto configurada para o workspace do Playwright.

Requisitos do SDK

Para Python exemplos, instale os pacotes necessários:

pip install "azure-ai-projects>=2.0.0"

O SDK do .NET está atualmente em versão prévia. Para obter mais informações, consulte o início rápido.

Configuração

Obtenha o ponto de extremidade do projeto: abra seu projeto no portal do Foundry e copie o ponto de extremidade da página de visão geral do projeto. O formato é https://{account-name}.services.ai.azure.com/api/projects/{project-name}.

Formato do ID de Conexão: use /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}. Você pode encontrar esse valor na página de detalhes da ferramenta depois de conectar a ferramenta de Automação do Navegador.

Suporte ao uso

A tabela a seguir mostra o SDK e o suporte à instalação.

Suporte ao Microsoft Foundry SDK do Python C# SDK SDK para JavaScript SDK do Java API REST Configuração básica do agente Configuração do agente padrão
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Como funciona

A interação começa quando o usuário envia uma consulta para um agente conectado à ferramenta de Automação do Navegador. Por exemplo, "Mostre-me todas as aulas de yoga disponíveis esta semana a partir do URL <>a seguir." Quando o agente recebe a solicitação, o Serviço do Agente do Foundry cria uma sessão isolada do navegador usando o workspace do Playwright provisionado. Cada sessão é isolada para privacidade e segurança.

O navegador executa ações orientadas pelo Dramaturgo, como navegar até páginas relevantes e aplicar filtros ou parâmetros com base nas preferências do usuário (como hora, localização e instrutor). Combinando o modelo com o Dramaturgo, o modelo pode analisar HTML ou XML em documentos DOM, tomar decisões e executar ações como selecionar elementos de interface do usuário, digitar e navegar em sites. Tenha cuidado ao usar essa ferramenta.

Um exemplo de fluxo é:

  1. Um usuário envia uma solicitação para o modelo que inclui uma chamada para a ferramenta de Automação de Navegador com a URL para a qual você deseja ir.
  2. A ferramenta de Automação do Navegador recebe uma resposta do modelo. Se a resposta tiver itens de ação, esses itens conterão ações sugeridas para avançar em direção à meta especificada. Por exemplo, uma ação pode ser uma captura de tela para que o modelo possa avaliar o estado atual com uma captura de tela atualizada ou clicar com coordenadas X/Y indicando para onde o mouse deve ser movido.
  3. A ferramenta de Automação do Navegador executa a ação em um ambiente em área restrita.
  4. Depois de executar a ação, a ferramenta de Automação do Navegador captura o estado atualizado do ambiente como uma captura de tela.
  5. A ferramenta envia uma nova solicitação com o estado atualizado e repete esse loop até que o modelo pare de solicitar ações ou o usuário decida parar.

A ferramenta de automação do navegador dá suporte a conversas com várias rodadas, permitindo que o usuário refine sua solicitação e conclua os cenários de preenchimento de formulário e de extração da Web.

Configurar a Automação do Navegador

Criar um espaço de trabalho do Playwright

  1. No portal Azure, crie um recurso Playwright Workspace.
  2. Depois que o workspace for criado, vá para Configurações>Gerenciamento de Acesso.
  3. Confirme se o método de autenticação do Token de Acesso do Serviço Playwright está habilitado.
  4. Selecione Gerar Token, insira um nome (por exemplo foundry-connection) e escolha um período de expiração.
  5. Copie o token imediatamente. Não é possível exibi-lo novamente depois de fechar a página.
  6. Armazene o token somente na conexão do projeto Foundry. Não o coloque no código-fonte, em comandos ou nos logs do aplicativo. Alterne a função antes que ela expire e revogue-a imediatamente se ela for exposta.
  7. Na página Visão geral do workspace, copie o ponto de extremidade do navegador (ele começa com wss://).
  8. Configure uma função personalizada com apenas as permissões de Dramaturgo necessárias para a identidade do projeto Foundry. Se uma função personalizada não estiver disponível, atribua a função Colaborador somente no escopo do recurso do workspace do Playwright. O token de acesso ao serviço é armazenado na conexão do projeto; a atribuição da função autoriza separadamente a identidade do projeto a acessar o recurso do workspace.

Conectar a ferramenta de Automação do Navegador na Foundry

  1. Vá para o portal do Foundry e selecione seu projeto.
  2. Selecione Ferramentas>de Build.
  3. Selecione Criar uma caixa de ferramentas.
  4. Preencha o nome e a descrição da caixa de ferramentas.
  5. Em Ferramentas, clique em Adicionar
  6. Selecione Automação do Navegador e clique em Adicionar ferramenta
  7. Insira os campos necessários
    • Nome da conexão: nome exclusivo para sua conexão
    • Espaço de trabalho do Playwright: Selecione o recurso Espaço de trabalho do Playwright.
    • Tipo de autenticação: selecione o tipo de autenticação para sua conexão.
  8. Selecione Conectar.
  9. Clique em Publicar para salvar a caixa de ferramentas

Depois que a caixa de ferramentas for criada, você poderá exibir a ID de conexão Project na página de detalhes da ferramenta. Use esse valor como a ID de conexão de automação do navegador em seu código.

Adicionar automação de navegador a uma caixa de ferramentas com a CLI do Desenvolvedor do Azure

Para adicionar automação do navegador a uma Caixa de Ferramentas, use a Azure Developer CLI para criar um workspace do Playwright. Este artigo parte do pressuposto de que você já tenha um recurso de espaço de trabalho do Playwright. Consulte a seção de pré-requisitos.

  1. Crie a conexão do Workspace do Dramaturgo.
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-workspaces-access-token>"

--kind PlaywrightWorkspace exige PascalCase exata.

  1. Defina a caixa de ferramentas (my-toolbox.yaml)
description: Browser Automation toolbox
tools:
  - type: browser_automation_preview
    project_connection_id: my-browser-conn
  1. Criar a caixa de ferramentas
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

Definições de ferramenta de Automação do Navegador

Depois de executar um exemplo, verifique se a ferramenta foi chamada usando o rastreamento no Microsoft Foundry. Para obter diretrizes sobre como validar a invocação de ferramentas, consulte as melhores práticas para o uso de ferramentas no Microsoft Foundry Agent Service. Se estiver usando streaming, você também poderá procurar eventos browser_automation_preview_call.

Nota

  • O SDK do .NET está atualmente em versão prévia. Para obter mais informações, consulte o início rápido.
ProjectsAgentTool tool = new BrowserAutomationPreviewTool(
    new BrowserAutomationToolOptions(
        new BrowserAutomationToolConnectionParameters("<BROWSER_AUTOMATION_PROJECT_CONNECTION_ID>")
    )
);

const tools = [
  {
    type: "browser_automation_preview",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    browser_automation_preview: {
      connection: {
          project_connection_id: "<BROWSER_AUTOMATION_PROJECT_CONNECTION_ID>"
      }
    }
  },
];

Usar BrowserAutomationPreviewTool com exemplo de agentes

O exemplo de Python a seguir demonstra como criar um agente de IA com recursos de automação do navegador. Selecione Prompt Agents para usar o SDK de Projetos de IA Azure para criar um agente de prompt do lado do servidor ou Hosted Agents para usar o Agent Framework FoundryChatClient para criar um agente efêmero em processo.

Agentes de prompt

import json
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
  BrowserAutomationPreviewTool,
    BrowserAutomationToolParameters,
    BrowserAutomationToolConnectionParameters,
)

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
BROWSER_CONNECTION_ID = "your-browser-automation-connection-id"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

tool = BrowserAutomationPreviewTool(
    browser_automation_preview=BrowserAutomationToolParameters(
        connection=BrowserAutomationToolConnectionParameters(
            project_connection_id=BROWSER_CONNECTION_ID,
        )
    )
)

agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="""You are an Agent helping with browser automation tasks. 
        You can answer questions, provide information, and assist with various tasks 
        related to web browsing using the Browser Automation tool available to you.""",
        tools=[tool],
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

stream_response = openai.responses.create(
    stream=True,
    tool_choice="required",
    input="""
        Your goal is to report the percent of Microsoft year-to-date stock price change.
        To do that, go to the website finance.yahoo.com.
        At the top of the page, you will find a search bar.
        Enter the value 'MSFT', to get information about the Microsoft stock price.
        At the top of the resulting page you will see a default chart of Microsoft stock price.
        Click on 'YTD' at the top of that chart, and report the percent value that shows up just below it.""",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

for event in stream_response:
    if event.type == "response.created":
        print(f"Follow-up response created with ID: {event.response.id}")
    elif event.type == "response.output_text.delta":
        print(f"Delta: {event.delta}")
    elif event.type == "response.output_text.done":
        print(f"\nFollow-up response done!")
    elif event.type == "response.output_item.done":
        item = event.item
        if item.type == "browser_automation_preview_call":
            arguments_str = getattr(item, "arguments", "{}")

            # Parse the arguments string into a dictionary
            arguments = json.loads(arguments_str)
            query = arguments.get("query")

            print(f"Call ID: {getattr(item, 'call_id')}")
            print(f"Query arguments: {query}")
    elif event.type == "response.completed":
        print(f"\nFollow-up completed!")
        print(f"Full response: {event.response.output_text}")

print("\nCleaning up...")
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
print("Agent deleted")

O que esse código faz

Este exemplo cria uma versão do agente com a ferramenta de Automação de Navegador habilitada e envia um prompt que exige que o agente use a ferramenta. Ele também processa eventos de streaming para que você possa observar o progresso e as chamadas de ferramenta.

Entradas necessárias

  • Um ponto de extremidade do projeto Foundry e uma ID de conexão de automação do navegador. Consulte Configuração para obter detalhes.

Saída esperada

Ao criar o agente, você verá uma saída semelhante a:

Agent created (id: ..., name: ..., version: ...)

Durante o streaming, você também pode visualizar deltas e detalhes das chamadas de ferramentas. A saída varia de acordo com o conteúdo do site e o comportamento do modelo.

Agentes hospedados

Este exemplo usa FoundryChatClient do Microsoft Agent Framework para criar o browser-automation-toolbox e conectar-se ao seu endpoint MCP com FoundryToolbox. Instale os pacotes com pip install agent-framework-foundry azure-ai-projects, substitua PROJECT_ENDPOINT e BROWSER_CONNECTION_ID com seus valores de projeto e entre com az login. Para obter o padrão completo da caixa de ferramentas do agente hospedado, consulte o exemplo completo.

import asyncio

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
  BrowserAutomationPreviewToolboxTool,
    BrowserAutomationToolParameters,
    BrowserAutomationToolConnectionParameters,
)
from azure.identity import AzureCliCredential

PROJECT_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>"
BROWSER_CONNECTION_ID = "your-browser-automation-connection-id"


async def main() -> None:
    credential = AzureCliCredential()

    # 1. Add the Browser Automation tool to a toolbox. Using a toolbox is the recommended way
    #    to give agents tools: you curate tools once and reuse the toolbox across agents.
    #    See /azure/foundry/agents/concepts/toolbox-overview
    project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=credential)
    tool = BrowserAutomationPreviewToolboxTool(
        browser_automation_preview=BrowserAutomationToolParameters(
            connection=BrowserAutomationToolConnectionParameters(
                project_connection_id=BROWSER_CONNECTION_ID,
            )
        )
    )
    toolbox = project.toolboxes.create_version(
        name="browser-automation-toolbox",
        description="Toolbox with the Browser Automation tool",
        tools=[tool],
    )

    # 2. The toolbox exposes an MCP-compatible endpoint.
    TOOLBOX_MCP_URL = (
        f"{PROJECT_ENDPOINT}/toolboxes/{toolbox.name}"
        f"/versions/{toolbox.version}/mcp?api-version=v1"
    )

    # 3. Attach the toolbox to the hosted agent as an MCP tool.
, timeout=120.0)
    toolbox_tool = FoundryToolbox(credential, url=TOOLBOX_MCP_URL)

agent = Agent(
        client=FoundryChatClient(credential=credential),
        instructions=(
            "You help with browser automation tasks. Use the Browser Automation tool "
            "to navigate and read information from websites."
        ),
        tools=[toolbox_tool],
    )

    result = await agent.run(
        "Go to finance.yahoo.com, search for MSFT, click 'YTD' on the price chart, "
        "and report the year-to-date percent change."
    )
    print(f"Agent: {result.text}")


if __name__ == "__main__":
    asyncio.run(main())

Saída esperada

O agente navega pelo site ao vivo por meio da ferramenta de Automação do Navegador na caixa de ferramentas e relata o valor de YTD que ele observa. A saída varia de acordo com o conteúdo do site:

Agent: The year-to-date change for MSFT is approximately +18.4%.

Para obter o padrão completo da caixa de ferramentas do agente hospedado, consulte o exemplo completo.

Usar BrowserAutomationPreviewTool com exemplo de agentes

Antes de executar este exemplo, conclua as etapas de instalação na Configuração da Automação do Navegador.

O exemplo de C# a seguir demonstra como criar um agente de IA com recursos de Automação de Navegador. Selecione Prompt Agents para usar o SDK de Projetos de IA Azure para criar um agente de prompt do lado do servidor ou Hosted Agents para usar o Microsoft Agent Framework para criar um agente efêmero em processo.

Agentes de prompt

Este exemplo usa métodos síncronos da biblioteca de cliente do Azure AI Projects. Para ver um exemplo que usa métodos assíncronos, consulte o exemplo Sample for use of BrowserAutomationPreviewTool and Agents no repositório do SDK do Azure para .NET no GitHub.

using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var browserConnectionId = "your-browser-automation-connection-id";

// Note that Browser automation operations can take longer than usual
// and require the request timeout to be at least 5 minutes.
AIProjectClientOptions options = new()
{
    NetworkTimeout = TimeSpan.FromMinutes(5)
};
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential(), options: options);

// Create the Browser Automation tool using the Playwright connection.
BrowserAutomationPreviewTool playwrightTool = new(
    new BrowserAutomationToolParameters(
        new BrowserAutomationToolConnectionParameters(browserConnectionId)
    ));

// Create the Agent version with the Browser Automation tool.
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
{
    Instructions = "You are an Agent helping with browser automation tasks.\n" +
    "You can answer questions, provide information, and assist with various tasks\n" +
    "related to web browsing using the Browser Automation tool available to you.",
    Tools = { playwrightTool }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

// Create the response stream. Also set ToolChoice = ResponseToolChoice.CreateRequiredChoice()
// on the ResponseCreationOptions to ensure the agent uses the Browser Automation tool.
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
CreateResponseOptions responseOptions = new()
{
    ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
    StreamingEnabled = true,
    InputItems =
    {
        ResponseItem.CreateUserMessageItem("Your goal is to report the percent of Microsoft year-to-date stock price change.\n" +
            "To do that, go to the website finance.yahoo.com.\n" +
            "At the top of the page, you will find a search bar.\n" +
            "Enter the value 'MSFT', to get information about the Microsoft stock price.\n" +
            "At the top of the resulting page you will see a default chart of Microsoft stock price.\n" +
            "Click on 'YTD' at the top of that chart, and report the percent value that shows up just below it.")
    }
};
foreach (StreamingResponseUpdate update in responseClient.CreateResponseStreaming(options: responseOptions))
{
    if (update is StreamingResponseCreatedUpdate createUpdate)
    {
        Console.WriteLine($"Stream response created with ID: {createUpdate.Response.Id}");
    }
    else if (update is StreamingResponseOutputTextDeltaUpdate textDelta)
    {
        Console.WriteLine($"Delta: {textDelta.Delta}");
    }
    else if (update is StreamingResponseOutputTextDoneUpdate textDoneUpdate)
    {
        Console.WriteLine($"Response done with full message: {textDoneUpdate.Text}");
    }
    else if (update is StreamingResponseErrorUpdate errorUpdate)
    {
        throw new InvalidOperationException($"The stream has failed with the error: {errorUpdate.Message}");
    }
}

// Delete the Agent version to clean up resources.
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

O que esse código faz

Este exemplo cria uma versão do agente com a ferramenta de Automação de Navegador habilitada, envia um prompt que exige o uso da ferramenta e imprime atualizações de streaming à medida que o agente funciona por meio das etapas do navegador.

Entradas necessárias

  • Um ponto de extremidade do projeto Foundry e uma ID de conexão de automação do navegador. Consulte Configuração para obter detalhes.
  • Uma conexão Playwright criada em seu projeto do Foundry.

Saída esperada

Você vê as mensagens de progresso durante o streaming, como deltas de texto, e uma resposta concluída. A saída varia de acordo com o conteúdo do site e o comportamento do modelo.

Agentes hospedados

Este exemplo cria a caixa de ferramentas de Automação do Navegador com o SDK de Projetos de IA do Azure e, em seguida, usa a integração do Microsoft Agent Framework AddFoundryToolboxes para disponibilizar a ferramenta para o agente hospedado. Instale os pacotes do Agent Framework, defina as variáveis de ambiente AZURE_AI_PROJECT_ENDPOINT, AZURE_AI_MODEL_DEPLOYMENT_NAME e BROWSER_AUTOMATION_CONNECTION_ID e entre usando az login.

using System.IO;
using System.Runtime.CompilerServices;
using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? "https://<account>.services.ai.azure.com/api/projects/<project>";
string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5-mini";
string browserConnectionId = Environment.GetEnvironmentVariable("BROWSER_AUTOMATION_CONNECTION_ID")
    ?? "your-browser-automation-connection-id";

var openAiEndpoint = new Uri(projectEndpoint).GetLeftPart(UriPartial.Authority);
DefaultAzureCredential credential = new();

// 1. Create the Browser Automation tool and add it to a toolbox. Using a toolbox is the
//    recommended way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
ProjectsAgentTool browserTool = new BrowserAutomationPreviewTool(
    new BrowserAutomationToolParameters(
        new BrowserAutomationToolConnectionParameters(browserConnectionId)
    ));
ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateToolboxVersion(
        toolboxName: "browser-automation-toolbox",
        tools: [browserTool],
        description: "Toolbox with the Browser Automation tool");

// Create the hosted agent and register the toolbox integration.
AIAgent agent = projectClient.AsAIAgent(
    model: deploymentName,
    instructions: "You are a helpful assistant with access to the toolbox tools.",
    name: "hosted-toolbox-agent");

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.Services.AddFoundryToolboxes(credential, toolboxVersion.Name);

var app = builder.Build();
app.MapFoundryResponses();
app.Run();

Saída esperada

O agente hospedado se conecta à ferramenta de Automação do Navegador por meio do ponto de extremidade MCP da caixa de ferramentas e usa o navegador para concluir a tarefa da Web solicitada. A saída varia de acordo com o conteúdo do site e o comportamento do modelo:

Agent: The year-to-date change for MSFT is approximately +18.4%.

Para obter o padrão completo da caixa de ferramentas do agente hospedado, consulte o exemplo completo.

Obtenha um token de acesso:

AGENT_TOKEN=$(az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv)

Esse token de acesso é de curta duração. Mantenha-o apenas no shell ou processo atual. Nunca confirme, armazene, imprima ou registre esta alteração. Execute o comando novamente após ele expirar. Os fluxos do SDK usam DefaultAzureCredential onde há suporte, mas essas solicitações REST exigem o token de portador.

A maneira recomendada de adicionar a Automação do Navegador é por meio de uma caixa de ferramentas e, em seguida, anexar a caixa de ferramentas ao seu agente como uma ferramenta MCP. Veja o que é uma caixa de ferramentas?

  1. Crie uma caixa de ferramentas que contenha a ferramenta de Automação do Navegador:
curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/browser-automation-toolbox/versions?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "description": "Toolbox with the Browser Automation tool",
    "tools": [
      {
        "type": "browser_automation_preview",
        "browser_automation_preview": {
          "connection": {
            "project_connection_id": "'"$BROWSER_AUTOMATION_PROJECT_CONNECTION_ID"'"
          }
        }
      }
    ]
  }'

O kit de ferramentas expõe um endpoint compatível com MCP em $FOUNDRY_PROJECT_ENDPOINT/toolboxes/browser-automation-toolbox/versions/<version>/mcp?api-version=v1, em que <version> é a versão retornada pela chamada anterior.

  1. Crie uma conexão de projeto de ferramenta remota que aponte para o ponto de extremidade da caixa de ferramentas, usando um token Entra do usuário para que a identidade do chamador seja passada (audiência https://ai.azure.com).
azd ai connection create browser-automation-toolbox-conn \
  --kind remote-tool \
  --target "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/browser-automation-toolbox/versions/<version>/mcp?api-version=v1" \
  --auth-type user-entra-token \
  --audience https://ai.azure.com
  1. Crie uma resposta que use a caixa de ferramentas anexando-a como uma ferramenta MCP.
curl --request POST \
  --url "${FOUNDRY_PROJECT_ENDPOINT}/openai/v1/responses" \
  --header "Authorization: Bearer ${AGENT_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "User-Agent: insomnia/11.6.1" \
  --data @- <<JSON
{
  "model": "${FOUNDRY_MODEL_DEPLOYMENT_NAME}",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Your goal is to report the percent of Microsoft year-to-date stock price change."
        },
        {
          "type": "input_text",
          "text": "Go to finance.yahoo.com, search for MSFT, select YTD on the chart, and report the percent value shown."
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "mcp",
      "server_label": "toolbox",
      "server_url": "${FOUNDRY_PROJECT_ENDPOINT}/toolboxes/browser-automation-toolbox/versions/<version>/mcp?api-version=v1",
      "require_approval": "never",
      "project_connection_id": "browser-automation-toolbox-conn"
    }
  ]
}
JSON

Usar a ferramenta de automação de navegador com exemplo de uso com agentes

O exemplo typeScript a seguir demonstra como criar um agente com a ferramenta de Automação do Navegador, executar tarefas de navegação na Web e processar respostas de streaming com eventos de automação do navegador. Para obter uma versão javaScript deste exemplo, consulte o exemplo JavaScript para a ferramenta de Automação de Navegador no repositório SDK do Azure para JavaScript no GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const BROWSER_CONNECTION_ID = "your-browser-automation-connection-id";

const handleBrowserCall = (item: any) => {
  // TODO: support browser_automation_preview_call schema
  const callId = item.call_id;
  const argumentsStr = item.arguments;

  // Parse the arguments string into a dictionary
  let query = null;
  if (argumentsStr && typeof argumentsStr === "string") {
    try {
      const argumentsObj = JSON.parse(argumentsStr);
      query = argumentsObj.query;
    } catch (e) {
      console.error("Failed to parse arguments:", e);
    }
  }

  console.log(`Call ID: ${callId ?? "None"}`);
  console.log(`Query arguments: ${query ?? "None"}`);
};

export async function main(): Promise<void> {
  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  console.log("Creating a toolbox with the Browser Automation tool...");

  // 1. Add the Browser Automation tool to a toolbox. Using a toolbox is the recommended
  //    way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
  const toolbox = await project.toolboxes.createVersion(
    "browser-automation-toolbox",
    [
      {
        type: "browser_automation_preview",
        browser_automation_preview: {
          connection: {
            project_connection_id: BROWSER_CONNECTION_ID,
          },
        },
      },
    ],
    { description: "Toolbox with the Browser Automation tool" },
  );

  // 2. The toolbox exposes an MCP-compatible endpoint.
  const toolboxMcpUrl =
    `${PROJECT_ENDPOINT}/toolboxes/${toolbox.name}` +
    `/versions/${toolbox.version}/mcp?api-version=v1`;

  // 3. Create a remote-tool project connection that points at the toolbox endpoint.
  //    Use a user Entra token so the caller's identity is passed through
  //    (audience https://ai.azure.com). Create the connection once, for example
  //    with the Azure Developer CLI:
  //
  //    azd ai connection create browser-automation-toolbox-conn \
  //      --kind remote-tool \
  //      --target "<toolboxMcpUrl>" \
  //      --auth-type user-entra-token \
  //      --audience https://ai.azure.com
  const toolboxConnectionName = "browser-automation-toolbox-conn";

  // 4. Attach the toolbox to a prompt agent as an MCP tool.
  const agent = await project.agents.createVersion("MyAgent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions: `You are an Agent helping with browser automation tasks. 
            You can answer questions, provide information, and assist with various tasks 
            related to web browsing using the Browser Automation tool available to you.`,
    tools: [
      {
        type: "mcp",
        server_label: "toolbox",
        server_url: toolboxMcpUrl,
        require_approval: "never",
        project_connection_id: toolboxConnectionName,
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  console.log("\nSending browser automation request with streaming...");
  const streamResponse = await openai.responses.create(
    {
      input: `Your goal is to report the percent of Microsoft year-to-date stock price change.
            To do that, go to the website finance.yahoo.com.
            At the top of the page, you will find a search bar.
            Enter the value 'MSFT', to get information about the Microsoft stock price.
            At the top of the resulting page you will see a default chart of Microsoft stock price.
            Click on 'YTD' at the top of that chart, and report the percent value that shows up just below it.`,
      stream: true,
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.created") {
      console.log(`Follow-up response created with ID: ${event.response.id}`);
    } else if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n\nFollow-up response done!");
    } else if (
      event.type === "response.output_item.done" ||
      event.type === "response.output_item.added"
    ) {
      const item = event.item as any;
      if (item.type === "browser_automation_preview_call") {
        handleBrowserCall(item);
      }
    } else if (event.type === "response.completed") {
      console.log("\nFollow-up completed!");
    }
  }

  // Clean up resources by deleting the agent version
  // This prevents accumulation of unused resources in your project
  console.log("\nCleaning up resources...");
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nBrowser Automation sample completed!");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

O que esse código faz

Este exemplo cria uma versão do agente com a ferramenta de Automação de Navegador habilitada, envia um prompt que exige o uso da ferramenta e processa eventos de streaming, incluindo eventos de chamada de automação do navegador, conforme eles chegam.

Entradas necessárias

  • Um ponto de extremidade do projeto Foundry e uma ID de conexão de automação do navegador. Consulte Configuração para obter detalhes.

Saída esperada

Você vê uma mensagem "Agente criado..." e a saída de texto em fluxo contínuo, além, opcionalmente, dos detalhes da chamada no navegador quando a ferramenta é invocada. A saída varia de acordo com o conteúdo do site e o comportamento do modelo.

Usar a automação do navegador em um agente de Java

Atualize esses valores em seu agente de Java depois de criar a caixa de ferramentas:

  • projectEndpoint — O ponto de extremidade do seu projeto.
  • toolboxMcpUrl — O ponto de extremidade MCP para a versão da caixa de ferramentas que contém a ferramenta Automação do Navegador.
  • toolboxConnectionName — O nome da conexão de projeto de ferramenta remota para o ponto de extremidade da caixa de ferramentas.

Adicione a dependência ao seu pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.4.0</version>
</dependency>

Dica

Recomendado: Para a maioria dos agentes, adicione a ferramenta de Automação do Navegador por meio de uma caixa de ferramentas e anexe a caixa de ferramentas ao seu agente como uma ferramenta MCP. O SDK Java ainda não expõe uma API de criação de caixa de ferramentas, portanto, crie a caixa de ferramentas usando o exemplo Python, API REST, C#ou TypeScript ou o portal do Foundry e, em seguida, referencie seu ponto de extremidade MCP do agente Java como um McpTool.

Limitações

  • Somente sites confiáveis: use essa ferramenta somente com sites confiáveis. Evite páginas que solicitam credenciais, pagamentos ou outras ações confidenciais.
  • Volatilidade da página: as páginas da Web podem ser alteradas a qualquer momento. O agente poderá falhar se o layout da página, os rótulos ou os fluxos de navegação forem alterados. Crie tratamento de erros em seus fluxos de trabalho.
  • Aplicativos complexos de página única: SPAs de JavaScript pesados com conteúdo dinâmico podem não ser renderizados corretamente.

Considerações de custo

Essa ferramenta usa um recurso de workspace do Playwright para executar sessões do navegador. Consulte a documentação do workspace do Playwright para obter detalhes de preços e uso. Para obter diretrizes sobre como otimizar o uso da ferramenta, consulte Melhores práticas para usar ferramentas no Microsoft Foundry Agent Service.

Solucionando problemas

O agente não usa a ferramenta

  • Confirme se você criou o agente com a ferramenta de Automação do Navegador habilitada.
  • Em sua solicitação, exija o uso da ferramenta (por exemplo, tool_choice="required").
  • Use o rastreamento no Microsoft Foundry para confirmar se ocorreu uma chamada de ferramenta. Para obter diretrizes, consulte Melhores práticas para usar ferramentas no Microsoft Foundry Agent Service.

Erros de conexão ou autorização

  • Confirme se a ID de conexão da automação do navegador corresponde à ID do recurso de conexão do workspace do Playwright em seu projeto.
  • Confirme se a identidade do projeto tem acesso ao recurso de espaço de trabalho do Playwright.
  • Se você recentemente rotacionou o token de acesso do Playwright, atualize a chave de conexão do projeto Foundry.

Erros do SDK do Python

  • Workspace não encontrado: Verifique se o endpoint do projeto usa o formato correto: https://{account-name}.services.ai.azure.com/api/projects/{project-name}. Não use o formato de ponto de extremidade legado do Azure ML.
  • Erros inesperados de argumento de palavra-chave: verifique se você está usando a versão mais recente de azure-ai-projects. Execute pip install "azure-ai-projects>=2.0.0" --upgrade para atualizar.
  • Erros de importação: instalar todos os pacotes necessários: pip install "azure-ai-projects>=2.0.0".

Tempo limite das solicitações

A automação do navegador pode levar mais tempo do que as solicitações típicas.

  • Aumente o tempo limite do cliente (o exemplo de C# define um tempo limite de 5 minutos).
  • Reduza o escopo do prompt (por exemplo, menos páginas e menos interações).

Limpar

  • Exclua a versão do agente que você criou para teste.
  • Revogue ou substitua o token de acesso do Playwright se você não precisar mais dele.
  • Remova a conexão do projeto se ela não for mais necessária. Para obter mais informações, consulte Add uma conexão no Microsoft Foundry.

Cenários de exemplo

  • Preenchimento de formulário: lida com diversos tipos de formulário com validação, DOM, autenticação, conformidade e suporte ao raciocínio de várias rodadas.

  • Raspagem da Web: navega sites autenticados para raspar, comparar e estruturar dados entre fontes.

Nota de transparência

Examine a nota de transparência ao usar essa ferramenta. A ferramenta de Automação de Navegador é uma ferramenta que pode executar tarefas de navegador do mundo real por meio de prompts de linguagem natural, permitindo atividades de navegação automatizadas sem intervenção humana.

Examine as considerações de IA responsáveis ao usar essa ferramenta.

Conteúdo relacionado

  • Last updated on