Poradnik: tworzenie kompleksowego agentowego rozwiązania do wyszukiwania za pomocą Wyszukiwanie AI platformy Azure

Dowiedz się, jak utworzyć inteligentne rozwiązanie z obsługą MCP, które integruje Wyszukiwanie AI platformy Azure z usługą Foundry Agent Service do agentowego pobierania. Tej architektury można używać w przypadku aplikacji konwersacyjnych, które wymagają złożonego rozumowania w dużych domenach wiedzy, takich jak obsługa klienta lub rozwiązywanie problemów technicznych.

W tym samouczku w dwóch miejscach są używane interfejsy API REST w wersji zapoznawczej. Baza wiedzy używa output_mode i retrieval_reasoning_effort (wersja zapoznawcza), aby jawnie określić odpowiedź ekstrakcyjną i minimalne wnioskowanie, chociaż równoważne działanie jest zasadniczo dostępne. Połączenie w projekcie używa RemoteTool (wersja zapoznawcza) oraz tożsamości zarządzanej przypisanej do projektu do uwierzytelniania w usłudze Wyszukiwanie AI platformy Azure.

W tym samouczku:

Wymagania wstępne

• Usługa Wyszukiwanie AI platformy Azure w dowolnym regionie z funkcjami agentowymi.

• Projekt Microsoft Foundry i zasób. Podczas tworzenia projektu zasób jest tworzony automatycznie.

• Model osadzania tekstu wdrożony w projekcie na potrzeby wektoryzacji czasu zapytania. To rozwiązanie używa metody text-embedding-3-large.

• Moduł LLM wdrożony w projekcie dla agenta. To rozwiązanie używa metody gpt-5-mini.

  Modele rodziny GPT-4 są przestarzałe. Aby uzyskać informacje na temat dat wycofania i bieżącego stanu w usłudze Microsoft Foundry, zobacz Model retirement schedule — Microsoft Foundry.

• Uprawnienie do uzyskiwania dostępu do zasobów Wyszukiwanie AI platformy Azure i Microsoft Foundry oraz zarządzania nimi. Aby uzyskać więcej informacji, zobacz Konfigurowanie dostępu.

• Python 3.8 lub nowszy.

• Visual Studio Code z rozszerzeniami Python i Jupyter.

• Azure CLI na potrzeby uwierzytelniania bez klucza za pomocą Microsoft Entra ID.

Omówienie rozwiązania

To rozwiązanie łączy Wyszukiwanie AI platformy Azure i Microsoft Foundry, aby stworzyć kompletny ciąg pobierania danych.

• Wyszukiwanie AI platformy Azure hostuje bazę wiedzy, która obsługuje planowanie zapytań, wykonywanie zapytań i syntezę wyników. Utworzysz indeks wyszukiwania do przechowywania zawartości, źródła wiedzy odwołującego się do indeksu i bazy wiedzy, która wykonuje pobieranie hybrydowe ze źródła wiedzy.

• Microsoft Foundry hostuje wdrożenia modelu Azure OpenAI, połączenie projektu i agenta. Utworzysz połączenie projektu wskazujące punkt końcowy MCP bazy wiedzy, a następnie utworzysz agenta korzystającego z narzędzia MCP w celu uzyskania dostępu do bazy wiedzy.

Użytkownik inicjuje przetwarzanie zapytań przez interakcję z aplikacją kliencką, taką jak czatbot, który wywołuje agenta. Agent używa narzędzia MCP do organizowania żądań do bazy wiedzy i syntetyzowania odpowiedzi. Gdy czatbot wywołuje agenta, narzędzie MCP wywołuje bazę wiedzy w Wyszukiwanie AI platformy Azure i wysyła odpowiedź do agenta i czatbota.

Konfigurowanie dostępu

Przed rozpoczęciem upewnij się, że masz uprawnienia dostępu do zawartości i operacji. Zalecamy Microsoft Entra ID na potrzeby uwierzytelniania i dostępu opartego na rolach na potrzeby autoryzacji. Aby przypisać role, musisz być właścicielem lub administratorem dostępu użytkowników . Jeśli role nie są możliwe, zamiast tego użyj uwierzytelniania opartego na kluczach .

