Cara menggunakan Grounding dengan Pencarian Kustom Bing (pratinjau)

2025-07-10

Gunakan artikel ini untuk menemukan instruksi langkah demi langkah dan sampel kode untuk menggunakan alat Pencarian Kustom Grounding dengan Bing di Azure AI Foundry Agent Service.

Navigasi ke layar Agen untuk agen Anda di portal Azure AI Foundry, gulir ke bawah panel Penyiapan di sebelah kanan ke pengetahuan. Kemudian pilih Tambahkan.
Pilih alat Penentuan Dasar dengan Pencarian Khusus Bing.
Pilih untuk membuat koneksi baru, atau gunakan koneksi yang sudah ada
1. Untuk koneksi baru, pilih Grounding Anda dengan sumber daya Pencarian Kustom Bing.
Setelah Anda tersambung ke sumber daya, pilih nama konfigurasi.
Simpan alat dan mulai mengobrol dengan agen Anda.

Prasyarat

Titik akhir Proyek Azure AI Foundry Anda.

Anda dapat menemukan titik akhir Anda di gambaran umum untuk proyek Anda di portal Azure AI Foundry, di bawah Pustaka>Azure AI Foundry.

Simpan titik akhir ini ke variabel lingkungan bernama PROJECT_ENDPOINT.
Nama sumber daya Grounding dengan Pencarian Kustom Bing Anda. Anda dapat menemukannya di portal Azure AI Foundry dengan memilih Pusat manajemen dari menu navigasi kiri. Kemudian memilih Sumber daya tersambung.

Simpan nama sumber daya ini ke variabel lingkungan bernama BING_CUSTOM_CONNECTION_NAME.
Nama konfigurasi Grounding dengan Pencarian Kustom Bing Anda, yang berisi URL yang ingin Anda izinkan atau blokir. Anda dapat menemukannya dengan menavigasi ke halaman gambaran umum untuk sumber daya Anda di portal Microsoft Azure. Pilih Konfigurasi, lalu pilih konfigurasi Anda.

Simpan nama koneksi ini ke variabel lingkungan bernama BING_CUSTOM_CONNECTION_NAME.
Nama penyebaran untuk model Anda. Anda dapat menemukannya di Model + Titik Akhir di menu navigasi kiri.

Simpan nama penyebaran model Anda sebagai variabel lingkungan bernama MODEL_DEPLOYMENT_NAME.

Membuat klien proyek

Buat objek klien, yang akan berisi string koneksi untuk menyambungkan ke proyek AI Anda dan sumber daya lainnya.

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

Membuat Agen dengan Grounding dengan alat Pencarian Kustom Bing diaktifkan

Untuk menyediakan alat Grounding Bing dengan Pencarian Kustom kepada agen Anda, gunakan koneksi untuk menginisialisasi alat dan menghubungkannya dengan agen.

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

Buat utas

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

Membuat eksekusi dan memeriksa output

Buat eksekusi dan amati bahwa model menggunakan alat Grounding with Bing Search untuk memberikan respons terhadap pertanyaan pengguna.

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

Penting

REST API ini memungkinkan pengembang untuk memanggil alat Grounding dengan Bing Custom Search melalui Azure AI Foundry Agent Service. Ini tidak mengirim panggilan ke Grounding dengan Bing Custom Search API secara langsung.
Sampel berikut berlaku jika Anda menggunakan sumber daya Proyek Azure AI Foundry dengan alat Microsoft Fabric melalui panggilan REST API
ID koneksi Anda harus dalam format ini: /subscriptions/<sub-id>/resourceGroups/<your-rg-name>/providers/Microsoft.CognitiveServices/accounts/<your-ai-services-name>/projects/<your-project-name>/connections/<your-bing-connection-name>

Ikuti Mulai Cepat REST API untuk mengatur nilai yang tepat untuk AGENT_TOKEN variabel lingkungan, AZURE_AI_FOUNDRY_PROJECT_ENDPOINT, dan API_VERSION.

Membuat Agen dengan Grounding dengan alat Pencarian Kustom Bing diaktifkan

Untuk menyediakan alat Grounding Bing dengan Pencarian Kustom kepada agen Anda, gunakan koneksi untuk menginisialisasi alat dan menghubungkannya dengan agen. Anda dapat menemukan koneksi Anda di bagian sumber daya yang terhubung dari proyek Anda di portal 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",
                    }
                ]
            }
          }
        ]
      }'

Buat utas

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

Tambahkan pertanyaan pengguna ke topik

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

Membuat eksekusi dan memeriksa output

Jalankan proses dan amati bahwa model menggunakan alat Grounding dengan Bing Custom Search untuk memberikan respons terhadap pertanyaan pengguna.

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

Mengambil status proses

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

Dapatkan respons agen

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

Bagikan melalui

Cara menggunakan Grounding dengan Pencarian Kustom Bing (pratinjau)

Prasyarat

Membuat klien proyek

Membuat Agen dengan Grounding dengan alat Pencarian Kustom Bing diaktifkan

Buat utas

Membuat eksekusi dan memeriksa output

Membuat Agen dengan Grounding dengan alat Pencarian Kustom Bing diaktifkan

Buat utas

Tambahkan pertanyaan pengguna ke topik

Membuat eksekusi dan memeriksa output

Mengambil status proses

Dapatkan respons agen

Saran dan Komentar

Sumber Daya Tambahan: