Agentes de aterramento com ferramentas de pesquisa Bing

Os exemplos seguintes demonstram como criar um agente com Grounding com as ferramentas de pesquisa do Bing, e como usar o agente para responder a perguntas dos utilizadores.

Aterramento com a Pesquisa Bing

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    BingGroundingTool,
    BingGroundingSearchToolParameters,
    BingGroundingSearchConfiguration,
)

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
BING_CONNECTION_NAME = "my-bing-connection"

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

# Get connection ID from connection name
bing_connection = project.connections.get(BING_CONNECTION_NAME)

agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="You are a helpful assistant.",
        tools=[
            BingGroundingTool(
                bing_grounding=BingGroundingSearchToolParameters(
                    search_configurations=[
                        BingGroundingSearchConfiguration(
                            project_connection_id=bing_connection.id
                        )
                    ]
                )
            )
        ],
    ),
    description="You are a helpful agent.",
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

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

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

O que este código faz

Este exemplo cria um agente com aterramento usando a ferramenta Bing Search, que pode recuperar informação em tempo real da web. Quando executas o código:

1. Cria um AIProjectClient e autentica usando as suas credenciais Azure.
2. Cria um agente com a ferramenta de suporte do Bing configurada através da sua conexão Bing.
3. Envia uma consulta sobre a data de hoje e o tempo em Seattle.
4. O agente utiliza a ferramenta de grounding Bing para pesquisar na web e transmite a resposta.
5. Extrai e mostra citações de URL dos resultados de pesquisa.

Entradas necessárias

• Atualiza as PROJECT_ENDPOINT constantes e BING_CONNECTION_NAME no código com os teus valores.
• Azure credenciais configuradas para DefaultAzureCredential.

Produção esperada

Agent created (id: asst_abc123, name: MyAgent, version: 1)
Follow-up response created with ID: resp_xyz789
Delta: Today
Delta: 's date
Delta:  is December 12, 2025...
Follow-up response done!
URL Citation: https://www.weather.gov/seattle/
Follow-up completed!
Full response: Today's date is December 12, 2025, and the weather in Seattle is...

Aterramento com Pesquisa Personalizada Bing (pré-visualização)

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    BingCustomSearchPreviewTool,
    BingCustomSearchToolParameters,
    BingCustomSearchConfiguration,
)

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
CUSTOM_SEARCH_CONNECTION_NAME = "my-custom-search-connection"
CUSTOM_SEARCH_INSTANCE_NAME = "my-custom-search-instance"

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

# Get connection ID from connection name
bing_custom_connection = project.connections.get(CUSTOM_SEARCH_CONNECTION_NAME)

bing_custom_search_tool = BingCustomSearchPreviewTool(
    bing_custom_search_preview=BingCustomSearchToolParameters(
        search_configurations=[
            BingCustomSearchConfiguration(
                project_connection_id=bing_custom_connection.id,
                instance_name=CUSTOM_SEARCH_INSTANCE_NAME,
            )
        ]
    )
)

agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="""You are a helpful agent that can use Bing Custom Search tools to assist users. 
        Use the available Bing Custom Search tools to answer questions and perform tasks.""",
        tools=[bing_custom_search_tool],
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

user_input = input(
    "Enter your question for the Bing Custom Search agent " "(e.g., 'Tell me more about foundry agent service'): \n"
)

# Send initial request that will trigger the Bing Custom Search tool
stream_response = openai.responses.create(
    stream=True,
    input=user_input,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

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}, "
                            f"Start index: {annotation.start_index}, "
                            f"End index: {annotation.end_index}"
                        )
    elif event.type == "response.completed":
        print(f"\nFollow-up completed!")
        print(f"Full response: {event.response.output_text}")

O que este código faz

Este exemplo cria um agente com a ferramenta Grounding with Bing Custom Search que pesquisa dentro de um conjunto configurável de domínios web públicos. Quando executas o código:

1. Cria um AIProjectClient e autentica usando as suas credenciais Azure.
2. Cria um agente com a ferramenta Bing Custom Search configurada usando a sua instância de pesquisa personalizada.
3. Solicita entrada do utilizador solicitando informação sobre tópicos específicos dentro dos seus domínios configurados.
4. O agente utiliza a ferramenta Bing Custom Search para pesquisar apenas nos domínios especificados e transmite a resposta.
5. Extrai e mostra citações de URL com posições de início e fim dos resultados de pesquisa personalizados.

Entradas necessárias

• Atualize as constantes PROJECT_ENDPOINT, CUSTOM_SEARCH_CONNECTION_NAME e CUSTOM_SEARCH_INSTANCE_NAME no código com os seus valores.
• Azure credenciais configuradas para DefaultAzureCredential.
• Entrada do utilizador em tempo de execução.

