你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用必应搜索工具对智能体进行基础设置

Foundry 模型具有知识截止点。它们无法访问超出固定时间点的新信息。通过使用 Grounding with Bing Search 和 Grounding with Bing Custom Search（预览版），智能体可在生成响应时合并实时公共 Web 数据。通过使用这些工具，可以提出“今天什么是热门 AI 新闻”等问题。

接地过程涉及几个关键步骤：

查询表述：代理标识信息差距并构造搜索查询。
搜索执行：基础工具将查询提交到搜索引擎并检索结果。
信息合成：代理处理搜索结果并将结果集成到响应中。
源归属：代理通过引用搜索源提供透明度。

重要

Grounding with Bing Search 和 Grounding with Bing Custom Search 是第一方消费服务，适用在线服务条款。它们受 Grounding with Bing 使用条款和 Microsoft 隐私声明约束。
Microsoft 数据保护附录不适用于发送到 Grounding with Bing Search 和 Grounding with Bing Custom Search 的数据。使用这些服务时，数据流超出Azure合规性和地理边界。这也意味着使用这些服务表示放弃所有政府社区云的高级安全性和合规性承诺，包括数据主权和筛选/基于公民身份的支持（如适用）。
使用 Grounding with Bing Search 和 Grounding with Bing Custom Search 会产生费用。请查看定价详情。
请参阅“管理”部分，了解 Azure 管理员如何管理 Grounding with Bing Search 和 Grounding with Bing Custom Search 的使用权限。

注意

从 Web 搜索工具开始。有关 Web 搜索与使用 Grounding with Bing Search（或 Grounding with Bing Custom Search）之间的差异，请参阅 Web 基础信息概述。

使用支持

下表显示了 SDK 和设置支持。

Microsoft Foundry 支持	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	基本代理设置	标准代理设置
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

注意

并非所有模型都支持 Grounding with Bing Search 或 Grounding with Bing Custom Search。有关支持这些工具的模型的完整列表，请参阅按区域和模型提供的工具支持。

先决条件

在开始之前，请确保具备：

具有适当权限的Azure订阅。
Azure RBAC 角色：
- 要创建必应资源并获取资源密钥，需要在订阅或资源组级别拥有参与者或所有者角色。
- 用于在 Foundry 中创建项目连接的 Foundry Project Manager 角色。有关详细信息，请参阅Microsoft Foundry 的基于角色的访问控制。
  
  重要
  
  Foundry RBAC 角色最近已更名。 Foundry 用户、Foundry 所有者、Foundry 帐户所有者和 Foundry 项目经理之前的名称分别为“Azure AI 用户”、“Azure AI 所有者”、“Azure AI 帐户所有者”和“Azure AI 项目经理”。在重命名推出时，你仍可能会在某些位置看到以前的名称。重命名后，角色 ID 和核心权限保持不变。
使用配置的端点创建的 Foundry 项目。
在项目中部署的 AI 模型。
为首选语言安装的 SDK：
- Python：azure-ai-projects
- C#：Azure.AI.Extensions.OpenAI
- TypeScript/JavaScript： @azure/ai-projects
- Java：com.azure:azure-ai-agents:2.0.0
为身份验证配置的Azure凭据（如 DefaultAzureCredential）。
- 对于 REST 示例，设置环境变量：
  - FOUNDRY_PROJECT_ENDPOINT：Foundry 项目终结点 URL。
  - FOUNDRY_MODEL_DEPLOYMENT_NAME：已部署的模型名称。
  - BING_PROJECT_CONNECTION_ID：你的 Grounding with Bing Search 项目连接 ID。
  - BING_CUSTOM_SEARCH_PROJECT_CONNECTION_ID：你的 Grounding with Bing Custom Search 项目连接 ID。
  - BING_CUSTOM_SEARCH_INSTANCE_NAME：自定义搜索实例名称。
  - AGENT_TOKEN。
已创建并连接到 Foundry 项目的必应基础或必应自定义搜索资源。创建“Grounding with Bing Search”或“Grounding with Bing Custom Search”资源需要付费订阅。
Grounding with Bing Search 工具可在网络安全的 Foundry 项目中使用，但它的行为类似于公共终结点。在受网络保护的环境中使用该工具时，请考虑此行为。

设置

在本部分中，你将为必应 (Bing) 资源添加项目连接，并捕获示例中使用的值。 SDK 示例使用项目连接名称并在运行时解析连接 ID。 REST 示例使用项目连接 ID。可以使用此 bicep 模板创建一个启用了“Grounding with Bing Search”工具的基本智能体。

如果你要使用的必应资源已有项目连接 ID，请跳过本部分。

将适当的连接添加到您的项目。

有关分步说明，请参阅向项目添加新连接。
重要
- 要创建必应 (Bing) 资源并获取资源密钥，你需要在订阅或资源组级别拥有参与者或所有者角色。
- 要查找资源密钥，请在 Azure 门户>资源管理>密钥中转到你的“Grounding with Bing”资源。
从连接详细信息获取项目连接名称和 ID，然后将值设置为环境变量。

对于 SDK 示例：
- 对于 Grounding with Bing Search：设置 BING_PROJECT_CONNECTION_NAME。
- 对于 Grounding with Bing Custom Search：设置 BING_CUSTOM_SEARCH_PROJECT_CONNECTION_NAME。
对于 REST 示例：
- 对于 Grounding with Bing Search：设置 BING_PROJECT_CONNECTION_ID。
- 对于 Grounding with Bing Custom Search：设置 BING_CUSTOM_SEARCH_PROJECT_CONNECTION_ID。

项目连接 ID 使用格式：

/subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}

可用工具

工具	描述	用例
使用必应搜索查找事实依据	为代理提供对必应搜索功能的标准访问权限。	需要广泛知识获取的场景。
使用必应自定义搜索进行基础设置（预览版）	允许代理在可配置的公共 Web 域集中搜索。定义要从中绘制的 Web 部分，以便用户仅看到所选域的相关结果。	需要信息管理的方案。

注意

请参阅有关优化工具使用情况的最佳做法。

代码示例

注意

需要最新的 SDK 包。有关详细信息，请参阅快速入门。
对于 SDK 示例，请使用项目连接名称。对于 REST 示例，请使用格式为/subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}的项目连接 ID。

以下示例演示如何使用必应搜索工具创建具有 Grounding 的代理，以及如何使用代理来响应用户查询。选择 Prompt Agents以使用 Azure AI Projects SDK 创建服务器端提示代理，或托管代理使用 Agent Framework FoundryChatClient生成临时进程内代理。

提示智能体
托管代理

使用必应搜索查找事实依据

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

此代码的作用

此示例使用必应搜索工具创建一个具有基础的智能体，该工具可以从 Web 中检索实时信息。运行代码时：

它创建 AIProjectClient，并使用Azure凭据进行身份验证。
使用通过必应连接配置的必应基础工具创建智能体。
发送一个查询，询问西雅图的当前日期和天气。
代理使用必应搜索工具在网络上进行搜索，并流式传输响应数据。
从搜索结果中提取和显示 URL 引文。

所需的输入

将代码中的 PROJECT_ENDPOINT 和 BING_CONNECTION_NAME 常量替换为您自己的值。
为 DefaultAzureCredential 配置的 Azure 凭据。

预期输出

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

此示例使用 Microsoft Agent Framework 中的 FoundryChatClient，并调用 get_bing_grounding_tool() 通过项目连接附加 Bing 依据。使用 pip install agent-framework-foundry aiohttp 安装软件包，设置 FOUNDRY_PROJECT_ENDPOINT 和 FOUNDRY_MODEL 环境变量，并使用 az login 登录。

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.ai.projects import AIProjectClient
from azure.identity import AzureCliCredential

BING_CONNECTION_NAME = "my-bing-connection"


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

    # Resolve the project connection ID from the connection name
    # (same pattern as the Prompt Agents tab).
    project = AIProjectClient(
        endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        credential=credential,
    )
    connection_id = project.connections.get(BING_CONNECTION_NAME).id

    agent = Agent(
        # Reads FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL from the environment.
        client=FoundryChatClient(credential=credential),
        instructions="You are a helpful assistant that can search the web with Bing.",
        tools=[
            FoundryChatClient.get_bing_grounding_tool(
                connection_id=connection_id,
                market="en-US",
                count=10,
                freshness="Day",
            )
        ],
    )

    result = await agent.run("What is today's date and weather in Seattle?")
    print(f"Agent: {result.text}")

    # Print URL citation annotations from the response.
    for message in result.messages:
        for content in message.contents:
            for annotation in getattr(content, "annotations", None) or []:
                url = getattr(annotation, "url", None)
                if url:
                    print(f"URL Citation: {url}")


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

