Websuchtool

Das Websuchtool im Foundry Agent Service ermöglicht es dem Agenten-Foundry-Modell, Antworten mit Echtzeitinformationen aus dem öffentlichen Web abzurufen und zu verankern, bevor die Ausgabe generiert wird. Wenn diese Option aktiviert ist, kann das Modell aktuelle Antworten mit Zitate in Text zurückgeben und Ihnen dabei helfen, Agenten zu erstellen, die aktuelle, faktenbezogene Informationen für Benutzer bereitstellen.

Wichtig

  • Die Websuche verwendet Grounding mit Bing-Suche und Grounding mit der benutzerdefinierten Bing-Suche, die First Party Consumption Services sind und durch diese Grounding mit Bing-Nutzungsbedingungen und die Microsoft-Datenschutzbestimmungen geregelt werden.
  • Der Microsoft Datenschutz-Zusatz gilt nicht für Daten, die an Grounding mit Bing Search und Grounding mit Bing Custom Search gesendet werden. Wenn Sie Grounding mit Bing Search und Grounding mit der benutzerdefinierten Bing-Suche verwenden, erfolgen Datenübertragungen außerhalb von Vorschriften und geografischen Grenzen.
  • Die Verwendung von Grounding mit Bing Search und Grounding mit Bing Custom Search kann Kosten verursachen. Details finden Sie unter "Preise ".
  • Im Abschnitt Management finden Sie Informationen dazu, wie Azure Administratoren den Zugriff auf die Verwendung der Websuche verwalten können.

Verwendungsunterstützung

Die folgende Tabelle zeigt die SDK- und Setupunterstützung.

Microsoft Foundry-Unterstützung Python SDK C# SDK JavaScript SDK Java SDK REST-API Grundlegendes Agent-Setup Standard-Agenten-Einrichtung
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Voraussetzungen

  • Eine grundlegende oder Standard-Agent-Umgebung
  • Das neueste SDK-Paket. Das .NET SDK ist derzeit als Vorschauversion verfügbar. Details finden Sie in der Schnellstartanleitung .
  • für die Authentifizierung konfigurierte Azure-Anmeldeinformationen (z. B. DefaultAzureCredential).
  • Die URL des Foundry-Projektendpunkts und ein Modellbereitstellungsname.

Codebeispiele

Hinweis

Informationen zur Optimierung der Toolverwendung finden Sie unter bewährten Methoden .

Das folgende Beispiel zeigt, wie Sie den KI-Project-Client mithilfe der Azure Identitätsbibliothek für die Authentifizierung einrichten.

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.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

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.

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

# 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()

# Create an agent with the web search tool and custom search configuration
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(
                custom_search_configuration=WebSearchConfiguration(
                    project_connection_id=BING_CUSTOM_SEARCH_CONNECTION_ID,
                    instance_name=BING_CUSTOM_SEARCH_INSTANCE_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.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

Die Einrichtung einer Grundlage mit der benutzerdefinierten Bing-Suche ist ein leistungsstarkes Tool, mit dem Sie einen Unterbereich des Webs auswählen können, um das Grundlagenwissen Ihres Agenten 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.
  • Sie benötigen mindestens die Rolle "Mitwirkender" für die Bing Custom Search-Ressource, um eine Konfiguration zu erstellen.
  • Sie können bestimmte Domänen blockieren und eine Suche für den Rest des Webs ausführen (z. B. die Website eines Wettbewerbers).
  • Die Grundlage für die benutzerdefinierte Bing-Suche gibt nur Ergebnisse für Domänen und Webseiten zurück, die von Bing öffentlich und indiziert sind.
  • 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. )

Das folgende Beispiel zeigt, wie Sie das o3-deep-research Modell mit dem Websuchtool verwenden. Dieser Ansatz ersetzt das veraltete Deep Research-Tool und ermöglicht eine mehrstufige Recherche mithilfe von öffentlichen Webdaten direkt über das Websuchtool.

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 agent with web search tool using o3-deep-research model
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.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

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.

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

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());
  1. Erstellen Sie einen Agent, der die Websuche mit der 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. Zum Abrufen der formatierten Anmerkung haben wir die GetFormattedAnnotation Methode erstellt.
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 "";
}
  1. 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 schließlich alle Ressourcen, die wir in diesem Beispiel erstellt haben.

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)

Das folgende Beispiel zeigt, wie Sie eine Antwort mithilfe eines Agents erstellen, der das Websuchtool aktiviert hat.

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": "web_search"
      }
    ]
  }'

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_text": "Here is a grounded response with citations.",
  "output_items": [
    {
      "type": "message",
      "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)

Das folgende Beispiel zeigt, wie Sie eine Antwort mithilfe eines Agents erstellen, der das Websuchtool aktiviert hat.

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": "web_search",
        "custom_search_configuration": [
          {
            "project_connection_id": "'$BING_CUSTOM_SEARCH_PROJECT_CONNECTION_ID'",
            "instance_name": "'$BING_CUSTOM_SEARCH_INSTANCE_NAME'",
          }
        ]
      }
    ]
  }'

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 sample code im Azure SDK für JavaScript-Repositories auf GitHub.

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