Produção esperada

Agent created (id: asst_abc123, name: MyAgent, version: 1)
Enter your question for the Bing Custom Search agent (e.g., 'Tell me more about foundry agent service'):
Tell me more about foundry agent service
Follow-up response created with ID: resp_xyz789
Delta: Microsoft
Delta:  Foundry
Delta:  Agent Service...
Follow-up response done!
URL Citation: https://learn.microsoft.com/azure/ai-foundry/agents, Start index: 45, End index: 120
Follow-up completed!
Full response: Microsoft Foundry Agent Service enables you to build...

Os exemplos seguintes de C# demonstram como criar um agente com Grounding com a ferramenta Bing Search, e como usar o agente para responder a perguntas dos utilizadores. Estes exemplos usam chamadas síncronas para simplificar. Para exemplos assíncronos, consulte as amostras de agentes C#.

Para permitir que o seu Agente utilize a API de pesquisa do Bing, use BingGroundingTool.

Aterramento com a Pesquisa Bing

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var bingConnectionName = "my-bing-connection";

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

// Get connection ID from connection name
AIProjectConnection bingConnection = projectClient.Connections.GetConnection(connectionName: bingConnectionName);

// Create the agent version with Bing grounding tool
BingGroundingTool bingGroundingAgentTool = new(new BingGroundingSearchToolOptions(
  searchConfigurations: [new BingGroundingSearchConfiguration(projectConnectionId: bingConnection.Id)]
    )
);
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
{
    Instructions = "You are a helpful agent.",
    Tools = { bingGroundingAgentTool, }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

// Output the agent version info
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);

ResponseResult response = responseClient.CreateResponse("How does wikipedia explain Euler's Identity?");

// Extract and format URL citation annotations
string citation = "";
foreach (ResponseItem item in response.OutputItems)
{
    if (item is MessageResponseItem messageItem)
    {
        foreach (ResponseContentPart content in messageItem.Content)
        {
            foreach (ResponseMessageAnnotation annotation in content.OutputTextAnnotations)
            {
                if (annotation is UriCitationMessageAnnotation uriAnnotation)
                {
                    citation = $" [{uriAnnotation.Title}]({uriAnnotation.Uri})";
                }
            }
        }
    }
}

// Validate and print the response
Assert.That(response.Status, Is.EqualTo(ResponseStatus.Completed));
Console.WriteLine($"{response.GetOutputText()}{citation}");

// Clean up resources by deleting the agent version
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

O que este código faz

Este exemplo cria um agente que utiliza a ferramenta Grounding with Bing Search e demonstra o tratamento de respostas síncronas. Quando executas o código:

1. Cria um AIProjectClient usando o endpoint do seu projeto.
2. Recupera a configuração da ligação Bing do seu projeto.
3. Cria um agente com a ferramenta de base Bing configurada.
4. Envia uma consulta a perguntar como a Wikipédia explica a Identidade de Euler.
5. O agente utiliza a ferramenta Bing Grounding para efetuar a pesquisa e retorna resultados formatados com citações de URLs.
6. Limpa eliminando a versão do agente.

Entradas necessárias

• Atualiza as projectEndpoint constantes e bingConnectionName no código com os teus valores.
• Azure credenciais configuradas para DefaultAzureCredential.

Produção esperada

Euler's identity is considered one of the most elegant equations in mathematics... [Euler's identity - Wikipedia](https://en.wikipedia.org/wiki/Euler%27s_identity)

Integração com o Bing em cenários de transmissão

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var bingConnectionName = "my-bing-connection";

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

// Get connection ID from connection name
AIProjectConnection bingConnection = projectClient.Connections.GetConnection(connectionName: bingConnectionName);

// Create the agent version with Bing grounding tool
BingGroundingTool bingGroundingAgentTool = new(new BingGroundingSearchToolOptions(
  searchConfigurations: [new BingGroundingSearchConfiguration(projectConnectionId: bingConnection.Id)]
    )
);
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
{
    Instructions = "You are a helpful agent.",
    Tools = { bingGroundingAgentTool }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

// Stream the response from the agent version
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);

string annotation = "";
string text = "";

// Parse the streaming response and output the results
foreach (StreamingResponseUpdate streamResponse in responseClient.CreateResponseStreaming("How does wikipedia explain Euler's Identity?"))
{
    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)
        {
            // Extract and format URL citation annotations
            if (itemDoneUpdate.Item is MessageResponseItem messageItem)
            {
                foreach (ResponseContentPart content in messageItem.Content)
                {
                    foreach (ResponseMessageAnnotation messageAnnotation in content.OutputTextAnnotations)
                    {
                        if (messageAnnotation is UriCitationMessageAnnotation uriAnnotation)
                        {
                            annotation = $" [{uriAnnotation.Title}]({uriAnnotation.Uri})";
                        }
                    }
                }
            }
        }
    }
    else if (streamResponse is StreamingResponseErrorUpdate errorUpdate)
    {
        throw new InvalidOperationException($"The stream has failed: {errorUpdate.Message}");
    }
}
Console.WriteLine($"{text}{annotation}");