预期输出

智能体使用 Bing 依据在网上搜索当前日期和西雅图天气信息，然后输出最终响应文本，后跟从响应注释中解析出的 URL 引用。

Agent: Today's date is December 12, 2025, and the weather in Seattle is...
URL Citation: https://www.weather.gov/seattle/

对于 Bing 自定义搜索，请使用 FoundryChatClient.get_bing_custom_search_tool(connection_id=..., instance_name=..., market=..., count=...)，并采用相同的代理模式。有关详细信息，请参阅 Foundry 提供程序示例。

使用必应自定义搜索进行基础设置（预览版）

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

此代码的作用

此示例使用 Grounding with Bing Custom Search 工具创建一个智能体，该工具可在一组可配置的公共 Web 域中搜索。运行代码时：

它创建 AIProjectClient，并使用Azure凭据进行身份验证。
使用通过自定义搜索实例配置的必应自定义搜索工具创建智能体。
提示用户输入，询问您配置的领域内的具体主题。
代理使用必应自定义搜索工具仅搜索指定的域并流式传输响应。
从自定义搜索结果中提取和显示带有起始位置和结束位置的 URL 引文。

所需的输入

将代码中的 PROJECT_ENDPOINT、CUSTOM_SEARCH_CONNECTION_NAME 和 CUSTOM_SEARCH_INSTANCE_NAME 常量更新为您的值。
为 DefaultAzureCredential 配置的 Azure 凭据。
运行时的用户输入。

预期输出

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

以下 C# 示例演示如何使用必应搜索工具创建具有 Grounding 的代理，以及如何使用代理来响应用户查询。为了简单起见，这些示例使用同步调用。有关异步示例，请参阅 agent 工具 C# 示例。

若要使代理能够使用必应搜索 API，请使用 BingGroundingTool。选择 Prompt Agents以使用 Azure AI Projects SDK 创建服务器端提示代理，或托管代理使用 Microsoft Agent Framework 生成临时进程内代理。

提示智能体
托管代理

使用必应搜索查找事实依据

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

此代码的作用

此示例会创建一个智能体，该智能体使用 Grounding with Bing Search 工具并演示同步响应处理。运行代码时：

它通过使用你的项目端点来创建 AIProjectClient。
从项目中检索Bing的连接配置。
使用配置的必应基础工具创建智能体。
发送一个查询，询问维基百科如何解释欧拉的身份。
智能体使用必应基础工具进行搜索，并返回带有 URL 引用的格式化结果。
通过删除代理软件版本进行清理。

所需的输入

将代码中的 projectEndpoint 和 bingConnectionName 常量替换为您自己的值。
为 DefaultAzureCredential 配置的 Azure 凭据。

预期输出

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)

此示例使用 Microsoft Agent Framework，并在 AsAIAgent(...) 上调用 AIProjectClient，以及来自 FoundryAITool.CreateBingGroundingTool(...) 的 Microsoft.Agents.AI.Foundry。安装 Microsoft.Agents.AI.Foundry 和 Azure.AI.Projects 包，设置 AZURE_AI_PROJECT_ENDPOINT 和 AZURE_AI_MODEL_DEPLOYMENT_NAME 环境变量，并使用 az login 登录。

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;
using Microsoft.Extensions.AI;

string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5-mini";
string bingConnectionName = "my-bing-connection";

const string AgentInstructions = "You are a helpful agent that can use Bing search to answer questions.";

AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());

// Resolve the project connection ID from the connection name
// (same pattern as the Prompt Agents tab).
AIProjectConnection bingConnection = aiProjectClient.Connections.GetConnection(connectionName: bingConnectionName);

