Средство поиска в Интернете

Инструмент поиска в Интернете в Службе агента Foundry позволяет модели агента Foundry извлекать и подкреплять ответы информацией в режиме реального времени из общедоступного Интернета перед созданием выходных данных. При активировании этой функции модель может возвращать актуальные ответы со встроенными цитатами, помогая создавать агентов, предоставляющих текущую фактическую информацию пользователям.

Важно

  • Веб-поиск использует опорный метод с поиском Bing и пользовательские запросы Bing, которые являются услугами первого порядка, урегулируются данными условиями использования службы Grounding Bing и заявлением о конфиденциальности Microsoft.
  • Дополнение Microsoft Data Protection не применяется к данным, отправленным для Grounding с поиском Bing и Grounding с пользовательским поиском Bing. При использовании приземления с поиском Bing и заземлением с пользовательским поиском Bing передача данных происходит вне соответствия и географических границ.
  • Использование обоснования с поиском Bing и обоснования с пользовательским поиском Bing влечет за собой расходы. См. ценообразование для получения подробной информации.
  • Для получения дополнительной информации о том, как администраторы Azure могут управлять доступом к использованию веб-поиска, см. в разделе управления.

Поддержка использования

В следующей таблице показана поддержка пакета SDK и настройки.

поддержка Microsoft Foundry пакет SDK Python Пакет SDK для C# Пакет SDK для JavaScript пакет SDK Java REST API Базовая настройка агента Настройка стандартного агента
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Необходимые условия

  • Базовая или стандартная среда агента
  • Последний пакет SDK. Пакет SDK .NET в настоящее время находится в предварительной версии. Дополнительные сведения см. в кратком руководстве .
  • Azure учетные данные, настроенные для проверки подлинности (например, DefaultAzureCredential).
  • URL-адрес конечной точки проекта Foundry и имя развертывания модели.

Примеры кода

Примечание

Ознакомьтесь с рекомендациями по оптимизации использования инструментов.

В следующем примере показано, как настроить клиент ИИ Project с помощью библиотеки удостоверений Azure для проверки подлинности.

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

Ожидаемые выходные данные

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

В следующем примере показано, как ограничить поиск в Интернете определенным доменам с помощью экземпляра пользовательского поиска Bing. Этот подход позволяет вам контролировать, какие веб-сайты может искать ваш агент.

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

Ожидаемые выходные данные

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

Закрепление с помощью пользовательского поиска Bing — это мощное средство, которое можно использовать для выбора подпространства в Интернете, чтобы ограничить базу знаний вашего агента. Ниже приведены несколько советов, которые помогут вам воспользоваться преимуществами этой возможности:

  • Если вы владеете общедоступным сайтом, который вы хотите включить в поиск, но Bing не индексировался, ознакомьтесь с рекомендациями веб-мастера Bing для получения индексации сайта. Документация для веб-мастеров также содержит сведения о том, как настроить обход сайта с помощью Bing, если индекс устарел.
  • Для создания конфигурации требуется как минимум роль Contributor для ресурса Bing Custom Search.
  • Вы можете заблокировать определенные домены и выполнить поиск по остальным веб-сайтам (например, сайт конкурента).
  • Использование поисковой системы Bing Custom возвращает результаты только для доменов и веб-страниц, которые являются общедоступными и индексированы в Bing.
  • Можно указать различные уровни детализации:
    • Домен (например, https://www.microsoft.com)
    • Домен и путь (например, https://www.microsoft.com/surface)
    • Веб-страница (например, https://www.microsoft.com/en-us/p/surface-earbuds/8r9cpq146064)

В следующем примере показано, как использовать o3-deep-research модель с средством поиска в Интернете. Этот подход заменяет нерекомендуемое средство Глубокого исследования, что позволяет выполнять многофакторные исследования с помощью общедоступных веб-данных непосредственно через средство поиска в Интернете.

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

Общий веб-поиск

В этом примере вы используете агента для выполнения веб-поиска в заданном местоположении. В примере в этом разделе используются синхронные вызовы. Для асинхронного примера см. пример кода в репозитории Azure SDK для .NET на 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);

Ожидаемые выходные данные

Ниже приведен пример ожидаемых выходных данных при выполнении кода C#:

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

Чтобы разрешить вашему агенту использовать веб-поиск с ориентацией на экземпляр пользовательского поиска Bing.

  1. Сначала создайте клиент проекта и определите значения, используемые в следующих шагах.
// 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. Создайте агента, способного выполнять поиск в Интернете на основе технологии привязки с использованием экземпляра пользовательского поиска Bing.

Синхронный пример:

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

Асинхронный пример:

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. Чтобы получить отформатированную заметку, мы создали этот метод GetFormattedAnnotation.
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. Задайте вопрос и передавайте ответ в потоковом режиме.

Синхронный пример:

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

Асинхронный пример:

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. Наконец, удалите все ресурсы, созданные в этом примере.

Синхронный пример:

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

Асинхронный пример:

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

Ожидаемые выходные данные

Ниже приведен пример ожидаемых выходных данных при выполнении кода C#:

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

Общий веб-поиск

Получение токена доступа:

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

В следующем примере показано, как создать ответ с помощью агента с включенным средством поиска в Интернете.

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

Ожидаемые выходные данные

В следующем примере показаны ожидаемые выходные данные при использовании средства поиска в Интернете через 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
            }
          ]
        }
      ]
    }
  ]
}