Aby skonfigurować dostęp dla tego rozwiązania:

1. Zaloguj się do portalu Azure.

2. Włącz tożsamość zarządzaną przypisaną przez system zarówno dla usługi wyszukiwania, jak i projektu. Można to zrobić na stronie Tożsamość każdego zasobu.

3. W usłudze wyszukiwania włącz dostęp oparty na rolach i przypisz następujące role.

   Roli	Cesjonariusz	Cel
   Współautor usługi wyszukiwania	Konto użytkownika	Tworzenie obiektów
   Współautor danych indeksu wyszukiwania	Konto użytkownika	Ładowanie danych
   Czytnik danych indeksu wyszukiwania	Konto użytkownika i tożsamość zarządzana projektu	Odczytywanie indeksowanej zawartości

4. W zasobie nadrzędnym projektu przypisz następujące role.

   Roli	Cesjonariusz	Cel
   Użytkownik platformy Foundry	Konto użytkownika	Uzyskiwanie dostępu do wdrożeń modelu i tworzenie agentów
   Menedżer projektu Foundry	Konto użytkownika	Tworzenie połączenia projektu i używanie narzędzia MCP w agentach
   Użytkownik usług Cognitive Services	Tożsamość zarządzana usługi wyszukiwania	Uzyskiwanie dostępu do bazy wiedzy

Konfigurowanie środowiska

1. Utwórz folder o nazwie tutorial-agentic-retrieval w systemie lokalnym.

2. Otwórz folder w Visual Studio Code.

3. Wybierz View>Paleta poleceń, a następnie wybierz Python: Utwórz środowisko. Postępuj zgodnie z monitami, aby utworzyć środowisko wirtualne.

4. Wybierz pozycję Terminal>New Terminal (Nowy terminal).

5. Zainstaluj wymagane pakiety.

   pip install azure-ai-projects==2.0.0b1 azure-mgmt-cognitiveservices azure-identity ipykernel python-dotenv azure-search-documents==11.7.0b2 requests openai
   

6. Utwórz plik o nazwie .env w folderze tutorial-agentic-retrieval .

7. Dodaj następujące zmienne do .env pliku, zastępując wartości symboli zastępczych własnymi.

   AZURE_SEARCH_ENDPOINT = https://{your-service-name}.search.windows.net
   PROJECT_ENDPOINT = https://{your-resource-name}.services.ai.azure.com/api/projects/{your-project-name}
   PROJECT_RESOURCE_ID = /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.CognitiveServices/accounts/{account-name}/projects/{project-name}
   AZURE_OPENAI_ENDPOINT = https://{your-resource-name}.openai.azure.com
   AZURE_OPENAI_EMBEDDING_DEPLOYMENT = text-embedding-3-large
    AGENT_MODEL = gpt-5-mini
   

   Punkty końcowe i identyfikator zasobu można znaleźć w portalu Azure:

   • AZURE_SEARCH_ENDPOINT znajduje się na stronie Przegląd usługi wyszukiwania.

   • PROJECT_ENDPOINT znajduje się na stronie Punkty końcowe projektu.

   • PROJECT_RESOURCE_ID znajduje się na stronie Właściwości projektu.

   • AZURE_OPENAI_ENDPOINT znajduje się na stronie Punkty końcowe zasobu nadrzędnego projektu.

8. W przypadku uwierzytelniania bez klucza przy użyciu Microsoft Entra ID zaloguj się do konta Azure. Jeśli masz wiele subskrypcji, wybierz tę, która zawiera zasoby Wyszukiwanie AI platformy Azure i Microsoft Foundry.

   az login
   

9. Utwórz plik o nazwie tutorial.ipynb w folderze tutorial-agentic-retrieval . Komórki kodu można dodać do tego pliku w następnej sekcji.

Tworzenie rozwiązania

W tej sekcji utworzysz składniki rozwiązania agentowego pobierania. Dodaj każdy fragment kodu do oddzielnej komórki kodu w notesie tutorial.ipynb i sekwencyjnie uruchom komórki.