BingGroundingSearchToolOptions bingGroundingOptions = new(
    searchConfigurations: [new BingGroundingSearchConfiguration(projectConnectionId: bingConnection.Id)]);

AIAgent agent = aiProjectClient.AsAIAgent(deploymentName,
    instructions: AgentInstructions,
    name: "BingGroundingAgent",
    tools: [FoundryAITool.CreateBingGroundingTool(bingGroundingOptions)]);

AgentResponse response = await agent.RunAsync("How does wikipedia explain Euler's Identity?");

Console.WriteLine($"Response: {response.Text}");

// Print URL citation annotations from the response.
foreach (AIAnnotation annotation in response.Messages.SelectMany(m => m.Contents).SelectMany(c => c.Annotations ?? []))
{
    if (annotation.RawRepresentation is UriCitationMessageAnnotation uriAnnotation)
    {
        Console.WriteLine($"URL Citation: [{uriAnnotation.Title}]({uriAnnotation.Uri})");
    }
}

预期输出

该代理使用 Bing grounding 在 Web 上搜索并回答问题，然后输出最终响应文本，并附上从响应注释中提取的 URL 引用。

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

对于 Bing 自定义搜索，请将 FoundryAITool.CreateBingCustomSearchTool(...) 与一个 BingCustomSearchToolOptions 实例配合使用。有关完整示例，请参阅 Agent_Step18_BingCustomSearch。

在流式处理方案中使用 Grounding with 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));

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

此代码的作用

此示例使用必应搜索工具创建具有基础的智能体，并演示流式响应的处理。运行代码时：

它通过使用你的项目端点来创建 AIProjectClient。
从项目中检索Bing的连接配置。
使用配置的必应基础工具创建智能体。
发送一个查询，询问维基百科如何解释欧拉的身份。
智能体使用必应基础工具并实时流式传输响应。
处理流式处理事件，包括增量文本更新和引文提取。
通过删除代理软件版本进行清理。

所需的输入

将代码中的 projectEndpoint 和 bingConnectionName 常量替换为您自己的值。
为 DefaultAzureCredential 配置的 Azure 凭据。

预期输出

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)

以下 REST API 示例演示了如何使用 Grounding with Bing Search 和 Grounding with Bing Custom Search（预览版）工具来响应用户查询。

使用必应搜索查找事实依据

身份验证设置

在运行 REST API 调用之前，请配置身份验证：

设置环境变量：
- FOUNDRY_PROJECT_ENDPOINT：Foundry 项目终结点 URL。
- FOUNDRY_MODEL_DEPLOYMENT_NAME：已部署的模型名称。
- BING_PROJECT_CONNECTION_ID：你的 Grounding with Bing Search 项目连接 ID。

获取承载令牌：

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

此代码的作用

此 REST API 请求通过 Grounding with Bing Search 创建响应。请求：

将 POST 请求发送到 Foundry 响应终结点。
在请求正文中包含模型部署和用户输入。
使用搜索参数（计数、市场、语言、新鲜度）配置必应基础工具。
返回包含 Web 搜索结果和引文的响应。

所需的输入

环境变量：FOUNDRY_PROJECT_ENDPOINT、、AGENT_TOKENFOUNDRY_MODEL_DEPLOYMENT_NAME、BING_PROJECT_CONNECTION_ID。
具有适当权限的有效持有者令牌。

预期输出

JSON 响应，其中包含：

id：响应标识符
output_text：基于有根据的信息生成文本
citations：用于生成响应的 URL 引文数组

使用必应自定义搜索进行基础设置（预览版）

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

此代码的作用

此 REST API 请求通过 Grounding with Bing Custom Search 创建响应。请求：

将 POST 请求发送到 Foundry 响应终结点。
在请求正文中包含模型部署和用户输入。
使用您的实例名称和搜索参数配置必应自定义搜索工具。
返回一个响应，其中的自定义搜索结果仅限于您已配置的域。

所需的输入

环境变量：FOUNDRY_PROJECT_ENDPOINT、、AGENT_TOKENFOUNDRY_MODEL_DEPLOYMENT_NAME、BING_CUSTOM_SEARCH_PROJECT_CONNECTION_ID、BING_CUSTOM_SEARCH_INSTANCE_NAME
具有适当权限的有效持有者令牌。
必应自定义搜索实例已配置目标域

