Websuchtool

Allgemeine Websuche

Das folgende Beispiel zeigt, wie Sie einem Agent Zugriff auf die Websuche gewähren. Wählen Sie Prompt Agents aus, um das AZURE AI Projects SDK zum Erstellen eines serverseitigen Eingabeaufforderungs-Agents oder Hosted Agents zu verwenden, um das Agent Framework FoundryChatClient zum Erstellen eines ephemeralen, in-Process-Agents zu verwenden.

Prompt-Agenten

Erstellen des Agents und Ausführen einer Suche

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    WebSearchTool,
    WebSearchApproximateLocation,
)

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

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

# Create an agent with the web search tool
agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that can search the web",
        tools=[
            WebSearchTool(
                user_location=WebSearchApproximateLocation(
                    country="GB", city="London", region="London"
                )
            )
        ],
    ),
    description="Agent for web search.",
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

# Send a query and stream the response
stream_response = openai.responses.create(
    stream=True,
    tool_choice="required",
    input="What is today's date and weather in Seattle?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

# Process streaming events
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":
        if event.item.type == "message":
            item = event.item
            if item.content[-1].type == "output_text":
                text_content = item.content[-1]
                for annotation in text_content.annotations:
                    if annotation.type == "url_citation":
                        print(f"URL Citation: {annotation.url}")
    elif event.type == "response.completed":
        print(f"\nFollow-up completed!")
        print(f"Full response: {event.response.output_text}")

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

Erwartete Ausgabe

Agent created: <agent-name> (version 1)
Response: The latest trends in renewable energy include ...
URL Citation: https://example.com/source

Follow-up completed!
Full response: Based on current data ...
Agent deleted

Gehostete Agents

Dieses Beispiel verwendet FoundryChatClient aus dem Microsoft Agent Framework und verbindet sich über FoundryToolbox mit dem MCP-Endpunkt der Toolbox. Installieren Sie das Paket mit pip install agent-framework-foundry, legen Sie die FOUNDRY_PROJECT_ENDPOINT Variablen und FOUNDRY_MODEL Umgebung fest, und melden Sie sich mit az login. Das vollständige Toolboxmuster des gehosteten Agents finden Sie im vollständigen Beispiel.

Erstellen einer Toolbox und Ausführen eines gehosteten Agents

import asyncio

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from azure.identity import AzureCliCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import WebSearchToolboxTool, WebSearchApproximateLocation

PROJECT_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>"


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

    # 1. Create the web search tool and add it to a toolbox. Using a toolbox is the
    #    recommended way to give agents tools: curate tools once and reuse the
    #    toolbox across agents. See /azure/foundry/agents/concepts/toolbox-overview
    project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=credential)
    toolbox = project.toolboxes.create_version(
        name="web-search-toolbox",
        description="Toolbox with the web search tool",
        tools=[
            WebSearchToolboxTool(
                user_location=WebSearchApproximateLocation(
                    country="GB", city="London", region="London"
                )
            )
        ],
    )

    # 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 are a research assistant. Use web search to find current information.",
        tools=[toolbox_tool],
    )

    result = await agent.run("What are the latest updates to Microsoft Foundry?")
    print(f"Agent: {result.text}")

    # Print any URL citations returned by the web search tool.
    for message in result.messages:
        for content in message.contents:
            for annotation in getattr(content, "annotations", None) or []:
                url = getattr(annotation, "url", None)
                if url:
                    title = getattr(annotation, "title", None) or ""
                    print(f"URL Citation: [{title}]({url})")


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

Erwartete Ausgabe

Der Agent antwortet mithilfe aktueller Informationen aus dem Web und gibt alle URL-Quellenangaben aus, die das Tool zurückgibt. Die Ausgabe variiert, wenn sich der Inhalt im Web ändert:

Agent: The latest updates to Microsoft Foundry include ...
URL Citation: [Microsoft Foundry documentation](https://learn.microsoft.com/azure/ai-foundry/)

Das Websuchwerkzeug wird in der Foundry Responses API serverseitig ausgeführt. Sie können es mit Tools für lokale Funktionen kombinieren, indem Sie der @tool-Liste zusätzliche Einträge hinzufügen (z. B. eine tools-dekorierte Funktion). Weitere Informationen finden Sie in der Schnellstartanleitung: Verwenden der Findry-Antwort-API.

Domänenbeschränkte Suche mit benutzerdefinierter Bing-Suche

Das folgende Beispiel zeigt, wie Sie die Websuche mithilfe einer benutzerdefinierten Bing-Suchinstanz auf bestimmte Domänen beschränken. Mit diesem Ansatz können Sie steuern, welche Websites Ihr Agent durchsuchen kann.

Erstellen Sie die Toolbox und den domänenbeschränkten Agenten

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    WebSearchToolboxTool,
    WebSearchConfiguration,
    MCPTool,
)

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
BING_CUSTOM_SEARCH_CONNECTION_ID = "your_bing_custom_search_connection_id"
BING_CUSTOM_SEARCH_INSTANCE_NAME = "your_bing_custom_search_instance_name"

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

# 1. Add the web search tool and custom search configuration to a toolbox.
toolbox = project.toolboxes.create_version(
    name="web-search-toolbox",
    description="Toolbox with the web search tool",
    tools=[
        WebSearchToolboxTool(
            custom_search_configuration=WebSearchConfiguration(
                project_connection_id=BING_CUSTOM_SEARCH_CONNECTION_ID,
                instance_name=BING_CUSTOM_SEARCH_INSTANCE_NAME,
            )
        )
    ],
)

# 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. 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 web-search-toolbox-conn \
#      --kind remote-tool \
#      --target "<TOOLBOX_MCP_URL>" \
#      --auth-type user-entra-token \
#      --audience https://ai.azure.com
TOOLBOX_CONNECTION_NAME = "web-search-toolbox-conn"

# 4. Attach the toolbox to a prompt agent as an MCP tool.
agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that can search the web",
        tools=[
            MCPTool(
                server_label="toolbox",
                server_url=TOOLBOX_MCP_URL,
                require_approval="never",
                project_connection_id=TOOLBOX_CONNECTION_NAME,
            )
        ],
    ),
    description="Agent for domain-restricted web search.",
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

