Edit

Share via

Grounding with Bing Custom Search (preview)

Grounding with Bing Custom Search tool allows your Azure AI Agents to search within a configurable set of public web domains. It allows you to define the parts of the web you want to draw from so users only see relevant results from the domains and subdomains of your choosing. You need to first create a Grounding with Bing Custom Search resource in Azure portal.

Once the resource is deployed, go to Configurations in the Azure AI Foundry portal, and create a configuration instance to include content only from websites that your users care about. Instructions about how to create your custom configuration can be found in the setup section.

Once the tool is configured, you can connect it to your Azure AI Agent. When a user sends a query, the agent will decide if Grounding with Bing Custom Search should be leveraged or not. If so, it will use Bing to search over the domains you specify and return relevant chunks. Lastly, Azure AI Agents will use the returned chunks to generate a response to return to the user

Important

  • Your usage of Grounding with Bing Custom Search can incur costs. See the pricing page for details.
  • By creating and using a Grounding with Bing Custom Search resource through code-first experience, such as Azure CLI, or deploying through deployment template, you agree to be bound by and comply with the terms of use, which may be updated periodically.
  • When you use Grounding with Bing Custom Search, your customer data is transferred outside of the Azure compliance boundary to the Grounding with Bing Custom Search service. Grounding with Bing Custom Search isn't subject to the same data processing terms (including location of processing) and doesn't have the same compliance standards and certifications as the Azure AI Foundry Agent Service, as described in the Grounding with Bing Custom Search Terms of Use. It's your responsibility to assess whether use of Grounding with Bing Custom Search in your agent meets your needs and requirements.

How Grounding with Bing Custom Search works

The user query is the message that an end user sends to an agent, such as "what water bottle is available?" (assuming you create an instance to Contoso product websites). Instructions are the system message a developer can provide to share context and provide instructions to the AI model on how to use various tools or behave.

When a user sends a query, the customer's AI model deployment first processes it (using the provided instructions) to later perform a Bing Custom Search query (which is visible to developers). Grounding with Bing Custom Search returns relevant search results to the customer's model deployment, which then generates the final output.

Note

When using Grounding with Bing Custom Search, the Bing Custom Search query, the configuration instance, tool parameters, and your resource key are sent to Bing, and no end user-specific information is included. Your resource key is sent to Bing solely for billing and rate limiting purposes.

The authorization will happen between Grounding with Bing Custom Search service and Azure AI Foundry Agent service. Any Bing Custom Search query that is generated and sent to Bing for the purposes of grounding is transferred, along with the resource key and configuration instance, outside of the Azure compliance boundary to the Grounding with Bing Custom Search service. Grounding with Bing Custom Search is subject to Bing's terms and don't have the same compliance standards and certifications as the Azure AI Foundry Agent Service, as described in the Grounding with Bing Custom Search Terms of Use. It's your responsibility to assess whether the use of Grounding with Bing Custom Search in your agent meets your needs and requirements.

Developers and end users don't have access to raw content returned from Grounding with Bing Custom Search. The model response, however, includes citations with links to the websites used to generate the response and is allowed to be stored using the mechanisms provided by the Agents Service. You can retrieve the model response by accessing the data in the thread that was created. These references must be retained and displayed in the exact form provided by Microsoft, as per Grounding with Bing Custom Search's Use and Display Requirements.

Setup

Note

You can only use Azure OpenAI models with Grounding with Bing Custom Search.

  1. Create an Azure AI Agent by following the steps in the quickstart.

  2. Create a Grounding with Bing Custom Search resource in the Azure portal. You need to have owner or contributor role in your subscription or resource group to create it. Make sure you create this Grounding with Bing Custom Search resource in the same resource group as your Azure AI Agent, AI Project, and other resources.

  3. After you have created a Grounding with Bing Custom Search resource, you can create a configuration instance.

    1. Go to the Grounding with Bing Custom Search resource created

    2. Select Resource Management on the left panel.

    3. Select Configurations.

    4. Select Create a new configuration.