预期输出

JSON 响应，其中包含：

id：响应标识符
output_text：生成的文本包含来自自定义域集合的信息
citations：来自已配置域的 URL 引文数组

以下 TypeScript 示例演示如何使用 Grounding with Bing Search 和 Grounding with Bing Custom Search（预览版）”工具创建智能体，以及如何使用该智能体响应用户查询。有关 JavaScript 示例，请参阅 GitHub 上适用于 JavaScript 存储库的 Azure SDK 中的 agent 工具 JavaScript 示例。

使用必应搜索查找事实依据

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

此代码的作用

此示例使用必应搜索工具创建一个具有基础的智能体，该工具可以从 Web 中检索实时信息。运行代码时：

它创建 AIProjectClient，并使用Azure凭据进行身份验证。
使用通过必应连接配置的必应基础工具创建智能体。
发送一个查询，询问西雅图的当前日期和时间，工具选项设置为“必需”。
代理使用必应搜索工具在网络上进行搜索，并流式传输响应数据。
处理流式处理事件并提取 URL 引文及其在文本中的位置。
通过删除代理软件版本进行清理。

所需的输入

将代码中的 PROJECT_ENDPOINT 和 BING_CONNECTION_NAME 常量替换为您自己的值。
为 DefaultAzureCredential 配置的 Azure 凭据。

预期输出

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!

使用必应自定义搜索进行基础设置（预览版）

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

此代码的作用

此示例使用 Grounding with Bing Custom Search 工具创建智能体，该工具可在所配置的域中进行搜索。运行代码时：

它创建 AIProjectClient，并使用Azure凭据进行身份验证。
使用通过自定义搜索实例配置的必应自定义搜索工具创建智能体。
在运行时通过命令行提示用户输入。
代理使用必应自定义搜索工具仅搜索指定的域并流式传输响应。
处理流式处理事件并提取 URL 引文及其在文本中的位置。
通过删除代理软件版本进行清理。

所需的输入

将代码中的 PROJECT_ENDPOINT、CUSTOM_SEARCH_CONNECTION_NAME 和 CUSTOM_SEARCH_INSTANCE_NAME 常量更新为您的值。
为 DefaultAzureCredential 配置的 Azure 凭据。
通过控制台在运行时提供的用户输入。

预期输出

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!

在 Java 智能体中使用 Bing 依据

将依赖项添加到pom.xml：

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

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

工作原理

用户查询是最终用户发送给代理的消息，例如*“我今天是否应该和我一起拿伞？我在西雅图。*说明是开发人员可以提供的系统消息，用于共享上下文，并向 AI 模型提供有关如何使用各种工具或行为的说明。

当用户发送查询时，客户的 AI 模型部署首先处理它（使用提供的指令）以便在之后执行必应搜索查询（这对开发人员可见）。 “Grounding with Bing”会将相关的搜索结果返回到客户的模型部署，然后生成最终输出。

注意

在使用 Grounding with Bing Search 或 Grounding with Bing Custom Search 时，发送到必应的信息仅包括必应搜索查询、工具参数和资源密钥。该服务不会发送任何特定于最终用户的信息。资源密钥发送到必应仅出于计费和速率限制目的。

授权将在 Grounding with Bing Search 或 Grounding with Bing Custom Search 服务与 Foundry 智能体服务之间进行。服务出于基础功能目的生成并发送到必应的任何必应搜索查询都将连同资源密钥一起传输到 Azure 合规边界外部，将发送到 Grounding with Bing Search 服务。如使用条款中所述，Grounding with Bing Search 功能受必应条款约束，且不具备与智能体服务相同的合规标准和认证。你负责评估在智能体中使用 Grounding with Bing Search 功能或 Grounding with Bing Custom Search 功能是否满足你的需求和要求。

使用 Grounding with Bing 资源的事务数按每次运行时的工具调用次数计算。您可以查看运行步骤中进行了多少次工具调用。