# Send a query and stream the response
stream_response = openai.responses.create(
    stream=True,
    tool_choice="required",
    input="What are the latest updates from Microsoft Learn?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

# Process streaming events
for event in stream_response:
    if event.type == "response.created":
        print(f"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"\nResponse done!")
    elif event.type == "response.output_item.done":
        if event.item.type == "message":
            item = event.item
            if item.content[-1].type == "output_text":
                text_content = item.content[-1]
                for annotation in text_content.annotations:
                    if annotation.type == "url_citation":
                        print(f"URL Citation: {annotation.url}")
    elif event.type == "response.completed":
        print(f"\nResponse completed!")
        print(f"Full response: {event.response.output_text}")

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

Erwartete Ausgabe

Agent created (id: abc123, name: MyAgent, version: 1)
Response created with ID: resp_456
Delta: Based on your custom search ...
Response done!
URL Citation: https://your-allowed-domain.com/article

Response completed!
Full response: Based on your custom search ...
Agent deleted

Tipps für domänenbeschränkte Suche

Grounding mit benutzerdefinierter Bing-Suche ist ein leistungsstarkes Tool, mit dem Sie einen Teilbereich des Webs auswählen können, um das Grounding-Wissen Ihres Agents einzuschränken. Hier sind einige Tipps, die Ihnen helfen, diese Funktion vollständig zu nutzen:

• Wenn Sie eine öffentliche Website besitzen, die Sie in die Suche aufnehmen möchten, die Bing jedoch noch nicht indiziert hat, finden Sie in den Bing Webmaster-Richtlinien ausführliche Informationen dazu, wie Ihre Website indiziert werden kann. Die Webmasterdokumentation enthält auch Details zum Abrufen von Bing zum Durchforsten Ihrer Website, wenn der Index veraltet ist.
• Um eine Konfiguration zu erstellen, aktivieren Sie die Rolle Contributor für die Bing Custom Search-Ressource rechtzeitig über Microsoft Entra PIM. Deaktivieren Sie die Rolle nach der Konfiguration. Entwickler von Agents und Benutzer der Laufzeitumgebung benötigen diese Rolle im Alltag nicht.
• Sie können bestimmte Domänen blockieren und eine Suche für den Rest des Webs ausführen (z. B. die Website eines Wettbewerbers).
• Grounding with Bing Custom Search liefert nur Ergebnisse für Domänen und Webseiten, die öffentlich sind und von Bing indexiert werden.
• Sie können verschiedene Granularitätsebenen angeben:
  • Domäne (z. B https://www.microsoft.com. )
  • Domäne und Pfad (z. B https://www.microsoft.com/surface. )
  • Webseite (z. B https://www.microsoft.com/en-us/p/surface-earbuds/8r9cpq146064. )

Tiefe Recherche mit Websuche

Das folgende Beispiel zeigt, wie Sie das o3-deep-research Modell mit dem Vorschautool für die direkte Websuche verwenden. Dieser Ansatz ersetzt das veraltete Deep Research-Tool. Leiten Sie die Websuche nicht über eine Toolbox für die umfassende Recherche weiter, da das Modell das Tool für die direkte Antwortwebsuche benötigt.

Deep-Research-Agent erstellen

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchPreviewTool

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

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

# Create a prompt agent with the direct web search preview tool.
agent = project.agents.create_version(
    agent_name="MyDeepResearchAgent",
    definition=PromptAgentDefinition(
        model="o3-deep-research",
        instructions="You are a helpful assistant that can search the web",
        tools=[WebSearchPreviewTool()],
    ),
    description="Agent for deep research with web search.",
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

# Create a conversation for the agent interaction
conversation = openai.conversations.create()
print(f"Created conversation (id: {conversation.id})")

# Send a query to search the web
stream_response = openai.responses.create(
    stream=True,
    conversation=conversation.id,
    input="What are the latest advancements in quantum computing?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

# Process streaming events as they arrive
for event in stream_response:
    if event.type == "response.created":
        print(f"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"\nResponse done!")
    elif event.type == "response.completed":
        print(f"\nResponse completed!")
        print(f"Full response: {event.response.output_text}")

# Clean up resources
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
print("Agent deleted")

Allgemeine Websuche

Das folgende Beispiel zeigt, wie Sie einem Agent Zugriff auf die Websuche gewähren. Wählen Sie Prompt Agents aus, um das AZURE AI Projects SDK zum Erstellen eines serverseitigen Eingabeaufforderungs-Agents oder Hosted Agents zu verwenden, um das Microsoft Agent Framework zum Erstellen eines ephemeren, in-Process-Agents zu verwenden.

Prompt-Agenten

In diesem Beispiel verwenden Sie den Agent, um die Websuche an dem angegebenen Speicherort auszuführen. Im Beispiel in diesem Abschnitt werden synchrone Aufrufe verwendet. Für ein asynchrones Beispiel siehe den Beispielcode im Azure SDK für .NET-Repository auf GitHub.

Erstellen des Agents und Ausführen einer Suche

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

// Create project client to call Foundry API
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Create an agent with the web search tool
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful assistant that can search the web",
    Tools = {
        ResponseTool.CreateWebSearchTool(userLocation: WebSearchToolLocation.CreateApproximateLocation(
            country: "GB",
            city: "London",
            region: "London"
            )
        ),
    }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

// Ask a question related to London.
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);

ResponseResult response = responseClient.CreateResponse("Show me the latest London Underground service updates");

// Create the response and verify it completed.
Console.WriteLine($"Response status: {response.Status}");
Console.WriteLine(response.GetOutputText());

// Delete the created agent version.
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

Erwartete Ausgabe

Im Folgenden sehen Sie ein Beispiel für die erwartete Ausgabe beim Ausführen des C#-Codes:

Response status: Completed
The London Underground currently has service disruptions on ...
Agent deleted

Gehostete Agents

In diesem Beispiel wird die Websuch-Toolbox mit dem AZURE AI Projects SDK erstellt. Anschließend wird die Microsoft Agent Framework-Integration AddFoundryToolboxes verwendet, um die Websuche für den gehosteten Agent verfügbar zu machen. Legen Sie die Umgebungsvariablen AZURE_AI_PROJECT_ENDPOINT, AZURE_OPENAI_ENDPOINT und AZURE_AI_MODEL_DEPLOYMENT_NAME fest, und melden Sie sich mit az login an.

Erstellen einer Toolbox und Ausführen eines gehosteten Agents

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;

const string AgentInstructions = "You are a helpful assistant that can search the web to find current information and answer questions accurately.";
const string AgentName = "WebSearchAgent";

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? "https://<account>.services.ai.azure.com/api/projects/<project>";
string openAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5-mini";

DefaultAzureCredential credential = new();

// 1. Create the web search 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 webTool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateWebSearchTool(userLocation: WebSearchToolLocation.CreateApproximateLocation(
        "GB", "London", "London")));
ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateToolboxVersion(
        toolboxName: "web-search-toolbox",
        tools: [webTool],
        description: "Toolbox with the web search 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();

Erwartete Ausgabe

Der Agent antwortet mithilfe aktueller Informationen aus dem Web und gibt alle URL-Quellenangaben aus, die das Tool zurückgibt. Die Ausgabe variiert, wenn sich der Inhalt im Web ändert:

Response: Today in Seattle it is mostly cloudy with a high near 55°F ...
Title: National Weather Service – Seattle
URL: https://www.weather.gov/sew/

Der gehostete Agent stellt eine Verbindung mit einem Toolbox-Endpunkt her und erkennt das Tool für die Websuche zur Laufzeit. Sie können der Toolbox weitere Tools hinzufügen, ohne den Code des gehosteten Agents zu ändern.

Domänenbeschränkte Websuche

Um Ihrem Agenten die Verwendung der Websuche mit Grounding über eine benutzerdefinierte Bing-Suchinstanz zu ermöglichen.

1. Erstellen Sie zuerst den Projektclient, und definieren Sie die werte, die in den nächsten Schritten verwendet werden.

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var modelDeploymentName = "gpt-4.1-mini";
var connectionName = "your_custom_bing_connection_name";
var customInstanceName = "your_bing_custom_search_instance_name";
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());

2. Erstellen Sie einen Agent, der die Websuche mit einer benutzerdefinierten Bing-Suchinstanz verwenden kann.

Synchrones Beispiel:

AIProjectConnection bingConnection = projectClient.Connections.GetConnection(connectionName: connectionName);
WebSearchTool webSearchTool = ResponseTool.CreateWebSearchTool();
webSearchTool.CustomSearchConfiguration = new(bingConnection.Id, customInstanceName);
DeclarativeAgentDefinition agentDefinition = new(model: modelDeploymentName)
{
    Instructions = "You are a helpful agent.",
    Tools = { webSearchTool }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

Asynchrones Beispiel:

AIProjectConnection bingConnection = projectClient.Connections.GetConnection(connectionName: connectionName);
WebSearchTool webSearchTool = ResponseTool.CreateWebSearchTool();
webSearchTool.CustomSearchConfiguration = new(bingConnection.Id, customInstanceName);
DeclarativeAgentDefinition agentDefinition = new(model: modelDeploymentName)
{
    Instructions = "You are a helpful agent.",
    Tools = { webSearchTool }
};
AgentVersion agentVersion = await projectClient.AgentAdministrationClient.CreateAgentVersionAsync(
    agentName: "myAgent",
    options: new(agentDefinition));

1. Rufen Sie die GetFormattedAnnotation Methode auf, um die Anmerkung zu formatieren.

private static string GetFormattedAnnotation(ResponseItem item)
{
    if (item is MessageResponseItem messageItem)
    {
        foreach (ResponseContentPart content in messageItem.Content)
        {
            foreach (ResponseMessageAnnotation annotation in content.OutputTextAnnotations)
            {
                if (annotation is UriCitationMessageAnnotation uriAnnotation)
                {
                    return $" [{uriAnnotation.Title}]({uriAnnotation.Uri})";
                }
            }
        }
    }
    return "";
}

4. Stellen Sie die Frage, und streamen Sie die Antwort.

Synchrones Beispiel:

ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);

string annotation = "";
string text = "";
CreateResponseOptions options = new()
{
    ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
    InputItems = { ResponseItem.CreateUserMessageItem("How many medals did the USA win in the 2024 summer olympics?") },
};
foreach (StreamingResponseUpdate streamResponse in responseClient.CreateResponseStreaming(options))
{
    if (streamResponse is StreamingResponseCreatedUpdate createUpdate)
    {
        Console.WriteLine($"Stream response created with ID: {createUpdate.Response.Id}");
    }
    else if (streamResponse is StreamingResponseOutputTextDeltaUpdate textDelta)
    {
        Console.WriteLine($"Delta: {textDelta.Delta}");
    }
    else if (streamResponse is StreamingResponseOutputTextDoneUpdate textDoneUpdate)
    {
        text = textDoneUpdate.Text;
    }
    else if (streamResponse is StreamingResponseOutputItemDoneUpdate itemDoneUpdate)
    {
        if (annotation.Length == 0)
        {
            annotation = GetFormattedAnnotation(itemDoneUpdate.Item);
        }
    }
    else if (streamResponse is StreamingResponseErrorUpdate errorUpdate)
    {
        throw new InvalidOperationException($"The stream has failed: {errorUpdate.Message}");
    }
}
Console.WriteLine($"{text}{annotation}");

Asynchrones Beispiel:

ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);

string annotation = "";
string text = "";
CreateResponseOptions options = new()
{
    ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
    InputItems = { ResponseItem.CreateUserMessageItem("How many medals did the USA win in the 2024 summer olympics?") },
};
await foreach (StreamingResponseUpdate streamResponse in responseClient.CreateResponseStreamingAsync(options))
{
    if (streamResponse is StreamingResponseCreatedUpdate createUpdate)
    {
        Console.WriteLine($"Stream response created with ID: {createUpdate.Response.Id}");
    }
    else if (streamResponse is StreamingResponseOutputTextDeltaUpdate textDelta)
    {
        Console.WriteLine($"Delta: {textDelta.Delta}");
    }
    else if (streamResponse is StreamingResponseOutputTextDoneUpdate textDoneUpdate)
    {
        text = textDoneUpdate.Text;
    }
    else if (streamResponse is StreamingResponseOutputItemDoneUpdate itemDoneUpdate)
    {
        if (annotation.Length == 0)
        {
            annotation = GetFormattedAnnotation(itemDoneUpdate.Item);
        }
    }
    else if (streamResponse is StreamingResponseErrorUpdate errorUpdate)
    {
        throw new InvalidOperationException($"The stream has failed: {errorUpdate.Message}");
    }
}
Console.WriteLine($"{text}{annotation}");

1. Löschen Sie alle Ressourcen, die das Beispiel erstellt hat.

Synchrones Beispiel:

projectClient.AgentAdministrationClient.DeleteAgentVersionAsync(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

Asynchrones Beispiel:

await projectClient.AgentAdministrationClient.DeleteAgentVersionAsync(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

Erwartete Ausgabe

Im Folgenden sehen Sie ein Beispiel für die erwartete Ausgabe beim Ausführen des C#-Codes:

Response status: Completed
The London Underground currently has service disruptions on ...
Agent deleted

Allgemeine Websuche

Zugriffstoken abrufen:

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

Die empfohlene Methode zum Hinzufügen der Websuche besteht aus einer Toolbox, und fügen Sie die Toolbox dann als MCP-Tool an Ihren Agent an. Sehen Sie sich an, was eine Toolbox ist?

1. Erstellen Sie eine Toolbox, die das Websuchtool enthält:

   curl --request POST \
     --url "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/web-search-toolbox/versions?api-version=v1" \
           -H "Authorization: Bearer $AGENT_TOKEN" \
     -H "Content-Type: application/json" \
     --data '{
       "description": "Toolbox with the web search tool",
       "tools": [
         { "type": "web_search" }
       ]
     }'
   

   Die Toolbox stellt unter $FOUNDRY_PROJECT_ENDPOINT/toolboxes/web-search-toolbox/versions/<version>/mcp?api-version=v1 einen MCP-kompatiblen Endpunkt bereit, wobei <version> die vom vorherigen Aufruf zurückgegebene Version ist.

2. Erstellen Sie eine Remote-Tool-Projektverbindung, die auf den Toolbox-Endpunkt verweist, und verwenden Sie dabei ein Entra-Benutzertoken, damit die Identität des Aufrufers durchgereicht wird (Zielgruppe https://ai.azure.com).

   azd ai connection create web-search-toolbox-conn \
     --kind remote-tool \
     --target "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/web-search-toolbox/versions/<version>/mcp?api-version=v1" \
     --auth-type user-entra-token \
     --audience https://ai.azure.com
   

3. Erstellen Sie eine Antwort, die die Toolbox verwendet, indem Sie sie als MCP-Tool anfügen.

   curl --request POST \
     --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
     -H "Authorization: Bearer $AGENT_TOKEN" \
     -H "Content-Type: application/json" \
     --data '{
       "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
       "input": "Tell me about the latest news about AI",
       "tool_choice": "required",
       "tools": [
         {
           "type": "mcp",
           "server_label": "toolbox",
           "server_url": "'$FOUNDRY_PROJECT_ENDPOINT'/toolboxes/web-search-toolbox/versions/<version>/mcp?api-version=v1",
           "require_approval": "never",
           "project_connection_id": "web-search-toolbox-conn"
         }
       ]
     }'
   

Erwartete Ausgabe

Das folgende Beispiel zeigt die erwartete Ausgabe bei Verwendung des Websuchtools über die REST-API:

{
  "id": "resp_abc123xyz",
  "object": "response",
  "created_at": 1702345678,
  "status": "completed",
    "output": [
    {
            "id": "msg_abc123xyz",
      "type": "message",
            "role": "assistant",
            "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Here is a grounded response with citations.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://contoso.com/example-source",
              "start_index": 0,
              "end_index": 43
            }
          ]
        }
      ]
    }
  ]
}