// Clean up resources by deleting the agent version
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

O que este código faz

Este exemplo cria um agente com fundamentação utilizando a ferramenta Bing Search e demonstra o tratamento de respostas em fluxo contínuo. Quando executas o código:

1. Cria um AIProjectClient usando o endpoint do seu projeto.
2. Recupera a configuração da ligação Bing do seu projeto.
3. Cria um agente com a ferramenta de base Bing configurada.
4. Envia uma consulta a perguntar como a Wikipédia explica a Identidade de Euler.
5. O agente utiliza a ferramenta de grounding Bing e fornece a resposta em tempo real.
6. Processa eventos em streaming, incluindo atualizações de texto delta e extração de citações.
7. Limpa eliminando a versão do agente.

Entradas necessárias

• Atualiza as projectEndpoint constantes e bingConnectionName no código com os teus valores.
• Azure credenciais configuradas para DefaultAzureCredential.

Produção esperada

Stream response created with ID: resp_xyz789
Delta: Euler
Delta: 's
Delta:  Identity
Delta:  is one of the most...
Euler's Identity is one of the most elegant equations in mathematics... [Euler's identity - Wikipedia](https://en.wikipedia.org/wiki/Euler%27s_identity)

Os seguintes exemplos de APIs REST demonstram como usar o Grounding com as ferramentas Bing Search e Grounding com Bing Custom Search (preview) para responder a questões dos utilizadores.

Aterramento com a Pesquisa Bing

Configuração da autenticação

Antes de executar chamadas à API REST, configure a autenticação:

1. Definir variáveis do ambiente:

   • FOUNDRY_PROJECT_ENDPOINT: URL do endpoint do seu projeto Foundry.
   • FOUNDRY_MODEL_DEPLOYMENT_NAME: O nome do seu modelo implantado.
   • BING_PROJECT_CONNECTION_ID: ID de conexão do seu projeto Grounding com a Pesquisa Bing.

2. Obtenha um token de portador:

   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" \
     -d '{
     "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
     "input": "How does Wikipedia explain Euler\u0027s identity?",
     "tool_choice": "required",
     "tools": [
       {
         "type": "bing_grounding",
         "bing_grounding": {
           "search_configurations": [
             {
               "project_connection_id": "'$BING_PROJECT_CONNECTION_ID'",
               "count": 7,
               "market": "en-US",
               "set_lang": "en",
               "freshness": "7d"
             }
           ]
         }
       }
     ]
   }'
   

O que este código faz

Este pedido de API REST cria uma resposta usando Grounding com Bing Search. O pedido:

1. Envia um pedido POST para o endpoint de respostas da Foundry.
2. Inclui a implementação do modelo e a entrada do utilizador no corpo do pedido.
3. Configura a ferramenta de grounding do Bing com parâmetros de pesquisa (contagem, mercado, idioma, frescura).
4. Devolve uma resposta com resultados de pesquisa na web e citações.

Entradas necessárias

• Variáveis de ambiente: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME, BING_PROJECT_CONNECTION_ID.
• Token de portador válido com as permissões apropriadas.

Produção esperada

Resposta do JSON com:

• id: Identificador de resposta
• output_text: Texto gerado com informação fundamentada
• citations: Array de citações de URL usado para gerar a resposta

Aterramento com Pesquisa Personalizada Bing (pré-visualização)

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
  "input": "How does Wikipedia explain Euler\u0027s identity?",
  "tool_choice": "required",
  "tools": [
    {
      "type": "bing_custom_search_preview",
      "bing_custom_search_preview": {
        "search_configurations": [
          {
            "project_connection_id": "'$BING_CUSTOM_SEARCH_PROJECT_CONNECTION_ID'",
            "instance_name": "'$BING_CUSTOM_SEARCH_INSTANCE_NAME'",
            "count": 7,
            "market": "en-US",
            "set_lang": "en",
            "freshness": "7d"
          }
        ]
      }
    }
  ]
}'

O que este código faz

Este pedido da API REST cria uma resposta usando Grounding com Bing Custom Search. O pedido:

