Web grounding tools overview
Web grounding tools in Microsoft Foundry Agent Service connect your agents to real-time public web data, overcoming the knowledge cutoff that limits large language models. For example, you can ask questions such as “what is the top AI news today” and receive current, cited answers.How web grounding works
The grounding process involves several key steps:- Query formulation: The agent identifies information gaps and constructs search queries based on the user’s input.
- Search execution: The grounding tool submits queries to Bing and retrieves results.
- Information synthesis: The agent processes search results and integrates findings into responses.
- Source attribution: The agent provides transparency by citing search sources with URLs.
Prerequisites
Before using any web grounding tool, ensure you have:- A basic or standard agent environment.
- The latest prerelease SDK package for your language (Python:
azure-ai-projects, C#:Azure.AI.Projects.OpenAI, JavaScript:@azure/ai-projects). See the quickstart for installation steps. - An Azure OpenAI model deployment in your Foundry project.
Web Search requires no extra roles beyond your Foundry project access. Grounding with Bing Search and Grounding with Bing Custom Search require Contributor or Owner role to create Bing resources, and Azure AI Project Manager role to create project connections. For details, see agent environment setup.
- Web Search (preview) uses Grounding with Bing Search and Grounding with Bing Custom Search are First Party Consumption Services with terms for online services. They’re governed by the 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 or Grounding with Bing Custom Search. When you use these services, your data flows outside the Azure compliance and Geo boundary. This also means use of these services waives all elevated Government Community Cloud security and compliance commitments, including data sovereignty and screened/citizenship-based support, as applicable.
- 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 Grounding with Bing Search and Grounding with Bing Custom Search.
Determine the best tool for your use cases
If you’re just getting started, use Web Search (preview). It requires no extra Azure resources and is the simplest way to add web grounding to your agent. The following use cases help you compare the available tools. Use case 1 covers general web search, where both Web Search and Grounding with Bing Search can retrieve results from the public web. Use case 2 covers domain-restricted search, which only Grounding with Bing Custom Search supports.Use case 1: Grounding from general web indexed by Bing
| Web Search (recommended) | Grounding with Bing Search | |
|---|---|---|
| Stage | Preview | GA |
| Grounding with Bing resource | Managed by Microsoft | Managed by you — requires creating a Grounding with Bing Search resource first |
| Supported parameters | - user_location: Provides geo‑relevant results- search_context_size: low/medium/high (default: medium)Learn more about Web Search parameters | - count: the maximum of results returned by Bing - freshness: specifies the period for the search results- market: specifies the region for the search results - set_lang: specifies the language for the search results Learn more about Bing Search parameters |
| Data boundary | Data flows outside Azure compliance boundary | Data flows outside Azure compliance boundary |
| Supported models | Azure OpenAI models | Azure OpenAI models and Azure direct models (non-OpenAI models deployed directly on Azure) |
Use case 2: Grounding from specific domains you defined
| Grounding with Bing Custom Search | |
|---|---|
| Stage | Preview |
| Pre-defined domains | Supported — use custom_search_configuration to pre‑define allowed or blocked domains (requires creating a Bing Custom Search resource + instance) |
| Other parameters | - count: the maximum number of results returned by Bing - freshness: specifies the period for the search results- market: specifies the region for the search results - set_lang: specifies the language for the search results Learn more about Bing Custom Search parameters |
| Supported models | Azure OpenAI models and Azure direct models |
Common questions
Which tool should I use if I’m just getting started?
Use Web Search (preview). It requires no additional Azure resources, handles Bing resource management automatically, and provides geo-relevant results with theuser_location parameter.
Can I use web grounding tools with network-secured Foundry projects?
Web grounding tools don’t respect VPN or private endpoints. They act as public endpoints. Consider this security implication when using network-secured Foundry with these tools.How do I restrict search results to specific websites?
Use Grounding with Bing Custom Search (preview). This tool lets you define an allow-list or block-list of domains, so search results come only from sources you approve.Are there additional costs for web grounding?
Yes. Web Search (preview), Grounding with Bing Search and Grounding with Bing Custom Search (preview) incur costs beyond standard Azure OpenAI usage. See pricing details.Troubleshooting
| Issue | Likely cause | Resolution |
|---|---|---|
| Agent doesn’t use web grounding | Tool not configured or model doesn’t support the tool. | Verify the tool is added to your agent definition. Use tool_choice="required" to force tool use. Check that your model deployment supports the tool. |
| No citations in response | The model generated a response without using search results. | Add explicit instructions to always cite sources. Use tool_choice="required" to ensure tool invocation. |
| Search results aren’t relevant | Query formulation didn’t capture user intent. | Improve agent instructions to guide query construction. For Bing tools, adjust market and set_lang parameters. |
| Tool blocked by administrator | Your organization disabled web grounding tools. | Contact your Azure administrator to enable access. See administrator control. |
| Unexpected costs | Web grounding tools have usage-based pricing. | Review pricing details and implement rate limiting if needed. |