When you create or update a configuration, enter the following information:

  1. The name of your configuration. This can be changed at any time.

  2. Include URLs to define your search slices in at least one of the following fields:

    Note

    Grounding with Bing Custom Search only returns results for domains and webpages that are public and have been indexed by Bing.

    • Domain (for example, https://www.microsoft.com)
    • Domain and path (for example, https://www.microsoft.com/surface)
    • Webpage (for example, https://www.microsoft.com/en-us/p/surface-earbuds/8r9cpq146064)

    1. Allowed domains to search against. For allowed domains, if you want to include subpages, please make sure the domains have at most 2 levels of subpages.

    2. Blocked domains to exclude from the search space.

  3. Determine if you want to include subpages. A subpage slice specifies a domain path. Bing searches all content found at and below the path. You can specify a maximum of two subfolders in the path. For example, www.microsoft.com/windows/.

  4. Adjust ranking if needed.

  5. Navigate to the Agents screen for your agent in the Azure AI Foundry portal, scroll down the Setup pane on the right to knowledge. Then select Add.

    A screenshot of the agents screen in the AI Foundry portal.

  6. Select the Grounding with Bing Custom Search tool.

  7. Select to create a new connection, or use an existing connection

    1. For a new connection, select your Grounding with Bing Custom Search resource.

  8. Once you have connected to a resource, select the configuration name.

  9. Save the tool and start chatting with your agent.

Custom Search configuration capabilities

Grounding with Bing Custom Search is a powerful tool that allows you to select a subspace of the web to limit your Agent’s grounding knowledge. Here you can find a few tips for how to take the maximum advantage of this capability:

  1. If you own a public site that you want to include in the search but Bing hasn’t indexed, see the Bing webmaster documentation for details about getting your site indexed. The webmaster documentation also provides details about getting Bing to crawl your site if the index is out of date.

  2. You can only block certain domains and perform a search against the rest of the Web (a competitor’s site, for example).

Optional parameters

When you add the Grounding with Bing Custom Search tool to your agent, you can pass the following parameters. These parameters will impact the Grounding with Bing Custom Search tool output, and the AI model might not fully use all of the outputs. See the code examples for information on API version support and how to pass these parameters.

Name Value Type Required
count The number of search results to return in the response. The default is 5 and the maximum value is 50. The actual number delivered may be less than requested. It's possible for multiple pages to include some overlap in results. This parameter affects only web page results. It's possible that AI model might not use all search results returned by Bing. UnsignedShort No
freshness Filter search results by the following case-insensitive age values:
Day: Return webpages that Bing discovered within the last 24 hours.
Week: Return webpages that Bing discovered within the last 7 days.
Month: Return webpages that Bing discovered within the last 30 days. To get articles discovered by Bing during a specific timeframe, specify a date range in the form: YYYY-MM-DD..YYYY-MM-DD. For example, freshness=2019-02-01..2019-05-30. To limit the results to a single date, set this parameter to a specific date. For example, freshness=2019-02-04.		 String No
market The market where the results come from. Typically, mkt is the country where the user is making the request from. However, it could be a different country if the user isn't located in a country where Bing delivers results. The market must be in the form: <language>-<country/region>. For example, en-US. The string is case insensitive. For a list of possible market values, see Market codes. If known, you're encouraged to always specify the market. Specifying the market helps Bing route the request and return an appropriate and optimal response. If you specify a market that is not listed in Market codes, Bing uses a best fit market code based on an internal mapping that is subject to change. String No
set_lang The language to use for user interface strings. You may specify the language using either a 2-letter or 4-letter code. Using 4-letter codes is preferred.
For a list of supported language codes, see Bing supported languages.
Bing loads the localized strings if setlang contains a valid 2-letter neutral culture code (fr) or a valid 4-letter specific culture code (fr-ca). For example, for fr-ca, Bing loads the fr neutral culture code strings.
If setlang isn't valid (for example, zh) or Bing doesn’t support the language (for example, af, af-na), Bing defaults to en (English).
To specify the 2-letter code, set this parameter to an ISO 639-1 language code.
To specify the 4-letter code, use the form <language>-<country/region> where <language> is an ISO 639-1 language code (neutral culture) and <country/region> is an ISO 3166 country/region (specific culture) code. For example, use en-US for United States English.
Although optional, you should always specify the language. Typically, you set setLang to the same language specified by mkt unless the user wants the user interface strings displayed in a different language.		 String No