/**
 * This sample demonstrates how to run Prompt Agent operations using the Web Search Tool.
 *
 * @summary This sample demonstrates how to create an agent with web search capabilities,
 * send a query to search the web, and clean up resources.
 *
 * @warning Web Search tool uses Grounding with Bing, which has additional costs and terms: [terms of use](https://www.microsoft.com/bing/apis/grounding-legal-enterprise) and [privacy statement](https://go.microsoft.com/fwlink/?LinkId=521839&clcid=0x409). Customer data will flow outside the Azure compliance boundary. Learn more [here](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/web-search?pivots=rest-api)
 *
 * @azsdk-weight 100
 */

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 agent with web search tool...");

  // Create Agent with web search 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: "web_search",
        user_location: {
          type: "approximate",
          country: "GB",
          city: "London",
          region: "London",
        },
      },
    ],
  });
  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: { 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

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.0.0</version>
</dependency>

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
        WebSearchPreviewTool 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 ...]

Konfigurieren des Websuchtools

Sie können websuchverhalten konfigurieren, wenn Sie Ihren Agent erstellen.

  • user_location: Unterstützt die Websuche beim Zurückgeben von Ergebnissen, die für die Geografie eines Benutzers relevant sind. Verwenden Sie einen ungefähren Standort, wenn Sie Ergebnisse in ein Land/eine Region/Stadt lokalisieren möchten.
  • search_context_size: Steuert, wie viel Kontextfenster für die Suche verwendet werden soll. Unterstützte Werte sind low, mediumund high. Der Standardwert ist medium.

Überlegungen zu Sicherheit und Datenschutz

  • Behandeln von Websuchergebnissen als nicht vertrauenswürdige Eingabe. Überprüfen und berigen Sie Daten, bevor Sie sie in nachgeschalteten Systemen verwenden.
  • Vermeiden Sie das Senden geheimer oder vertraulicher personenbezogener Daten in Aufforderungen, die möglicherweise an externe Dienste weitergeleitet werden.
  • Überprüfen Sie die Begriffe, Datenschutz und Datenbegrenzungsnotizen im Vorschauabschnitt dieses Artikels, bevor Sie die Websuche in der Produktion aktivieren.

Bekannte Einschränkungen

Informationen zu Websuchverhalten und -einschränkungen in der Antwort-API finden Sie unter Websuche mit der Antwort-API.

Problembehandlung

Angelegenheit Ursache Auflösung
Die Websuche wird nicht verwendet, und es werden keine Zitate angezeigt. Das Modell hat nicht festgestellt, dass die Websuche erforderlich war. Aktualisieren Sie Ihre Anweisungen, um die Websuche für aktuelle Fragen explizit zuzulassen, und formulieren Sie eine Suchanfrage, die aktuelle Informationen erfordert.
Anforderungen schlagen nach dem Aktivieren der Websuche fehl Die Websuche ist auf Abonnementebene deaktiviert. Bitten Sie einen Administrator, die Websuche zu aktivieren. Siehe Administratorsteuerelement für das Websuchtool.
REST-Anforderungen geben Authentifizierungsfehler zurück Bearer-Token fehlt, ist abgelaufen oder weist unzureichende Berechtigungen auf. Aktualisieren Sie Ihr Token, und bestätigen Sie den Zugriff auf das Projekt und den Agent.
Suche gibt veraltete Informationen zurück. Webinhalte, die nicht kürzlich indiziert wurden Verfeinern Sie Ihre Abfrage, um die neuesten Informationen explizit anzufordern. Die Ergebnisse hängen vom Indizierungszeitplan von Bing ab.
Keine Ergebnisse für bestimmte Themen Abfrage zu schmal oder Inhalt nicht indiziert Erweitern Sie Ihre Suchabfrage. Einige Nischenthemen haben möglicherweise eine begrenzte Webabdeckung.
Fehler beim Einschränken der Rate (429) Zu viele Anforderungen in einem kurzen Zeitraum Implementieren Sie exponentielle Backoff- und Wiederholungslogik. Erwägen Sie, die Anforderungen zeitlich zu staffeln.
Inkonsistente Zitatformatierung Das Antwortformat variiert je nach Abfragetyp. Standardisieren sie die Zitatbehandlung in Ihrem Anwendungscode. Analysieren Sie sowohl Inline- als auch Referenzstil-Zitate.
Tool nicht für die Bereitstellung verfügbar Regionale oder Modellbeschränkungen Vergewissern Sie sich, dass die Websuche in Ihrer Region und mit Ihrer Modellbereitstellung verfügbar ist. Überprüfen Sie die bewährten Methoden des Tools.

Administratorsteuerelement für das Websuchtool

Sie können das Websuchtool im Foundry Agent Service auf Abonnementebene aktivieren oder deaktivieren, indem Sie Azure CLI verwenden. Diese Einstellung gilt für alle Konten innerhalb des angegebenen Abonnements.

Voraussetzungen

Bevor Sie die folgenden Befehle ausführen, stellen Sie sicher, dass Sie:

  1. Azure CLI installiert haben.
  2. Sind mit az login bei Azure angemeldet.
  3. Besitzen Sie Besitzer- oder Mitwirkenderzugriff auf das Abonnement.

Führen Sie den folgenden Befehl aus, um das Websuchtool für alle Konten in einem Abonnement zu deaktivieren:

az feature register \
  --name OpenAI.BlockedTools.web_search \
  --namespace Microsoft.CognitiveServices \
  --subscription "<subscription-id>"

Mit diesem Befehl wird die Websuche für alle Konten im angegebenen Abonnement deaktiviert.

Führen Sie den folgenden Befehl aus, um das Websuchtool zu aktivieren:

az feature unregister \
  --name OpenAI.BlockedTools.web_search \
  --namespace Microsoft.CognitiveServices \
  --subscription "<subscription-id>"

Mit diesem Befehl können Websuchfunktionen für alle Konten im Abonnement aktiviert werden.

Nächste Schritte

Bewährte Methoden zum Überprüfen des Tools

Einrichten einer Agentumgebung

  • Last updated on