1. Envia um pedido POST para o endpoint de respostas da Foundry.
2. Inclui a implementação do modelo e a entrada do utilizador no corpo do pedido.
3. Configura a ferramenta Bing Custom Search com o nome da sua instância e parâmetros de pesquisa.
4. Devolve uma resposta com resultados de pesquisa personalizados limitados aos domínios configurados.

Entradas necessárias

• Variáveis de ambiente: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME, BING_CUSTOM_SEARCH_PROJECT_CONNECTION_ID, BING_CUSTOM_SEARCH_INSTANCE_NAME
• Token de portador válido com as permissões apropriadas.
• Instância de Pesquisa Personalizada do Bing já configurada com domínios de destino

Produção esperada

Resposta do JSON com:

• id: Identificador de resposta
• output_text: Texto gerado com informação do seu conjunto de domínios personalizado
• citations: Array de citações de URL dos seus domínios configurados

Os seguintes exemplos de TypeScript demonstram como criar um agente com Grounding com Bing Search e Grounding com ferramentas Bing Custom Search (pré-visualização), e como usar o agente para responder a perguntas dos utilizadores. Para exemplos de JavaScript, consulte os exemplos de ferramentas agent no repositório SDK do Azure para JavaScript sobre GitHub.

Aterramento com a Pesquisa Bing

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_CONNECTION_NAME = "my-bing-connection";