开发人员和最终用户无权访问通过必应搜索从 Grounding 返回的原始内容。不过，模型响应包括带有用于生成响应的网站链接的引文，以及用于搜索的必应查询的链接。可以通过访问已创建的会话中的数据来检索 模型响应 。根据“Grounding with Bing Search”的使用和显示要求，这两个“参考项”必须以 Microsoft 提供的确切形式保留和显示。有关详细信息，请参阅如何显示“Grounding with Bing Search”结果部分。

如何显示搜索结果

根据“Grounding with Bing”的使用条款及使用和显示要求，你需要在自定义界面中显示网站 URL 和必应搜索查询 URL。可以在 API 响应中的参数中找到 arguments 此信息。若要呈现网页，请将必应搜索查询 URL 的终结点替换为 www.bing.com，此时，您的必应搜索查询 URL 如下所示 https://www.bing.com/search?q={search query}。

“Grounding with Bing Custom Search”配置

Grounding with Bing Custom Search 是一种功能强大的工具，可用于选择 Web 的子空间，以便限制智能体的基础知识。下面是一些提示，可帮助你充分利用此功能：

如果你拥有要包含在搜索中的公共网站，但必应尚未编制索引，请参阅必应网站管理员指南，了解有关获取网站索引的详细信息。如果索引过期，Webmaster 文档还提供了有关如何让必应爬网您的网站的详细信息。
创建配置至少需要对必应自定义搜索资源拥有参与者角色。
只能阻止某些域，并针对 Web 的其余部分（例如竞争对手的网站）执行搜索。
Grounding with Bing Custom Search 仅会返回已公开且必应已编制索引的域和网页的结果。
- 域（例如， https://www.microsoft.com）
- 域和路径（例如） https://www.microsoft.com/surface
- 网页（例如， https://www.microsoft.com/en-us/p/surface-earbuds/8r9cpq146064）

可选参数

将 Grounding with Bing Search 或 Grounding with Bing Custom Search 工具添加到智能体时，可以传递以下参数。这些参数会影响工具输出，并且 AI 模型可能无法完全使用所有输出。有关 API 版本支持以及如何传递这些参数的信息，请参阅代码示例。

名字	价值	类型	必填
`count`	响应中要返回的搜索结果数。默认值为 5，最大值为 50。传递的实际数字可能小于请求数。不同页面的结果可能会有重叠。此参数仅影响网页结果。 AI 模型可能不使用必应返回的所有搜索结果。	`UnsignedShort`	不
`freshness`	按以下不区分大小写的年龄值筛选搜索结果：日：返回必应在过去 24 小时内发现的网页。周：返回必应在过去 7 天内发现的网页。月：显示 Bing 在过去 30 天内发现的网页。若要获取必应在特定时间段内发现的文章，请按以下格式指定日期范围：`YYYY-MM-DD..YYYY-MM-DD`。例如， `freshness=2019-02-01..2019-05-30`. 若要将结果限制为单个日期，请将此参数设置为特定日期。例如， `freshness=2019-02-04`.	字符串	不
`market`	结果来源的市场。通常， `mkt` 是用户发出请求的国家/地区。但是，如果用户所在的国家/地区不在必应 (Bing) 提供结果的范围内，则可能会显示其他国家/地区的结果。市场必须采用以下形式： `<language>-<country/region>` 例如， `en-US`. 字符串不区分大小写。有关可能的市场值的列表，请参阅 “市场代码”。如果已知，建议始终指定市场。指定市场有助于必应路由请求，并返回适当的最佳响应。如果指定市场代码中未列出的市场，必应会根据可能会更改的内部映射使用最适合的市场代码。	字符串	不
`set_lang`	用于用户界面字符串的语言。可以使用 2 个字母或 4 个字母代码指定语言。首选使用 4 个字母代码。有关支持的语言代码的列表，请参阅必应所支持的语言。如果 `setlang` 包含有效的 2 个字母的非特定区域性代码 (`fr`) 或有效的 4 个字母的特定区域性代码 (`fr-ca`)，必应将加载本地化字符串。例如，对于 `fr-ca`，必应加载 `fr` 非特定区域性代码字符串。如果 `setlang` 无效（例如 `zh`），或者必应不支持的语言（例如 `af`, `af-na`），必应将默认为 `en`（英语）。若要指定 2 个字母代码，请将此参数设置为 ISO 639-1 语言代码。若要指定 4 个字母代码，请使用格式 `<language>-<country/region>`，其中 `<language>` 为 ISO 639-1 语言代码（中性文化），`<country/region>` 为 ISO 3166 国家/地区代码（特定文化）。例如，对于美国英语使用 `en-US`。虽然是可选的，但应始终指定语言。通常，您应将 `setLang` 设置为与 `mkt` 相同的语言，除非用户希望用户界面字符串以其他语言显示。	字符串	不