Kroki opisane w tej sekcji obejmują:

1. Ładowanie połączeń
2. Tworzenie indeksu wyszukiwania
3. Przekazywanie dokumentów do indeksu
4. Tworzenie źródła wiedzy
5. Tworzenie bazy wiedzy
6. Konfigurowanie klienta projektu
7. Utwórz połączenie projektu
8. Tworzenie agenta za pomocą narzędzia MCP
9. Rozmowa z agentem
10. Czyszczenie zasobów

Wczytywanie połączeń

Poniższy kod ładuje zmienne środowiskowe z pliku .env i ustanawia połączenia z Wyszukiwanie AI platformy Azure i Microsoft Foundry.

import os

from azure.identity import DefaultAzureCredential
from azure.mgmt.core.tools import parse_resource_id
from dotenv import load_dotenv

load_dotenv(override=True) # Take environment variables from .env

project_endpoint = os.environ["PROJECT_ENDPOINT"]
project_resource_id = os.environ["PROJECT_RESOURCE_ID"]
project_connection_name = os.getenv("PROJECT_CONNECTION_NAME", "earthknowledgeconnection")
agent_model = os.getenv("AGENT_MODEL", "gpt-5-mini")
agent_name = os.getenv("AGENT_NAME", "earth-knowledge-agent")
endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
knowledge_source_name = os.getenv("AZURE_SEARCH_KNOWLEDGE_SOURCE_NAME", "earth-knowledge-source")
index_name = os.getenv("AZURE_SEARCH_INDEX", "earth-at-night")
azure_openai_endpoint = os.environ["AZURE_OPENAI_ENDPOINT"]
azure_openai_embedding_deployment = os.getenv("AZURE_OPENAI_EMBEDDING_DEPLOYMENT", "text-embedding-3-large")
azure_openai_embedding_model = os.getenv("AZURE_OPENAI_EMBEDDING_MODEL", "text-embedding-3-large")
base_name = os.getenv("AZURE_SEARCH_AGENT_NAME", "earth-knowledge-base")

# Parse the resource ID to extract subscription and other components
parsed_resource_id = parse_resource_id(project_resource_id)
subscription_id = parsed_resource_id['subscription']
resource_group = parsed_resource_id['resource_group']
account_name = parsed_resource_id['name']
project_name = parsed_resource_id['child_name_1']

Tworzenie indeksu wyszukiwania

W Wyszukiwanie AI platformy Azure indeks jest ustrukturyzowaną kolekcją danych. Poniższy kod tworzy indeks do przechowywania zawartości z możliwością wyszukiwania dla bazy wiedzy.

Schemat indeksu zawiera pola identyfikacji dokumentu i zawartości strony, osadzania i liczb. Schemat zawiera również konfiguracje semantycznego klasyfikowania i wyszukiwania wektorów, które używają text-embedding-3-large wdrożenia do wektoryzacji tekstu i dopasowywania dokumentów na podstawie podobieństwa semantycznego.

Aby uzyskać więcej informacji na temat tego kroku, zobacz Utwórz indeks pobierania agenta w Wyszukiwanie AI platformy Azure.

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    AzureOpenAIVectorizer, AzureOpenAIVectorizerParameters,
    HnswAlgorithmConfiguration, SearchField, SearchIndex,
    SemanticConfiguration, SemanticField, SemanticPrioritizedFields,
    SemanticSearch, VectorSearch, VectorSearchProfile
)

