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.

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.
• Azure credentials configured for authentication (such as DefaultAzureCredential).
• Your Foundry project endpoint URL and a model deployment name.

Code examples

See best practices for information on optimizing tool usage.

Configure the web search tool

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

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. Have Owner or Contributor access to the subscription.

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