> ## Documentation Index
> Fetch the complete documentation index at: https://hobbyist-e43fa225.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview of web grounding capabilities in Foundry
> Learn how to choose the right web grounding tool for your Microsoft Foundry agents. Compare Web Search, Grounding with Bing Search, and Bing Custom Search.
Web grounding tools in Microsoft Foundry Agent Service connect your agents to real-time public web data, overcoming the knowledge cutoff of the agent's Foundry model. 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:
1. **Query formulation**: The agent identifies information gaps and constructs search queries based on the user's input.
2. **Search execution**: The grounding tool submits queries to Bing and retrieves results.
3. **Information synthesis**: The agent processes search results and integrates findings into responses.
4. **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](../../../agents/environment-setup).
* The latest SDK package for your language (Python: `azure-ai-projects`, C#: `Azure.AI.Projects` and `Azure.AI.Extensions.OpenAI`, JavaScript: `@azure/ai-projects`). See the [quickstart](/get-started/get-started-code) 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 **Foundry Project Manager** role to create project connections. For details, see [agent environment setup](../../../agents/environment-setup).
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.
Web Search, Grounding with Bing Search, and Grounding with Bing Custom Search are [First Party Consumption Services](https://www.microsoft.com/licensing/terms/product/Glossary/EAEAS#:~:text=First-Party%20Consumption%20Services) with [terms for online services](https://www.microsoft.com/licensing/terms/product/ForOnlineServices/EAEAS). They're governed by the [Grounding with Bing terms of use](https://www.microsoft.com/en-us/bing/apis/grounding-legal-enterprise) and the [Microsoft Privacy Statement](https://go.microsoft.com/fwlink/?LinkId=521839\&clcid=0x409).
The Microsoft [Data Protection Addendum](https://aka.ms/dpa) 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 details](https://www.microsoft.com/en-us/bing/apis). Azure admins can restrict access to these tools. For details, see [Administrator control for the Web Search tool](/tools-and-knowledge/web-search#administrator-control-for-the-web-search-tool).
## Determine the best tool for your use cases
If you're just getting started, use [Web Search](/tools-and-knowledge/web-search). It requires no extra Azure resources and is the simplest way to add web grounding to your agent.
If you're migrating from Grounding with Bing Search on the classic agents platform, both [Web Search](/tools-and-knowledge/web-search) and [Grounding with Bing Search](/tools-and-knowledge/bing-tools) are GA options on the new agents API. Web Search requires no separate Bing resource. Grounding with Bing Search offers more parameters and supports non-OpenAI models deployed directly on Azure.
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](/tools-and-knowledge/web-search) (recommended) | [Grounding with Bing Search](/tools-and-knowledge/bing-tools) |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Stage** | GA | 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](/tools-and-knowledge/web-search#optional-parameters-for-general-web-search) | - `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](/tools-and-knowledge/bing-tools#optional-parameters) |
| **Data boundary** | Data flows outside Azure compliance boundary | Data flows outside Azure compliance boundary |
| **Supported models** | Azure OpenAI models | Azure OpenAI models and Foundry Models sold by Azure (non-OpenAI models deployed directly on Azure) |
### Use case 2: Grounding from specific domains you defined
| | [Web Search](/tools-and-knowledge/web-search) (recommended) | [Grounding with Bing Custom Search](/tools-and-knowledge/bing-tools) |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Stage** | GA (requires a Bing Custom Search instance) | Preview |
| **Restrict to custom domains** | Supported — use `custom_search_configuration` to pre‑define allowed or blocked domains (requires creating a Bing Custom Search resource + instance) | Supported — use `custom_search_configuration` to pre‑define allowed or blocked domains (requires creating a Bing Custom Search resource + instance) |
| **Other parameters** | - `user_location`: Provides geo‑relevant results
- `search_context_size`: low/medium/high (default: medium)
Learn more about [Web Search parameters](/tools-and-knowledge/web-search#domain-restricted-search-with-bing-custom-search) | - `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](/tools-and-knowledge/bing-tools#optional-parameters) |
| **Supported models** | Azure OpenAI models | Azure OpenAI models and Models sold by Azure |
## Common questions
### Which tool should I use if I'm just getting started?
Use [Web Search](/tools-and-knowledge/web-search). It requires no additional Azure resources, handles Bing resource management automatically, and provides geo-relevant results with the `user_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 [Web Search](/tools-and-knowledge/web-search). 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, Grounding with Bing Search, and Grounding with Bing Custom Search (preview) incur costs beyond standard Azure OpenAI usage. See [pricing details](https://www.microsoft.com/en-us/bing/apis).
## 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](/tools-and-knowledge/web-search#administrator-control-for-the-web-search-tool). |
| Unexpected costs | Web grounding tools have usage-based pricing. | Review [pricing details](https://www.microsoft.com/en-us/bing/apis) and implement rate limiting if needed. |
## Related content
* [Use the Web Search tool](/tools-and-knowledge/web-search)
* [Use Grounding with Bing Search and Grounding with Bing Custom Search](/tools-and-knowledge/bing-tools)
* [Best practices for using tools in Foundry Agent Service](/agents/tool-best-practice)
* [Agent environment setup](../../../agents/environment-setup)
* [Web grounding pricing](https://www.microsoft.com/en-us/bing/apis)