index = SearchIndex(
    name=index_name,
    fields=[
        SearchField(name="id", type="Edm.String", key=True, filterable=True, sortable=True, facetable=True),
        SearchField(name="page_chunk", type="Edm.String", filterable=False, sortable=False, facetable=False),
        SearchField(name="page_embedding_text_3_large", type="Collection(Edm.Single)", stored=False, vector_search_dimensions=3072, vector_search_profile_name="hnsw_text_3_large"),
        SearchField(name="page_number", type="Edm.Int32", filterable=True, sortable=True, facetable=True)
    ],
    vector_search=VectorSearch(
        profiles=[VectorSearchProfile(name="hnsw_text_3_large", algorithm_configuration_name="alg", vectorizer_name="azure_openai_text_3_large")],
        algorithms=[HnswAlgorithmConfiguration(name="alg")],
        vectorizers=[
            AzureOpenAIVectorizer(
                vectorizer_name="azure_openai_text_3_large",
                parameters=AzureOpenAIVectorizerParameters(
                    resource_url=azure_openai_endpoint,
                    deployment_name=azure_openai_embedding_deployment,
                    model_name=azure_openai_embedding_model
                )
            )
        ]
    ),
    semantic_search=SemanticSearch(
        default_configuration_name="semantic_config",
        configurations=[
            SemanticConfiguration(
                name="semantic_config",
                prioritized_fields=SemanticPrioritizedFields(
                    content_fields=[
                        SemanticField(field_name="page_chunk")
                    ]
                )
            )
        ]
    )
)

index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
index_client.create_or_update_index(index)
print(f"Index '{index_name}' created or updated successfully")

Przesyłanie dokumentów do indeksu

Obecnie indeks jest pusty. Poniższy kod wypełnia indeks dokumentami JSON z NASA's Earth at Night e-book. Zgodnie z wymaganiami Wyszukiwanie AI platformy Azure każdy dokument jest zgodny z polami i typami danych zdefiniowanymi w schemacie indeksu.

Aby uzyskać więcej informacji na temat tego kroku, zobacz Wypychanie danych do indeksu.

import requests
from azure.search.documents import SearchIndexingBufferedSender

url = "https://raw.githubusercontent.com/Azure-Samples/azure-search-sample-data/refs/heads/main/nasa-e-book/earth-at-night-json/documents.json"
documents = requests.get(url).json()

with SearchIndexingBufferedSender(endpoint=endpoint, index_name=index_name, credential=credential) as client:
    client.upload_documents(documents=documents)

print(f"Documents uploaded to index '{index_name}'")

Tworzenie źródła wiedzy

Źródło wiedzy to odwołanie wielokrotnego użytku do danych źródłowych. Poniższy kod tworzy źródło wiedzy, które jest przeznaczone dla utworzonego wcześniej indeksu.

source_data_fields określa, które pola indeksu są uwzględniane w odwołaniach do cytatów. W tym przykładzie uwzględniono tylko pola czytelne dla człowieka, aby uniknąć długich, niezinterpretowanych osadzeń w odpowiedziach.

Aby uzyskać więcej informacji na temat tego kroku, zobacz Tworzenie źródła wiedzy indeksu wyszukiwania.

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    SearchIndexFieldReference, SearchIndexKnowledgeSource,
    SearchIndexKnowledgeSourceParameters
)

ks = SearchIndexKnowledgeSource(
    name=knowledge_source_name,
    description="Knowledge source for Earth at night data",
    search_index_parameters=SearchIndexKnowledgeSourceParameters(
        search_index_name=index_name,
        semantic_configuration_name="semantic_config",
        source_data_fields=[
            SearchIndexFieldReference(name="id"),
            SearchIndexFieldReference(name="page_chunk"),
            SearchIndexFieldReference(name="page_number")
        ]
    ),
)

index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
index_client.create_or_update_knowledge_source(knowledge_source=ks)
print(f"Knowledge source '{knowledge_source_name}' created or updated successfully.")

Tworzenie bazy wiedzy

Poniższy kod tworzy bazę wiedzy, która koordynuje agenticzne pobieranie ze źródła wiedzy. Kod przechowuje również punkt końcowy MCP bazy wiedzy, która będzie używana przez agenta do uzyskiwania dostępu do bazy wiedzy.

W przypadku integracji z usługą agenta usługi Foundry baza wiedzy jest skonfigurowana przy użyciu następujących parametrów:

• output_mode (wersja zapoznawcza) jest ustawione na dane ekstrakcyjne, które udostępniają agentowi dosłowną, nieprzetworzoną zawartość na potrzeby osadzania i wnioskowania. Tryb alternatywny, synteza odpowiedzi, zwraca wstępnie wygenerowane odpowiedzi, które ograniczają zdolność agenta do rozumowania nad zawartością źródłową.

