Use web search tool in Foundry Agent Service

Use the web search tool in Foundry Agent Service to retrieve real-time information and ground AI responses. Includes code examples.

The web search tool in Foundry Agent Service enables the agent’s Foundry model to retrieve and ground responses with real-time information from the public web before generating output. When enabled, the model can return up-to-date answers with inline citations, helping you build agents that provide current, factual information to users.

• Web Search uses Grounding with Bing Search and Grounding with Bing Custom Search, which are First Party Consumption Services governed by these Grounding with Bing terms of use and the Microsoft Privacy Statement.
• The Microsoft Data Protection Addendum doesn’t apply to data sent to Grounding with Bing Search and Grounding with Bing Custom Search. When you use Grounding with Bing Search and Grounding with Bing Custom Search, data transfers occur outside compliance and geographic boundaries.
• Use of Grounding with Bing Search and Grounding with Bing Custom Search incurs costs. See pricing for details.
• See the management section for information about how Azure admins can manage access to use of web search.

Consider adding this tool using a toolbox. By using a toolbox, you are able to reuse the tool across agents and runtimes, as well as centralizing credential management, versioning, and policy enforcement through a managed MCP endpoint. See the toolbox quickstart.

Usage support

The following table shows SDK and setup support.

Microsoft Foundry support	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Basic agent setup	Standard agent setup
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Prerequisites

• A basic or standard agent environment
• The latest SDK package. The .NET SDK is currently in preview. See the quickstart for details.
• Foundry User role on the Foundry project to create and run agents.

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

• Foundry Project Manager role on the Foundry project if you create the remote-tool project connection for domain-restricted search.
• Azure credentials configured for authentication (such as DefaultAzureCredential).
• Your Foundry project endpoint URL and a model deployment name.

Choose a web grounding scenario

Scenario	Choose it when	Start here
General Web Search	Your agent needs current information from the public web without a separate Bing resource or project connection.	Add web search directly to a prompt agent.
Domain-restricted Bing Custom Search	Search results must come from public domains configured in your Bing Custom Search instance.	Configure domain-restricted search.
Deep research	Your o3-deep-research agent needs multi-step research and synthesis.	Use direct web search for deep research.
Bing grounding tools	You need the explicit bing_grounding or bing_custom_search_preview tool type with a Bing project connection.	Use Grounding with Bing Search tools.

Add web search directly to an agent

Start with the Prompt Agents tab. It adds WebSearchTool directly to a server-side agent and doesn’t require a toolbox or a separate Bing project connection. This path provides the shortest route to a grounded response with citations.

The Hosted Agents tab uses WebSearchToolboxTool to add web search to a toolbox, then connects to the toolbox MCP endpoint. Keep the direct-agent and toolbox tool types separate because they apply to different API surfaces.

For information on optimizing tool usage, see best practices.

Configure the web search tool

You can configure web search behavior when you create your agent.

Web search response format over MCP

When Web Search returns results over MCP, the response is a resource content item containing the synthesized answer with inline Markdown source links. URL citations are in content[].resource._meta.annotations[]. For example:

{
  "jsonrpc": "2.0",
  "id": "ws-call-1",
  "result": {
    "_meta": {
      "tool_configuration": {
        "type": "web_search",
        "name": "web-search-default"
      }
    },
    "content": [
      {
        "type": "resource",
        "resource": {
          "uri": "about:web-search-answer",
          "mimeType": "text/plain",
          "text": "Here are the latest updates on Azure OpenAI Service...\n\n- **GPT-image-1 Release (January 7, 2026)** Microsoft introduced GPT-image-1 ([serverless-solutions.com](https://...)).\n\n..."
        },
        "annotations": {
          "audience": ["assistant"]
        },
        "_meta": {
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.serverless-solutions.com/blog/...",
              "title": "Microsoft expands Foundry with powerful new OpenAI models",
              "start_index": 741,
              "end_index": 879
            }
          ],
          "action": {
            "type": "search",
            "query": "Azure OpenAI service updates 2026",
            "queries": ["Azure OpenAI service updates 2026"]
          },
          "response_id": "resp_001fcebcc300..."
        }
      }
    ],
    "isError": false
  }
}

Optional parameters for general web search

• user_location: Helps web search return results relevant to a user’s geography. Use an approximate location when you want results localized to a country/region/city.
• search_context_size: Controls how much context window space to use for the search. Supported values are low, medium, and high. The default is medium.

Security and privacy considerations

• Treat web search results as untrusted input. Validate and sanitize data before you use it in downstream systems.
• Avoid sending secrets or sensitive personal data in prompts that might be forwarded to external services.
• Review the terms, privacy, and data boundary notes in the preview section of this article before enabling web search in production.

Known limitations

For information about web search behavior and limitations in the Responses API, see Web search with the Responses API.

Troubleshooting

Issue	Cause	Resolution
Web search isn’t used and no citations appear	Model didn’t determine web search was needed	Update your instructions to explicitly allow web search for up-to-date questions, and ask a query that requires current information.
Requests fail after enabling web search	Web search is disabled at the subscription level	Ask an admin to enable web search. See Administrator control for the web search tool.
REST requests return authentication errors	Bearer token is missing, expired, or has insufficient permissions	Refresh your token and confirm your access to the project and agent.
Search returns outdated information	Web content not recently indexed	Refine your query to explicitly request the most recent information. Results depend on Bing’s indexing schedule.
No results for specific topics	Query too narrow or content not indexed	Broaden your search query. Some niche topics might have limited web coverage.
Rate limiting errors (429)	Too many requests in a short time period	Implement exponential backoff and retry logic. Consider spacing out requests.
Inconsistent citation formatting	Response format varies by query type	Standardize citation handling in your application code. Parse both inline and reference-style citations.
Tool not available for deployment	Regional or model limitations	Confirm web search is available in your region and with your model deployment. Check tool best practices.

Administrator control for the web search tool

You can enable or disable the web search tool in Foundry Agent Service at the subscription level by using Azure CLI. This setting applies to all accounts within the specified subscription.

Prerequisites

Before running the following commands, make sure that you:

1. Have Azure CLI installed.
2. Are signed in to Azure by using az login.
3. Activate Contributor at subscription scope just in time through Microsoft Entra PIM. Subscription scope is required because this setting applies to all Foundry resources in the subscription. Deactivate the role after changing the setting. Day-to-day agent developers and runtime users don’t need this role.

Disable web search

To disable the web search tool for all accounts in a subscription, run the following command:

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

This command disables web search across all accounts in the specified subscription.

Enable web search

To enable the web search tool, run the following command:

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

This command enables web search functionality for all accounts in the subscription.

Next steps

Review tool best practices

Set up an agent environment