支持的功能和已知问题

Grounding with Bing Search 工具旨在从 Web 检索实时信息，而不是从特定 Web 域检索。要从特定域检索信息，请使用 Grounding with Bing Custom Search 工具。
不要要求模型汇总整个网页。
在一次运行中，AI 模型会评估工具输出，并可能决定再次调用该工具以获取更多信息和上下文。 AI 模型还可能决定使用哪些工具输出来生成响应。
Foundry 代理服务将 AI 模型生成的响应 作为输出返回，因此端到端延迟受模型预处理和后期处理的影响。
Grounding with Bing Search 和 Grounding with Bing Custom Search 工具不会向开发人员和最终用户返回工具输出。
Grounding with Bing Search 和 Grounding with Bing Custom Search 仅适用于未使用 VPN 或专用终结点的智能体。代理必须具有正常的网络访问。
对于来自使用 Grounding with Bing 工具的链接，请使用默认引用模式（annotation 中发送的链接）。不要要求模型生成引文链接。

故障排除

使用此部分解决将 Grounding 与必应搜索工具配合使用时的常见问题。

连接 ID 格式错误

问题：错误消息指出连接 ID 格式无效。

解决方案：验证连接 ID 是否与所需的格式匹配：

/subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}

将所有占位符值（包括 {{ 和 }}）替换为实际资源标识符。

身份验证失败

问题：创建代理或运行查询时出现“未授权”或“禁止”错误。

解决方案：

验证是否具有所需的 RBAC 角色：
- 用于创建必应资源的参与者或所有者角色
- 用于创建项目连接的 Foundry 项目经理角色
检查是否已正确配置Azure凭据：
- 对于 Python/TypeScript：DefaultAzureCredential可以进行身份验证
- 对于 REST：持有者令牌有效且未过期
如果使用的是 Azure CLI，请运行 az login 以刷新凭据

网络连接问题

问题：Grounding with Bing Search 请求超时或无法连接。

解决方案：Grounding with Bing Search 和 Grounding with Bing Custom Search 不适用于 VPN 或专用终结点。确保：

你的网络可以正常访问互联网。
未使用 VPN 连接。
未为代理服务配置专用终结点。
防火墙规则允许与必应服务建立出站连接。

自定义搜索不返回任何结果

问题：必应自定义搜索返回空结果或找不到预期内容。

解决方案：

验证自定义搜索实例是否已正确配置目标域。
确保要搜索的域是公开的，并由必应编制索引。
检查配置的域是否符合搜索查询预期。
如果网站未编制索引，请参阅必应网站管理员指南，获取索引说明。
等待必应最近添加或更新的内容进行爬网（可能需要几天时间）。

缺少或无效的配置值

问题：代码失败并出现连接错误或“找不到”响应。

解决方案：确保使用实际值更新代码中的所有必需常量：

PROJECT_ENDPOINT （Python/TypeScript）或 projectEndpoint （C#/Java）：你的 Foundry 项目端点 URL。
必应资源的连接名称或 ID。
对于自定义搜索：自定义搜索实例名称。
对于 REST API，请设置环境变量： FOUNDRY_PROJECT_ENDPOINT、 FOUNDRY_MODEL_DEPLOYMENT_NAME或 BING_PROJECT_CONNECTION_IDBING_CUSTOM_SEARCH_PROJECT_CONNECTION_ID，以及 AGENT_TOKEN。

代理不使用接地工具

问题：智能体在没有调用必应基础工具的情况下做出响应。

解决方案：

确保查询需要模型不知道的当前信息。
对于显式工具用法，请在请求中设置 tool_choice="required"（Python/TypeScript 示例显示此情况）。
验证该工具是否已在代理定义中正确配置。
检查代理指令，建议使用现有工具获取最新信息。