• retrieval_reasoning_effort (wersja zapoznawcza) ma ustawiony minimalny nakład pracy, co pomija planowanie zapytań oparte na modelach LLM, aby zmniejszyć koszty i opóźnienia. Z innych powodów baza wiedzy używa programu LLM do ponownego formatowania zapytań użytkowników przed pobraniem.

Aby uzyskać więcej informacji na temat tego kroku, zobacz Utwórz bazę wiedzy w Wyszukiwanie AI platformy Azure.

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import KnowledgeBase, KnowledgeSourceReference
from azure.search.documents.knowledgebases.models import KnowledgeRetrievalMinimalReasoningEffort

knowledge_base = KnowledgeBase(
    name=base_name,
    knowledge_sources=[
        KnowledgeSourceReference(
            name=knowledge_source_name
        )
    ],
    output_mode="extractiveData",
    retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort()
)


index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
index_client.create_or_update_knowledge_base(knowledge_base=knowledge_base)
print(f"Knowledge base '{base_name}' created or updated successfully")

mcp_endpoint = f"{endpoint.rstrip('/')}/knowledgebases/{base_name}/mcp?api-version=2026-08-01-preview"

Konfigurowanie klienta projektu

Użyj AIProjectClient aby utworzyć połączenie klienta z projektem Microsoft Foundry. Twój projekt może jeszcze nie zawierać żadnych agentów, ale jeśli ukończono już ten samouczek, agent jest tutaj wyświetlany.

from azure.ai.projects import AIProjectClient

project_client = AIProjectClient(endpoint=project_endpoint, credential=credential)

list(project_client.agents.list())

Utwórz połączenie projektu

Poniższy kod tworzy w Microsoft Foundry połączenie projektu RemoteTool (wersja zapoznawcza), które wskazuje na punkt końcowy MCP Twojej bazy wiedzy. To połączenie używa tożsamości zarządzanej projektu do uwierzytelniania w Wyszukiwanie AI platformy Azure.

import requests
from azure.identity import get_bearer_token_provider

bearer_token_provider = get_bearer_token_provider(credential, "https://management.azure.com/.default")
headers = {
    "Authorization": f"Bearer {bearer_token_provider()}",
}

response = requests.put(
    f"https://management.azure.com{project_resource_id}/connections/{project_connection_name}?api-version=2025-10-01-preview",
    headers=headers,
    json={
        "name": project_connection_name,
        "type": "Microsoft.MachineLearningServices/workspaces/connections",
        "properties": {
            "authType": "ProjectManagedIdentity",
            "category": "RemoteTool",
            "target": mcp_endpoint,
            "isSharedToAll": True,
            "audience": "https://search.azure.com/",
            "metadata": { "ApiType": "Azure" }
        }
    }
)

response.raise_for_status()
print(f"Connection '{project_connection_name}' created or updated successfully.")

Tworzenie agenta za pomocą narzędzia MCP

Poniższy kod tworzy agenta skonfigurowanego za pomocą narzędzia MCP. Gdy agent odbierze zapytanie użytkownika, może wywołać bazę wiedzy za pomocą narzędzia MCP, aby pobrać odpowiednią zawartość na potrzeby uziemienia odpowiedzi.

Definicja agenta zawiera instrukcje określające jego zachowanie i utworzone wcześniej połączenie projektu. Na podstawie naszych eksperymentów te instrukcje są skuteczne w maksymalizacji dokładności wywołań bazy wiedzy i zapewniania odpowiedniego formatowania cytatów.

Aby uzyskać więcej informacji na temat tego kroku, zobacz Szybki start: tworzenie nowego agenta.

from azure.ai.projects.models import PromptAgentDefinition, MCPTool

instructions = """
You are a helpful assistant that must use the knowledge base to answer all the questions from user. You must never answer from your own knowledge under any circumstances.
Every answer must always provide annotations for using the MCP knowledge base tool and render them as: `【message_idx:search_idx†source_name】`
If you cannot find the answer in the provided knowledge base you must respond with "I don't know".
"""