Domänenbeschränkte Websuche

Zugriffstoken abrufen:

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

Die empfohlene Methode zum Hinzufügen der domänengeschränkten Websuche erfolgt über eine Toolbox, und fügen Sie die Toolbox dann als MCP-Tool an Ihren Agent an.

1. Erstellen Sie eine Toolbox, die das mit der Domäne eingeschränkte Websuchtool enthält:

   curl --request POST \
     --url "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/web-search-toolbox/versions?api-version=v1" \
           -H "Authorization: Bearer $AGENT_TOKEN" \
     -H "Content-Type: application/json" \
     --data '{
       "description": "Toolbox with the domain-restricted web search tool",
       "tools": [
         {
           "type": "web_search",
           "custom_search_configuration": {
             "project_connection_id": "'$BING_CUSTOM_SEARCH_PROJECT_CONNECTION_ID'",
             "instance_name": "'$BING_CUSTOM_SEARCH_INSTANCE_NAME'"
           }
         }
       ]
     }'
   

2. Erstellen Sie eine Remote-Tool-Projektverbindung, die auf den Toolbox-Endpunkt verweist, und verwenden Sie dabei ein Entra-Benutzertoken, damit die Identität des Aufrufers durchgereicht wird (Zielgruppe https://ai.azure.com).

   azd ai connection create web-search-toolbox-conn \
     --kind remote-tool \
     --target "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/web-search-toolbox/versions/<version>/mcp?api-version=v1" \
     --auth-type user-entra-token \
     --audience https://ai.azure.com
   

3. Erstellen Sie eine Antwort, die die Toolbox verwendet, indem Sie sie als MCP-Tool anfügen.

   curl --request POST \
     --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
   -H "Authorization: Bearer $AGENT_TOKEN" \
     -H "Content-Type: application/json" \
     --data '{
       "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
       "input": "Tell me about the latest news about AI",
       "tool_choice": "required",
       "tools": [
         {
           "type": "mcp",
           "server_label": "toolbox",
           "server_url": "'$FOUNDRY_PROJECT_ENDPOINT'/toolboxes/web-search-toolbox/versions/<version>/mcp?api-version=v1",
           "require_approval": "never",
           "project_connection_id": "web-search-toolbox-conn"
         }
       ]
     }'
   

