如何使用“使用必应自定义搜索提供事实依据（预览版）”功能

1. 在 Azure AI Foundry 门户中，导航到你的代理的“代理”屏幕，向下滚动“知识”右侧的“设置”窗格。 然后选择“添加”。

   

2. 选择“使用必应自定义搜索提供事实依据”工具。

3. 选择以创建新连接或使用现有连接

   1. 对于新连接，选择你的“使用必应自定义搜索提供事实依据”资源。

4. 连接到资源后，选择配置名称。

5. 保存该工具并开始与代理聊天。

先决条件

• Azure AI Foundry 项目终结点。

  您可以在项目的 概述中，通过 Azure AI Foundry 门户下的库>Azure AI Foundry找到您的终结点。

  

  将此终结点保存到名为PROJECT_ENDPOINT的环境变量中。

• “通过必应自定义搜索提供事实依据”资源名称的名称。 可以通过从左侧导航菜单中选择 管理中心 ，在 Azure AI Foundry 门户中找到它。 然后选择 “连接的资源”。

  

  将此资源名称保存到名为 BING_CUSTOM_CONNECTION_NAME 的环境变量中。

• “通过必应自定义搜索提供事实依据”配置的名称，其中包含要允许或禁止的 URL。 可以通过导航到 Azure 门户中资源的概述页来找到它。 选择 “配置”，然后选择配置。

  

  将此配置名称保存到名为 的 BING_CUSTOM_INSTANCE_NAME环境变量。

• 模型部署名称的名称。 可以在左侧导航菜单中的 “模型 + 终结点 ”中找到它。

  

  将模型部署名称保存为名为MODEL_DEPLOYMENT_NAME的环境变量。

创建项目客户端

创建一个客户端对象，其中包含用于连接到 AI 项目和其他资源的连接字符串。

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(),
)

创建已启用“使用必应自定义搜索提供事实依据”工具的代理

要使“使用必应自定义搜索查找事实依据”工具可供代理使用，请使用连接来初始化该工具并将其附加到代理。

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 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 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})")

请按照 REST API 快速入门 为环境变量 AGENT_TOKEN、AZURE_AI_FOUNDRY_PROJECT_ENDPOINT 和 API_VERSION 设置正确的值。

创建已启用“使用必应自定义搜索提供事实依据”工具的代理

要使“使用必应自定义搜索查找事实依据”工具可供代理使用，请使用连接来初始化该工具并将其附加到代理。 可以在 Azure AI Foundry 门户中项目的“已连接资源”部分找到连接。

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",
                    }
                ]
            }
          }
        ]
      }'

创建线程

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 ''

将用户问题添加到线程

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>"
    }'

创建运行并检查输出

创建运行并观察模型是否使用“使用必应自定义搜索查找事实依据”工具来响应用户的问题。

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",
  }'

获取运行状态

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

检索代理响应

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