mcp_kb_tool = MCPTool(
    server_label="knowledge-base",
    server_url=mcp_endpoint,
    require_approval="never",
    allowed_tools=["knowledge_base_retrieve"],
    project_connection_id=project_connection_name
)

agent = project_client.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(
        model=agent_model,
        instructions=instructions,
        tools=[mcp_kb_tool]
    )
)

print(f"AI agent '{agent_name}' created or updated successfully")

(Opcjonalnie) Wymuszanie uprawnień przy użyciu nagłówków poszczególnych żądań

Jeśli którekolwiek ze źródeł wiedzy zawiera zawartość chronioną uprawnieniami, aparat pobierania może filtrować wyniki, aby każdy użytkownik widział tylko dokumenty, do których ma dostęp. Aby włączyć to filtrowanie, przekaż token tożsamości zalogowanego użytkownika w nagłówku x-ms-query-source-authorization połączenia narzędzia MCP. Bez tego tokenu źródła z włączoną kontrolą uprawnień zwracają nieprzefiltrowane wyniki. Aby uzyskać więcej informacji, zobacz Wymuszanie uprawnień w czasie zapytania (wersja zapoznawcza).

Aby zmieniać nagłówki MCP dla każdego żądania, na przykład przekazując przy każdym wywołaniu token innego użytkownika, zadeklaruj ustrukturyzowane dane wejściowe w definicji agenta i odwołaj się do nich jako {{placeholder}} w elemencie headers narzędzia. Wywołujący dostarcza wartość przy każdym wywołaniu. Takie podejście działa w przypadku narzędzi MCP powiązanych z połączeniem projektu.

W przypadku autoryzacji dla poszczególnych użytkowników na serwerze MCP można również użyć przekazywania tożsamości OAuth.

Poniższy kod aktualizuje agenta z poprzedniego kroku, aby narzędzie MCP odczytywało nagłówek autoryzacji ze ustrukturyzowanych danych wejściowych.

from azure.ai.projects.models import StructuredInputDefinition

# Reference the token as a placeholder in the header
mcp_kb_tool = MCPTool(
    server_label="knowledge-base",
    server_url=mcp_endpoint,
    require_approval="never",
    allowed_tools=["knowledge_base_retrieve"],
    project_connection_id=project_connection_name,
    headers={
        "x-ms-query-source-authorization": "{{search_auth_token}}"
    }
)

# Declare the structured input so the caller can supply the token per request
agent = project_client.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(
        model=agent_model,
        instructions=instructions,
        tools=[mcp_kb_tool],
        structured_inputs={
            "search_auth_token": StructuredInputDefinition(
                description="Per-user Azure AI Search bearer token",
                required=True,
                schema={"type": "string"},
            )
        }
    )
)

print(f"AI agent '{agent_name}' created or updated successfully")

Podczas wywoływania agenta podaj token Wyszukiwanie AI platformy Azure w pliku structured_inputs. W tym przykładzie ustalany jest token z bieżącego credential. W przypadku aplikacji z wieloma użytkownikami należy przekazać token każdego zalogowanego użytkownika. Na przykład użyj tokenu uzyskanego za pomocą przepływu On-Behalf-Of, aby moduł wyszukiwania mógł filtrować wyniki dla tego użytkownika.

# Resolve an Azure AI Search token from the current credential (use a per-user token in production)
from azure.identity import get_bearer_token_provider

search_token = get_bearer_token_provider(credential, "https://search.azure.com/.default")()

openai_client = project_client.get_openai_client()
conversation = openai_client.conversations.create()

response = openai_client.responses.create(
    conversation=conversation.id,
    tool_choice="required",
    input="{user_query}",
    extra_body={
        "agent_reference": {"name": agent.name, "type": "agent_reference"},
        "structured_inputs": {"search_auth_token": search_token},
    },
)

print(f"Response: {response.output_text}")

Rozmowa z agentem

Aplikacja kliencka używa interfejsów API Konwersacje i Responses z Azure OpenAI do interakcji z agentem.