Verwenden des Websuchtools mit TypeScript

Im folgenden TypeScript-Beispiel wird veranschaulicht, wie ein Agent mit dem Websuchtool erstellt wird. Ein Beispiel, das JavaScript verwendet, finden Sie im Beispielcode im Azure SDK für JavaScript-Repository auf GitHub.

Erstellen Sie einen toolboxgestützten Agenten

Dieses Beispiel zeigt, wie Prompt-Agent-Operationen mithilfe des Websuchtools ausgeführt werden. Es zeigt, wie Sie einen Agent mit Websuchfunktionen erstellen, eine Abfrage senden, um das Web zu durchsuchen, und dann Ressourcen bereinigen.

Das Websuche-Tool verwendet Grounding mit Bing, das zusätzliche Kosten und Bedingungen hat: Nutzungsbedingungen und Datenschutzbestimmungen. Kundendaten fließen außerhalb der Azure Compliancegrenze.

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

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

export async function main(): Promise<void> {
  // Create AI Project client
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  console.log("Creating a toolbox with the web search tool...");

  // 1. Add the web search 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(
    "web-search-toolbox",
    [
      {
        type: "web_search",
        user_location: {
          type: "approximate",
          country: "GB",
          city: "London",
          region: "London",
        },
      },
    ],
    { description: "Toolbox with the web search 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 web-search-toolbox-conn \
  //      --kind remote-tool \
  //      --target "<toolboxMcpUrl>" \
  //      --auth-type user-entra-token \
  //      --audience https://ai.azure.com
  const toolboxConnectionName = "web-search-toolbox-conn";

  // 4. Attach the toolbox to a prompt agent as an MCP tool.
  const agent = await project.agents.createVersion("agent-web-search", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "You are a helpful assistant that can search the web",
    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})`);

  // Create a conversation for the agent interaction
  const conversation = await openai.conversations.create();
  console.log(`Created conversation (id: ${conversation.id})`);

  // Send a query to search the web
  console.log("\nSending web search query...");
  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "Show me the latest London Underground service updates",
    },
    {
    body: { agent_reference: { name: agent.name, type: "agent_reference" } },
    },
  );
  console.log(`Response: ${response.output_text}`);

  // Clean up resources
  console.log("\nCleaning up resources...");
  await openai.conversations.delete(conversation.id);
  console.log("Conversation deleted");

  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nWeb search sample completed!");
}

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

Erwartete Ausgabe

Das folgende Beispiel zeigt die erwartete Ausgabe beim Ausführen des TypeScript-Codes:

Agent created (id: 12345, name: agent-web-search, version: 1)
Response: The agent returns a grounded response that includes citations.
Agent deleted

Domänenbeschränkte Suche mit benutzerdefinierter Bing-Suche

Das folgende Beispiel zeigt, wie Sie die Websuche auf bestimmte Domänen beschränken, indem Sie das Websuchtool direkt mit einer Bing Custom Search-Konfiguration an den Agent anfügen.

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 BING_CUSTOM_SEARCH_CONNECTION_ID = "your_bing_custom_search_connection_id";
const BING_CUSTOM_SEARCH_INSTANCE_NAME = "your_bing_custom_search_instance_name";

export async function main(): Promise<void> {
  // Create AI Project client
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Create an agent with the web search tool configured for Bing Custom Search
  const agent = await project.agents.createVersion("agent-web-search-custom", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "You are a helpful assistant that can search the web and bing",
    tools: [
      {
        type: "web_search",
        custom_search_configuration: {
          project_connection_id: BING_CUSTOM_SEARCH_CONNECTION_ID,
          instance_name: BING_CUSTOM_SEARCH_INSTANCE_NAME,
        },
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Send a query and stream the response
  const stream = openai.responses.stream(
    {
      input: "What are the latest updates from Microsoft Learn?",
      tool_choice: "required",
    },
    {
      body: { agent_reference: { name: agent.name, type: "agent_reference" } },
    },
  );

  // Process streaming events as they arrive
  for await (const event of stream) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_item.done") {
      if (event.item.type === "message" && event.item.content) {
        const lastContent = event.item.content[event.item.content.length - 1];
        if (lastContent.type === "output_text" && lastContent.annotations) {
          for (const annotation of lastContent.annotations) {
            if (annotation.type === "url_citation") {
              console.log(`\nURL Citation: ${annotation.url}`);
            }
          }
        }
      }
    } else if (event.type === "response.completed") {
      console.log("\n\nResponse completed!");
    }
  }

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");
}

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

Erwartete Ausgabe

Agent created (id: abc123, name: agent-web-search-custom, version: 1)

URL Citation: https://your-allowed-domain.com/article

Response completed!
Agent deleted

Tiefe Recherche mit Websuche

Das folgende Beispiel zeigt, wie Sie das o3-deep-research Modell mit dem Vorschautool für die direkte Websuche verwenden. Leiten Sie die Websuche nicht über eine Toolbox für die umfassende Recherche weiter, da das Modell das Tool für die direkte Antwortwebsuche benötigt.

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

export async function main(): Promise<void> {
  // Create AI Project client
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Create a prompt agent with the direct web search preview tool
  const agent = await project.agents.createVersion("agent-deep-research", {
    kind: "prompt",
    model: "o3-deep-research",
    instructions: "You are a helpful assistant that can search the web",
    tools: [{ type: "web_search_preview" }],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Create a conversation for the agent interaction
  const conversation = await openai.conversations.create();
  console.log(`Created conversation (id: ${conversation.id})`);

  // Send a query to search the web
  const stream = openai.responses.stream(
    {
      conversation: conversation.id,
      input: "What are the latest advancements in quantum computing?",
    },
    {
      body: { agent_reference: { name: agent.name, type: "agent_reference" } },
    },
  );

  // Process streaming events as they arrive
  for await (const event of stream) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.completed") {
      console.log("\n\nResponse completed!");
      console.log(`Full response: ${event.response.output_text}`);
    }
  }

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");
}

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

Erwartete Ausgabe

Agent created (id: abc123, name: agent-deep-research, version: 1)
Created conversation (id: conv_456)

Response completed!
Full response: Recent advancements in quantum computing include ...
Agent deleted

Verwenden der Websuche in einem Java Agent

Fügen Sie die Abhängigkeit zu Ihrem pom.xml hinzu:

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

Erstellen eines Agents mit Websuche

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.ai.agents.models.WebSearchTool;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.Collections;

public class WebSearchExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();

        // Create web search tool with user location
        WebSearchTool webSearchTool = new WebSearchTool();

        // Create agent with web search tool
        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini")
            .setInstructions("You are a helpful assistant that can search the web for current information.")
            .setTools(Collections.singletonList(webSearchTool));

        AgentVersionDetails agent = agentsClient.createAgentVersion("web-search-agent", agentDefinition);
        System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());

        // Create a response
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions().setAgentReference(agentReference),
            ResponseCreateParams.builder()
                .input("What are the latest trends in renewable energy?"));

        System.out.println("Response: " + response.output());

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
    }
}

Erwartete Ausgabe

Agent created: web-search-agent (version 1)
Response: [ResponseOutputItem with web search results about renewable energy trends ...]