Pesquisa na Web

A Pesquisa na Web permite que os agentes pesquisem informações de data up-tona Web. Essa ferramenta permite que os agentes respondam a perguntas sobre eventos atuais, encontrem documentação e acessem informações além de seus dados de treinamento.

Observação

A disponibilidade da Pesquisa na Web depende do provedor de agente subjacente. Consulte a Visão geral dos provedores para obter suporte específico ao provedor.

O exemplo a seguir mostra como criar um agente com a ferramenta de Pesquisa na Web:

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// Requires: dotnet add package Microsoft.Agents.AI.Foundry --prerelease
var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";

// Create an agent with hosted web search.
AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant that can search the web for current information.",
        tools: [new HostedWebSearchTool()]);

Console.WriteLine(await agent.RunAsync("What is the current weather in Seattle?"));

Aviso

DefaultAzureCredential é conveniente para o desenvolvimento, mas requer uma consideração cuidadosa na produção. Em produção, considere o uso de uma credencial específica (por exemplo, ManagedIdentityCredential) para evitar problemas de latência, investigação de credenciais não intencionais e possíveis riscos de segurança de mecanismos de fallback.

O exemplo a seguir mostra como criar um agente com a ferramenta de Pesquisa na Web:

# Copyright (c) Microsoft. All rights reserved.

import asyncio

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

"""
OpenAI Responses Client with Web Search Example

This sample demonstrates using get_web_search_tool() with OpenAI Responses Client
for direct real-time information retrieval and current data access.
"""


async def main() -> None:
    client = OpenAIChatClient()

    # Create web search tool with location context
    web_search_tool = client.get_web_search_tool(
        user_location={"city": "Seattle", "country": "US"},
    )

    agent = Agent(
        client=client,
        instructions="You are a helpful assistant that can search the web for current information.",
        tools=[web_search_tool],
    )

    message = "What is the current weather? Do not ask for my current location."
    stream = False
    print(f"User: {message}")

    if stream:
        print("Assistant: ", end="")
        async for chunk in agent.run(message, stream=True):
            if chunk.text:
                print(chunk.text, end="")
        print("")
    else:
        response = await agent.run(message)
        print(f"Assistant: {response}")


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

Pesquisa na Web

O hostedtool.WebSearch tipo habilita a pesquisa na Web do lado do servidor ao usar um provedor compatível com ele.

import "github.com/microsoft/agent-framework-go/tool/hostedtool"

webSearch := &hostedtool.WebSearch{}

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Config: agent.Config{
        Tools: []tool.Tool{webSearch},
    },
})

Observação

A pesquisa na Web é uma ferramenta hospedada – a pesquisa é executada pelo serviço de IA, não localmente.

Usar a pesquisa na Web com o Harness Agent

Para um agente sem formatação, adicione HostedWebSearchTool às ferramentas do agente, conforme mostrado anteriormente. HarnessAgent adiciona um HostedWebSearchTool por padrão, portanto, nenhum registro de ferramenta é necessário:

using Microsoft.Agents.AI;

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    ChatOptions = new()
    {
        Instructions = "Use web search for current information and cite the sources you used.",
    },
});

Defina DisableWebSearch = true quando o provedor selecionado não dá suporte à pesquisa na Web hospedada ou quando você quiser registrar uma ferramenta de pesquisa específica do provedor por conta ChatOptions.Toolsprópria. Se você adicionar sua própria ferramenta de pesquisa na Web sem desabilitar o padrão, o agente receberá ambas as ferramentas.

A pesquisa na Web é hospedada pelo provedor de modelos; não há nenhum ciclo de vida local de cliente de pesquisa para o Harness gerenciar. Disponibilidade, modelos com suporte, parâmetros de pesquisa, residência de dados e cobrança dependem do IChatClient provedor. Clientes sem suporte podem rejeitar a ferramenta hospedada quando a solicitação é enviada.

Trate consultas e resultados de pesquisa como dados que cruzam um limite de confiança externo. Não inclua segredos em consultas e trate as páginas recuperadas como conteúdo não confiável que possa conter injeção de prompt indireto. Verifique declarações e citações importantes antes de executar ações.

HarnessAgent está disponível no Microsoft.Agents.AI.Harness pacote.

Para um agente sem formatação, chame client.get_web_search_tool(...) e passe a ferramenta retornada para Agent, conforme mostrado anteriormente. create_harness_agent chamadas client.get_web_search_tool() sem argumentos por padrão quando o cliente implementa SupportsWebSearchTool:

from agent_framework import create_harness_agent

agent = create_harness_agent(client=client)

Se o cliente não implementar SupportsWebSearchTool, a fábrica registrará um aviso e continuará sem pesquisa na Web. Defina disable_web_search=True para suprimir o registro automático e o aviso.

Para passar configurações específicas do provedor, desabilite o padrão e registre a ferramenta configurada explicitamente:

agent = create_harness_agent(
    client=client,
    disable_web_search=True,
    tools=[
        client.get_web_search_tool(
            user_location={"city": "Seattle", "country": "US"},
            search_context_size="medium",
        )
    ],
)

O provedor possui a execução de pesquisa hospedada e o ciclo de vida. Parâmetros, modelos, manipulação de dados e cobrança com suporte dependem da implementação do cliente. Não coloque segredos em consultas, trate o conteúdo recuperado como entrada não confiável e verifique declarações e citações importantes antes de executar ações.

create_harness_agent é lançado em ; a pesquisa na agent-framework-coreWeb permanece disponível somente por meio de clientes que implementam SupportsWebSearchTool.

Um Go Harness empacotado não está disponível no momento. Adicione hostedtool.WebSearch a um agente Go simples, conforme mostrado anteriormente.

Próximas etapas

Ferramentas MCP hospedadas