Poniższy kod tworzy konwersację i przekazuje komunikaty użytkowników do agenta, przypominające typowe środowisko czatu. Agent określa, kiedy wywołać bazę wiedzy za pomocą narzędzia MCP i zwraca odpowiedź w języku naturalnym z odwołaniami. Ustawienie tool_choice="required" zapewnia, że agent zawsze używa narzędzia bazy wiedzy podczas przetwarzania zapytań.

# Get the OpenAI client for responses and conversations
openai_client = project_client.get_openai_client()

conversation = openai_client.conversations.create()

# Send initial request that will trigger the MCP tool
response = openai_client.responses.create(
    conversation=conversation.id,
    tool_choice="required",
    input="""
        Why do suburban belts display larger December brightening than urban cores even though absolute light levels are higher downtown?
        Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?
    """,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response: {response.output_text}")

Odpowiedź powinna być podobna do poniższego przykładu.

Response: Here are evidence-based explanations to your questions:

---

**1. Why do suburban belts display larger December brightening than urban cores, even though absolute light levels are higher downtown?**

- Suburban belts show a *larger percentage increase* in night brightness during December compared to urban cores, largely because suburban residential areas feature more single-family homes and larger yards, which are typically decorated with holiday lights. These areas start from a lower baseline (less bright overall at night compared to dense urban centers), so the relative change (brightening) is much more noticeable.

- In contrast, the downtown core is already very bright at night due to dense commercial lighting and streetlights. While it also sees a December increase (often 20–30% brighter), the *absolute* change is less striking because it begins at a much higher base of illumination.

- This pattern is observed across U.S. cities, with the phenomenon driven by widespread cultural practices and the suburban landscape’s suitability for holiday lighting displays. The effect is visible in satellite data and was quantified at 20–50% brighter in December, especially in suburbs and city outskirts.

---

**2. Why is the Phoenix nighttime street grid so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?**

- Phoenix’s sharply visible nighttime street grid from space is a result of its urban layout: the city (like many western U.S. cities) was developed using a regular grid system, with extensive and uniform street lighting and strong urban sprawl. The grid pattern, and the dense network of intersecting surface streets, is brightly illuminated, particularly at intersections, commercial areas, and major thoroughfares.

- The interstate highways between midwestern cities, though significant in length and crucial to national infrastructure, traverse sparsely populated rural areas. These stretches typically have very little artificial lighting (due to low traffic volumes at night and cost considerations), making them much less visible in nighttime satellite imagery. Only nodes (cities and towns) along the route show as bright "pearls" in the darkness, while the "strings" (highways) connecting them remain faint or invisible.

- In summary:
  - Urban areas like Phoenix stand out with strong, connected patterns of light due to dense development and extensive lighting.
  - Rural interstates are sparsely lit, and only their endpoints—cities and large towns—generate notable light visible from space.

---

**References**:
- [Holiday Lights increase most dramatically in suburbs, not downtowns: earth_at_night_508_page_176_verbalized, page 160](4:5)
- [Lighting paths and urban grids are visible from space, while rural highways remain dim: earth_at_night_508_page_124_verbalized, page 108](4:3)
- [Phoenix’s grid and surrounding urban structure: earth_at_night_508_page_104_verbalized, page 88](4:1)

Sprawdzanie odpowiedzi

Podstawowa odpowiedź agenta zawiera metadane dotyczące zapytań wysyłanych do bazy wiedzy i znalezionych cytatów. Możesz sprawdzić te metadane, aby zrozumieć, jak agent przetworzył dane wejściowe użytkownika.

response.to_dict()

Czyszczenie zasobów

Jeśli pracujesz we własnej subskrypcji, dobrym pomysłem jest zakończenie projektu przez usunięcie zasobów, których już nie potrzebujesz. Zasoby, które pozostają uruchomione, mogą generować koszty.

W portalu Azure wybierz pozycję Wszystkie zasoby lub Grupy zasobów w okienku po lewej stronie, aby znaleźć zasoby i zarządzać nimi. Zasoby można usunąć pojedynczo lub usunąć grupę zasobów, aby jednocześnie usunąć wszystkie zasoby.

Możesz również uruchomić następujący kod, aby usunąć poszczególne obiekty:

# Delete the agent
project_client.agents.delete_version(agent.name, agent.version)
print(f"AI agent '{agent.name}' version '{agent.version}' deleted successfully")

# Delete the knowledge base
index_client.delete_knowledge_base(base_name)
print(f"Knowledge base '{base_name}' deleted successfully")

# Delete the knowledge source
index_client.delete_knowledge_source(knowledge_source=knowledge_source_name)
print(f"Knowledge source '{knowledge_source_name}' deleted successfully.")

# Delete the search index
index_client.delete_index(index_name)
print(f"Index '{index_name}' deleted successfully")

Poprawianie jakości danych

Domyślnie wyniki wyszukiwania z baz wiedzy są łączone w jeden duży, spójny ciąg, który można przekazać agentom w celu ugruntowania. Wyszukiwanie AI platformy Azure udostępnia następujące funkcje indeksowania i dostrajania istotności, które ułatwiają generowanie wyników wysokiej jakości. Te funkcje można zaimplementować w indeksie wyszukiwania, a ulepszenia trafności wyszukiwania są widoczne w jakości wyników wyszukiwania.

• Profile oceny zapewniają wbudowane kryteria wzmacniania. Indeks musi określać domyślny profil oceniania, który jest używany przez aparat pobierania, gdy zapytania zawierają pola skojarzone z tym profilem.

• Wymagana jest konfiguracja semantyczna, ale określasz, które pola są priorytetowe i używane do klasyfikowania.

• W przypadku zawartości zwykłego tekstu można użyć analizatorów do kontrolowania tokenizacji podczas indeksowania.

• W przypadku zawartości wielomodalnej lub obrazowej można użyć werbalizacji obrazów na potrzeby generowanych przez LLM opisów obrazów lub klasycznego OCR i analizy obrazów za pośrednictwem zestawów umiejętności podczas indeksowania.

Kontrolowanie liczby podzapytań

W bazie wiedzy można kontrolować liczbę podzapytań, ustawiając wysiłek wnioskowania podczas pobierania (wersja zapoznawcza). Wysiłek rozumowania określa poziom przetwarzania LLM na potrzeby planowania zapytań, od minimalnego (bez przetwarzania LLM) do średniego (dokładniejsze wyszukiwanie i kolejne iteracje).

W przypadku wysiłków rozumowania nie-minimalnego LLM określa liczbę podzapytań na podstawie następujących czynników.

• Zapytanie użytkownika
• Historia czatów
• Ograniczenia danych wejściowych klasyfikatora semantycznego

Kontroluj kontekst wysyłany do agenta

Interfejs API odpowiedzi steruje tym, co jest wysyłane do agenta i bazy wiedzy. Aby zoptymalizować wydajność i istotność, dostosuj instrukcje agenta, aby podsumować lub przefiltrować historię czatów przed wysłaniem ich do narzędzia MCP.

Kontrolowanie kosztów i ograniczanie operacji

Aby uzyskać wgląd w plan zapytania, zapoznaj się z tokenami wyjściowymi w tablicy działań odpowiedzi bazy wiedzy.

Zwiększanie wydajności

Aby zoptymalizować wydajność i zmniejszyć opóźnienie, należy wziąć pod uwagę następujące strategie:

• Podsumowywanie wątków komunikatów.

• Użyj gpt-5-mini lub mniejszego modelu, który działa szybciej.

• Ustaw maxOutputSizeakcję pobierania , aby zarządzać rozmiarem odpowiedzi lub maxRuntimeInSeconds przetwarzaniem powiązanym czasowo.

• Podziel duże dokumenty na mniejsze elementy przed indeksowaniem. Dokumenty, które przekraczają budżet wyjściowy, mogą zostać cicho pominięte w ugruntowanych wynikach.

Powiązana zawartość

• Pobieranie przy użyciu agentów w Wyszukiwanie AI platformy Azure
• Agentic RAG: Tworzenie silnika pobierania rozumowania za pomocą Wyszukiwanie AI platformy Azure (wideo z YouTube)
• Demonstracja Azure OpenAI z funkcją agentowego pobierania