export async function main(): Promise<void> {
  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Get connection ID from connection name
  const bingConnection = await project.connections.get(BING_CONNECTION_NAME);

  const agent = await project.agents.createVersion("MyBingGroundingAgent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions: "You are a helpful assistant.",
    tools: [
      {
        type: "bing_grounding",
        bing_grounding: {
          search_configurations: [
            {
              project_connection_id: bingConnection.id,
            },
          ],
        },
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Send request that requires current information from the web
  const streamResponse = await openai.responses.create(
    {
      input: "What is today's date and weather in Seattle?",
      stream: true,
    },
    {
      body: {
        agent: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.created") {
      console.log(`Follow-up response created with ID: ${event.response.id}`);
    } else if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n\nFollow-up response done!");
    } else if (event.type === "response.output_item.done") {
      if (event.item.type === "message") {
        const item = event.item;
        if (item.content && item.content.length > 0) {
          const lastContent = item.content[item.content.length - 1];
          if (lastContent.type === "output_text" && lastContent.annotations) {
            for (const annotation of lastContent.annotations) {
              if (annotation.type === "url_citation") {
                console.log(
                  `URL Citation: ${annotation.url}, Start index: ${annotation.start_index}, End index: ${annotation.end_index}`,
                );
              }
            }
          }
        }
      }
    } else if (event.type === "response.completed") {
      console.log("\nFollow-up completed!");
    }
  }

  // Clean up resources by deleting the agent version
  // This prevents accumulation of unused resources in your project
  console.log("\nCleaning up resources...");
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nBing grounding agent sample completed!");
}

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

O que este código faz

Este exemplo cria um agente com aterramento usando a ferramenta Bing Search, que pode recuperar informação em tempo real da web. Quando executas o código:

1. Cria um AIProjectClient e autentica usando as suas credenciais Azure.
2. Cria um agente com a ferramenta de suporte do Bing configurada através da sua conexão Bing.
3. Envia uma consulta sobre a data atual e as condições meteorológicas em Seattle, com a escolha de ferramenta definida como "necessária".
4. O agente utiliza a ferramenta de grounding Bing para pesquisar na web e transmite a resposta.
5. Processa eventos em streaming e extrai citações URL com as suas posições no texto.
6. Limpa eliminando a versão do agente.

Entradas necessárias

• Atualiza as PROJECT_ENDPOINT constantes e BING_CONNECTION_NAME no código com os teus valores.
• Azure credenciais configuradas para DefaultAzureCredential.

Produção esperada

Agent created (id: asst_abc123, name: MyBingGroundingAgent, version: 1)
Follow-up response created with ID: resp_xyz789
Today's date is December 12, 2025, and the weather in Seattle...

Follow-up response done!
URL Citation: https://www.weather.gov/seattle/, Start index: 45, End index: 120

Follow-up completed!

Cleaning up resources...
Agent deleted

Bing grounding agent sample completed!

Aterramento com Pesquisa Personalizada Bing (pré-visualização)

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import * as readline from "readline";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const CUSTOM_SEARCH_CONNECTION_NAME = "my-custom-search-connection";
const CUSTOM_SEARCH_INSTANCE_NAME = "my-custom-search-instance";

export async function main(): Promise<void> {
  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Get connection ID from connection name
  const bingCustomConnection = await project.connections.get(CUSTOM_SEARCH_CONNECTION_NAME);

  const agent = await project.agents.createVersion("MyAgent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions:
      "You are a helpful agent that can use Bing Custom Search tools to assist users. Use the available Bing Custom Search tools to answer questions and perform tasks.",
    tools: [
      {
        type: "bing_custom_search_preview",
        bing_custom_search_preview: {
          search_configurations: [
            {
              project_connection_id: bingCustomConnection.id,
              instance_name: CUSTOM_SEARCH_INSTANCE_NAME,
            },
          ],
        },
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Prompt user for input
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });

  const userInput = await new Promise<string>((resolve) => {
    rl.question(
      "Enter your question for the Bing Custom Search agent (e.g., 'Tell me more about foundry agent service'): \n",
      (answer) => {
        rl.close();
        resolve(answer);
      },
    );
  });

  // Send initial request that will trigger the Bing Custom Search tool
  const streamResponse = await openai.responses.create(
    {
      input: userInput,
      stream: true,
    },
    {
      body: {
        agent: { name: agent.name, type: "agent_reference" },
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.created") {
      console.log(`Follow-up response created with ID: ${event.response.id}`);
    } else if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n\nFollow-up response done!");
    } else if (event.type === "response.output_item.done") {
      if (event.item.type === "message") {
        const item = event.item;
        if (item.content && item.content.length > 0) {
          const lastContent = item.content[item.content.length - 1];
          if (lastContent.type === "output_text" && lastContent.annotations) {
            for (const annotation of lastContent.annotations) {
              if (annotation.type === "url_citation") {
                console.log(
                  `URL Citation: ${annotation.url}, Start index: ${annotation.start_index}, End index: ${annotation.end_index}`,
                );
              }
            }
          }
        }
      }
    } else if (event.type === "response.completed") {
      console.log("\nFollow-up completed!");
    }
  }

  // Clean up resources by deleting the agent version
  // This prevents accumulation of unused resources in your project
  console.log("\nCleaning up resources...");
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nBing Custom Search agent sample completed!");
}

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

O que este código faz

Este exemplo cria um agente com Grounding com a ferramenta Bing Custom Search que pesquisa dentro dos seus domínios configurados. Quando executas o código:

1. Cria um AIProjectClient e autentica usando as suas credenciais Azure.
2. Cria um agente com a ferramenta Bing Custom Search configurada usando a sua instância de pesquisa personalizada.
3. Solicitações para a entrada do utilizador durante a execução através da linha de comandos.
4. O agente utiliza a ferramenta Bing Custom Search para pesquisar apenas nos domínios especificados e transmite a resposta.
5. Processa eventos em streaming e extrai citações URL com as suas posições no texto.
6. Limpa eliminando a versão do agente.

Entradas necessárias

• Atualize as constantes PROJECT_ENDPOINT, CUSTOM_SEARCH_CONNECTION_NAME e CUSTOM_SEARCH_INSTANCE_NAME no código com os seus valores.
• Azure credenciais configuradas para DefaultAzureCredential.
• Entrada do utilizador fornecida em tempo de execução via consola.

Produção esperada

Agent created (id: asst_abc123, name: MyAgent, version: 1)
Enter your question for the Bing Custom Search agent (e.g., 'Tell me more about foundry agent service'):
Tell me more about foundry agent service
Follow-up response created with ID: resp_xyz789
Microsoft Foundry Agent Service enables you to build...

Follow-up response done!
URL Citation: https://learn.microsoft.com/azure/ai-foundry/agents, Start index: 0, End index: 89

Follow-up completed!

Cleaning up resources...
Agent deleted

Bing Custom Search agent sample completed!

Usa o aterramento do Bing num agente Java

Adicione a dependência ao seu pom.xml:

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

Crie um agente com suporte no Bing

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.*;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.Arrays;
import java.util.Collections;

public class BingGroundingExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";
        String bingConnectionId = "my-bing-connection-id";

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

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

        // Create Bing grounding tool with connection configuration
        BingGroundingTool bingTool = new BingGroundingTool(
            new BingGroundingSearchToolParameters(Arrays.asList(
                new BingGroundingSearchConfiguration(bingConnectionId)
            ))
        );

        // Create agent with Bing grounding tool
        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-4.1-mini")
            .setInstructions("You are a helpful assistant. Use Bing to find up-to-date information.")
            .setTools(Collections.singletonList(bingTool));

        AgentVersionDetails agent = agentsClient.createAgentVersion("bing-grounding-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 developments in AI?"));

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

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