Pesquisa na Web

A Pesquisa na Web permite aos agentes pesquisar na internet informações up-todatas. Esta ferramenta permite aos agentes responder a perguntas sobre eventos atuais, encontrar documentação e aceder a informações para além dos seus dados de treino.

Observação

A disponibilidade da Web Search depende do fornecedor do agente subjacente. Consulte a Visão Geral dos Prestadores para apoio específico para cada prestador.

O exemplo seguinte mostra como criar um agente com a ferramenta Web Search:

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?"));

Advertência

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

O exemplo seguinte mostra como criar um agente com a ferramenta Web Search:

# 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

Este hostedtool.WebSearch tipo permite a pesquisa web do lado do servidor ao utilizar um fornecedor que o suporta.

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 alojada — a pesquisa é realizada pelo serviço de IA, não localmente.

Use a pesquisa na web com o Harness Agent

Para um agente simples, adicione HostedWebSearchTool às ferramentas do agente, como mostrado anteriormente. HarnessAgent adiciona um HostedWebSearchTool por defeito, por isso não é necessário registo de ferramentas:

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 fornecedor selecionado não suporta a pesquisa web alojada ou quando quiser registar uma ferramenta de pesquisa específica para o fornecedor através ChatOptions.Toolsde . Se adicionar a sua própria ferramenta de pesquisa web sem desativar a predefinida, o agente recebe ambas as ferramentas.

A pesquisa web é alojada pelo fornecedor do modelo; não existe um ciclo de vida local de cliente de pesquisa para o Harness gerir. Disponibilidade, modelos suportados, parâmetros de pesquisa, residência de dados e faturação dependem do IChatClient fornecedor. Clientes não suportados podem rejeitar a ferramenta alojada quando o pedido é enviado.

Trate as consultas e resultados de pesquisa como dados que ultrapassam uma fronteira de confiança externa. Não inclua segredos nas consultas e trate as páginas recuperadas como conteúdo não confiável que pode conter injeção indireta de prompts. Verifique afirmações e citações importantes antes de tomar medidas.

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

Para um agente simples, ligue client.get_web_search_tool(...) e passe a ferramenta devolvida para Agent, como mostrado anteriormente. create_harness_agent chamadas client.get_web_search_tool() sem argumentos por defeito 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 regista um aviso e continua sem pesquisa na web. Definido disable_web_search=True para suprimir o registo automático e o aviso.

Para passar pelas definições específicas do fornecedor, desative o padrão e registe-se explicitamente a ferramenta configurada:

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 fornecedor é responsável pela execução e ciclo de vida da pesquisa hospedada. Parâmetros suportados, modelos, tratamento de dados e faturação dependem da implementação do cliente. Não coloque segredos nas consultas, trate o conteúdo recuperado como entrada não confiável e verifique afirmações e citações importantes antes de agir.

create_harness_agent é lançado em agent-framework-core; a pesquisa web permanece disponível apenas através de clientes que implementam SupportsWebSearchTool.

Um Go Harness embalado não está atualmente disponível. Adicione hostedtool.WebSearch a um agente Go simples, como mostrado anteriormente.

Próximos passos

Ferramentas MCP Alojadas