Web 搜索允许代理在 Web 中搜索 up-to日期信息。 此工具使代理能够回答有关当前事件的问题、查找文档以及访问其训练数据之外的信息。
注释
Web 搜索可用性取决于基础代理提供程序。 有关提供程序特定的支持，请参阅 提供程序概述 。
以下示例演示如何使用 Web 搜索工具创建代理：
using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
// Requires: dotnet add package Microsoft.Agents.AI.Foundry --prerelease
var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
// Create an agent with hosted web search.
AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
.AsAIAgent(
model: deploymentName,
instructions: "You are a helpful assistant that can search the web for current information.",
tools: [new HostedWebSearchTool()]);
Console.WriteLine(await agent.RunAsync("What is the current weather in Seattle?"));
Warning
DefaultAzureCredential 对于开发来说很方便，但在生产中需要仔细考虑。 在生产环境中，请考虑使用特定凭据（例如）， ManagedIdentityCredential以避免延迟问题、意外凭据探测以及回退机制的潜在安全风险。
以下示例演示如何使用 Web 搜索工具创建代理：
# Copyright (c) Microsoft. All rights reserved.
import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
"""
OpenAI Responses Client with Web Search Example
This sample demonstrates using get_web_search_tool() with OpenAI Responses Client
for direct real-time information retrieval and current data access.
"""
async def main() -> None:
client = OpenAIChatClient()
# Create web search tool with location context
web_search_tool = client.get_web_search_tool(
user_location={"city": "Seattle", "country": "US"},
)
agent = Agent(
client=client,
instructions="You are a helpful assistant that can search the web for current information.",
tools=[web_search_tool],
)
message = "What is the current weather? Do not ask for my current location."
stream = False
print(f"User: {message}")
if stream:
print("Assistant: ", end="")
async for chunk in agent.run(message, stream=True):
if chunk.text:
print(chunk.text, end="")
print("")
else:
response = await agent.run(message)
print(f"Assistant: {response}")
if __name__ == "__main__":
asyncio.run(main())
Web 搜索
使用支持服务器端 Web 搜索的提供程序时，该 hostedtool.WebSearch 类型将启用服务器端 Web 搜索。
import "github.com/microsoft/agent-framework-go/tool/hostedtool"
webSearch := &hostedtool.WebSearch{}
a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
Config: agent.Config{
Tools: []tool.Tool{webSearch},
},
})
注释
Web 搜索是托管工具 ， 搜索由 AI 服务执行，而不是在本地执行。
将 Web 搜索与 Harness 代理配合使用
对于普通代理，请添加到 HostedWebSearchTool 代理的工具，如前所述。
HarnessAgent 默认情况下添加一个 HostedWebSearchTool ，因此不需要任何工具注册：
using Microsoft.Agents.AI;
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
ChatOptions = new()
{
Instructions = "Use web search for current information and cite the sources you used.",
},
});
设置 DisableWebSearch = true 所选提供程序不支持托管的 Web 搜索或想要自行 ChatOptions.Tools注册提供程序特定的搜索工具时。 如果在不禁用默认值的情况下添加自己的 Web 搜索工具，代理将接收这两个工具。
Web 搜索由模型提供程序托管;Harness 没有要管理的本地搜索客户端生命周期。 可用性、支持的模型、搜索参数、数据驻留和计费取决于 IChatClient 提供程序。 发送请求时，不支持的客户端可能会拒绝托管工具。
将搜索查询和结果视为跨越外部信任边界的数据。 不要在查询中包含机密，并将检索的页面视为可以包含间接提示注入的不受信任的内容。 在采取措施之前验证重要的声明和引文。
HarnessAgent 可从包获取 Microsoft.Agents.AI.Harness 。
对于普通代理，请调用 client.get_web_search_tool(...) 并传递返回的工具， Agent如前面所示。
create_harness_agent在客户端实现时，默认情况下不带参数的client.get_web_search_tool()调用SupportsWebSearchTool：
from agent_framework import create_harness_agent
agent = create_harness_agent(client=client)
如果客户端未实现 SupportsWebSearchTool，工厂会记录警告并继续执行 Web 搜索。 设置为 disable_web_search=True 禁止自动注册和警告。
若要传递提供程序特定的设置，请禁用默认值并显式注册配置的工具：
agent = create_harness_agent(
client=client,
disable_web_search=True,
tools=[
client.get_web_search_tool(
user_location={"city": "Seattle", "country": "US"},
search_context_size="medium",
)
],
)
提供程序拥有托管搜索执行和生命周期。 支持的参数、模型、数据处理和计费取决于客户端实现。 不要在查询中放置机密，将检索的内容视为不受信任的输入，并在执行操作之前验证重要的声明和引文。
create_harness_agent 在 agent-framework-core;Web 搜索中仅通过实现 SupportsWebSearchTool的客户端可用。
打包的 Go Harness 当前不可用。
hostedtool.WebSearch如前所示添加到纯 Go 代理。