Grounding with Bing Custom Search 工具的基础设置中未找到实例名称

问题：

{"error": "Tool_User_Error", "message": "[bing_search] Failed to call Get Custom Search Instance with status 404: {\"error\":{\"code\":\"ResourceNotFound\",\"message\":\"Instance or Customer not found\",\"target\":\"instanceName or customerId\"}}."}

解决方案：

确保你的实例名称存在于正在使用的 Grounding with Bing Custom Search 资源中。
仔细检查实例名称是否拼写正确。

管理“Grounding with Bing Search”和“Grounding with Bing Custom Search”

管理员可以利用 RBAC 角色分配来在订阅或资源组中启用或禁用 Grounding with Bing 和 Grounding with Bing Custom Search。

管理员在 Azure 订阅中注册Microsoft.Bing。管理员需要可对资源提供程序执行 /register/action 操作的权限。参与者和所有者角色包括此权限。有关如何注册的详细信息，请参阅 Azure 资源提供程序和类型。
管理员注册 Microsoft.Bing 后，具有权限的用户可以创建、删除或检索 Grounding with Bing 和/或 Grounding with Bing Custom Search 资源的资源密钥。这些用户在订阅或资源组级别需要 “参与者 ”或“ 所有者 ”角色。
创建 Grounding with Bing 和/或 Grounding with Bing Custom Search 资源后，具有权限的用户可以创建 Microsoft Foundry 连接，以连接到资源并将其用作 Foundry 智能体服务中的工具。这些用户至少需要具有 Foundry Project Manager 角色。

禁用“Grounding with Bing Search”和“Grounding with Bing Custom Search”

管理员需要订阅中的 “所有者” 或 “参与者” 角色。
管理员可删除订阅中的所有 Grounding with Bing Search 和 Grounding with Bing Custom Search 资源。
管理员在订阅中注销 Microsoft.Bing 资源提供程序（删除所有资源之前无法注销）。有关详细信息，请参阅Azure资源提供程序和类型。
管理员按照示例创建 Azure Policy，以禁止在其订阅中创建 Grounding with Bing Search 和 Grounding with Bing Custom Search 资源。

后续步骤

工具使用最佳做法 - 了解代理工具的优化策略
Web 搜索工具 - 在不配置 Bing 工具参数的情况下使用 Web 搜索
在 Microsoft Foundry 和 Azure 中管理 Grounding with Bing - 控制和禁用 Grounding with Bing 功能
将 OpenAPI 工具连接到代理 - 将自定义 API 与代理集成
在 Foundry 工具中发现工具（预览版） - 探索 Foundry 代理服务中的所有可用代理工具

反馈

此页面是否有帮助？

Last updated on 2026-06-03

使用必应搜索工具对智能体进行基础设置

使用支持

先决条件

设置

可用工具

代码示例

使用必应搜索查找事实依据

此代码的作用

所需的输入

预期输出

使用必应自定义搜索进行基础设置（预览版）

使用必应搜索查找事实依据

此代码的作用

所需的输入

预期输出

在流式处理方案中使用 Grounding with Bing

此代码的作用

所需的输入

预期输出

使用必应搜索查找事实依据

身份验证设置

此代码的作用

所需的输入

预期输出

使用必应自定义搜索进行基础设置（预览版）

此代码的作用

所需的输入

预期输出

使用必应搜索查找事实依据

使用必应自定义搜索进行基础设置（预览版）

在 Java 智能体中使用 Bing 依据

创建带 Bing 依据的智能体

工作原理

如何显示搜索结果

“Grounding with Bing Custom Search”配置

可选参数

支持的功能和已知问题

故障 排除

连接 ID 格式错误

身份验证失败

网络连接问题

自定义搜索不返回任何结果

缺少或无效的配置值

代理不使用接地工具

Grounding with Bing Custom Search 工具的基础设置中未找到实例名称

管理“Grounding with Bing Search”和“Grounding with Bing Custom Search”

禁用“Grounding with Bing Search”和“Grounding with Bing Custom Search”

后续步骤

反馈

其他资源

故障排除