How to use Grounding with Bing Custom Search (preview)

1. 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.

   

2. Select the Grounding with Bing Custom Search tool.

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

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

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

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

Prerequisites

• Your Azure AI Foundry Project endpoint.

  You can find your endpoint in the overview for your project in the Azure AI Foundry portal, under Libraries > Azure AI Foundry.

  

  Save this endpoint to an environment variable named PROJECT_ENDPOINT.

• The name of your Grounding with Bing Custom Search resource name. You can find it in the Azure AI Foundry portal by selecting Management center from the left navigation menu. Then selecting Connected resources.

  

  Save this resource name to an environment variable named BING_CUSTOM_CONNECTION_NAME.

• The name of your Grounding with Bing Custom Search configuration, which contains the URLs you want to allow or disallow. You can find it by navigating to the overview page for your resource in the Azure portal. Select Configurations, then select your configuration.

  

  Save this connection name to an environment variable named BING_CUSTOM_CONNECTION_NAME.

• The names of your model's deployment name. You can find it in Models + Endpoints in the left navigation menu.

  

  Save the name of your model deployment name as an environment variable named MODEL_DEPLOYMENT_NAME.

Create a project client

Create a client object, which will contain the connection string for connecting to your AI project and other resources.

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import BingCustomSearchTool


# Create an Azure AI Client from an endpoint, copied from your Azure AI Foundry project.
# You need to login to Azure subscription via Azure CLI and set the environment variables
project_endpoint = os.environ["PROJECT_ENDPOINT"]  # Ensure the PROJECT_ENDPOINT environment variable is set

# Create an AIProjectClient instance
project_client = AIProjectClient(
    endpoint=project_endpoint,
    credential=DefaultAzureCredential(),
)

Create an Agent with the Grounding with Bing Custom Search tool enabled

To make the Grounding with Bing Custom Search tool available to your agent, use a connection to initialize the tool and attach it to the agent.

bing_custom_connection = project_client.connections.get(name=os.environ["BING_CUSTOM_CONNECTION_NAME"])
conn_id = bing_custom_connection.id

print(conn_id)

configuration_name = os.environ["BING_CUSTOM_INSTANCE_NAME"]
# Initialize Bing Custom Search tool with connection id and configuration name
bing_custom_tool = BingCustomSearchTool(connection_id=conn_id, instance_name=configuration_name)

# Create agent with the bing custom search tool and process assistant run
with project_client:
    agents_client = project_client.agents

    agent = agents_client.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-agent",
        instructions="You are a helpful agent",
        tools=bing_custom_tool.definitions,
    )
    print(f"Created agent, ID: {agent.id}")

Create a thread

# Create thread for communication
thread = agents_client.threads.create()
print(f"Created thread, ID: {thread.id}")

# Create message to thread
message = agents_client.messages.create(
    thread_id=thread.id,
    role="user",
    content="How many medals did the USA win in the 2024 summer olympics?",
)
print(f"Created message, ID: {message.id}")

Create a run and check the output

Create a run and observe that the model uses the Grounding with Bing Search tool to provide a response to the user's question.

# Create and process Agent run in thread with tools
run = agents_client.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
print(f"Run finished with status: {run.status}")

if run.status == "failed":
    print(f"Run failed: {run.last_error}")

# Uncomment these lines to delete the Agent when done
#agents_client.delete_agent(agent.id)
#print("Deleted agent")

# Fetch and log all messages
messages = agents_client.messages.list(thread_id=thread.id)
for msg in messages:
    if msg.text_messages:
        for text_message in msg.text_messages:
            print(f"Agent response: {text_message.text.value}")
        for annotation in msg.url_citation_annotations:
            print(f"URL Citation: [{annotation.url_citation.title}]({annotation.url_citation.url})")

Follow the REST API Quickstart to set the right values for the environment variables AGENT_TOKEN, AZURE_AI_FOUNDRY_PROJECT_ENDPOINT and API_VERSION.

Create an Agent with the Grounding with Bing Custom Search tool enabled

To make the Grounding with Bing Custom Search tool available to your agent, use a connection to initialize the tool and attach it to the agent. You can find your connection in the connected resources section of your project in the Azure AI Foundry portal.

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/assistants?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "instructions": "You are a helpful agent.",
        "name": "my-agent",
        "model": "gpt-4o",
        "tools": [
          {
            "type": "bing_custom_search",
            "bing_custom_search": {
                "search_configurations": [
                    {
                        "connection_id": /subscriptions/<sub-id>/resourceGroups/<your-rg-name>/providers/Microsoft.CognitiveServices/accounts/<your-ai-services-name>/projects/<your-project-name>/connections/<your-bing-connection-name>,
                        "instance_name": <your_custom_search_configuration_name>, 
                        "count": 7,
                        "market": "en-US", 
                        "set_lang": "en",
                        "freshness": "day",
                    }
                ]
            }
          }
        ]
      }'

Create a thread

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

Add a user question to the thread

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "user",
      "content": "<ask a question tailored towards your web domains>"
    }'

Create a run and check the output

Create a run and observe that the model uses the Grounding with Bing Custom Search tool to provide a response to the user's question.

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Retrieve the status of the run

curl --request GET \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN"

Retrieve the agent response

curl --request GET \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=$API_VERSION \
  -H "Authorization: Bearer $AGENT_TOKEN"