Поиск с ограниченным доступом к домену

Получение токена доступа:

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

В следующем примере показано, как создать ответ с помощью агента с включенным средством поиска в Интернете.

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

Использование средства поиска в Интернете с TypeScript

В следующем примере TypeScript показано, как создать агент с помощью средства поиска в Интернете. Пример использования JavaScript см. в примере кода извлеченного из репозитория Azure SDK для JavaScript на 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);
});

Ожидаемые выходные данные

В следующем примере показаны ожидаемые выходные данные при выполнении кода TypeScript:

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

Использование веб-поиска в агенте Java

Добавьте зависимость в вашу pom.xml:

<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());
    }
}

Ожидаемые выходные данные

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

Настройка средства поиска в Интернете

При создании агента можно настроить поведение поиска в Интернете.

  • user_location: помогает получить результаты возврата веб-поиска, относящиеся к географическому региону пользователя. Используйте приблизительное расположение, если требуется, чтобы результаты локализованы в стране, регионе или городе.
  • search_context_size: определяет, сколько пространства контекстного окна используется для поиска. Поддерживаемые значения: low, mediumи high. Значение по умолчанию — medium.

Вопросы безопасности и конфиденциальности

  • Обрабатывать результаты поиска в Интернете как ненадежные входные данные. Проверка и очистка данных перед использованием данных в подчиненных системах.
  • Избегайте отправки секретов или конфиденциальных персональных данных в запросах, которые могут быть перенаправлены во внешние службы.
  • Ознакомьтесь с условиями, конфиденциальностью и границами данных в разделе предварительной версии этой статьи, прежде чем включить веб-поиск в рабочей среде.

Известные ограничения

Сведения о поведении поиска в Интернете и ограничениях в API ответов см. в веб-поиске с помощью API ответов.

Устранение неполадок

Проблема Причина Разрешение
Веб-поиск не используется, и ссылки не отображаются Модель не определила необходимость поиска в Интернете Обновите инструкции, чтобы явно позволить поиск в интернете для получения актуальной информации и задать запрос, требующий самой свежей информации.
Сбой запросов после включения веб-поиска Поиск в Интернете отключен на уровне подписки Попросите администратора включить поиск в Интернете. См. элемент управления "Администратор" для средства поиска в Интернете.
Запросы REST возвращают ошибки проверки подлинности Маркер носителя отсутствует, истек или имеет недостаточно разрешений. Обновите маркер и подтвердите доступ к проекту и агенту.
Поиск возвращает устаревшие сведения Веб-содержимое не недавно индексировано Уточните запрос, чтобы явно запросить самую актуальную информацию. Результаты зависят от расписания индексирования Bing.
Нет результатов для определенных разделов Запрос слишком узкий или содержимое не индексировано Расширьте поисковый запрос. Некоторые нишевые темы могут иметь ограниченное веб-покрытие.
Ошибки ограничения скорости (429) Слишком много запросов за короткий период времени Реализуйте экспоненциальную логику обратной передачи и повтора. Рассмотрите возможность равномерного распределения запросов.
Несогласованное форматирование цитат Формат ответа зависит от типа запроса Стандартизируйте обработку ссылок в коде приложения. Анализ встроенных и ссылочных ссылок.
Средство недоступно для развертывания Ограничения региона или модели Убедитесь, что поиск в Интернете доступен в вашем регионе и при развертывании модели. Лучшие практики применения инструментов.

Управление администратором средства поиска в Интернете

Вы можете включить или отключить средство поиска в Интернете в службе агента Foundry на уровне подписки с помощью Azure CLI. Этот параметр применяется ко всем учетным записям в указанной подписке.

Необходимые условия

Перед выполнением следующих команд убедитесь, что вы:

  1. Установите Azure CLI.
  2. Вы вошли в Azure, используя az login.
  3. Иметь доступ владельца или участника к подписке.

Чтобы отключить средство поиска в Интернете для всех учетных записей в подписке, выполните следующую команду:

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

Эта команда отключает поиск в Интернете во всех учетных записях в указанной подписке.

Чтобы включить средство поиска в Интернете, выполните следующую команду:

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

Эта команда включает функции поиска в Интернете для всех учетных записей в подписке.

Дальнейшие действия