Lernprogramm: Erstellen einer End-to-End-Agent-Abruflösung mithilfe von Azure KI-Suche

Erfahren Sie, wie Sie eine intelligente, MCP-fähige Lösung erstellen, die Azure KI-Suche in den Foundry Agent Service für agentic retrieval integriert. Sie können diese Architektur für Konversationsanwendungen verwenden, die komplexe Überlegungen in großen Wissensbereichen erfordern, z. B. Kundensupport oder technische Problembehandlung.

In diesem Tutorial:

Voraussetzungen

• Ein Azure KI-Suche Dienst in einer beliebigen Region, der agentenbasierte Abrufe bereitstellt.

• Ein Microsoft Foundry-Projekt und eine Ressource. Wenn Sie ein Projekt erstellen, wird die Ressource automatisch erstellt.

• Ein in Ihr Projekt bereitgestelltes Texteinbettungsmodell für die Abfragezeitvektorisierung. Diese Lösung verwendet text-embedding-3-large.

• Ein LLM wird für den Software-Agent Ihres Projekts bereitgestellt. Diese Lösung verwendet gpt-5-mini.

  GPT-4-Familienmodelle sind veraltet. Informationen zu den Stilllegungsdaten und dem aktuellen Status in Microsoft Foundry finden Sie unter Zeitplan für die Stilllegung von Modellen – Microsoft Foundry.

• Berechtigung für den Zugriff auf und die Verwaltung von Azure KI-Suche- und Microsoft Foundry-Ressourcen. Weitere Informationen finden Sie unter Konfigurieren des Zugriffs.

• Python 3.8 oder höher.

• Visual Studio Code mit den Erweiterungen Python und Jupyter.

• Die Azure CLI für die schlüssellose Authentifizierung mit Microsoft Entra ID.

Verständnis der Lösung

Diese Lösung kombiniert Azure KI-Suche und Microsoft Foundry, um eine End-to-End-Abrufpipeline zu erstellen:

• Azure KI-Suche hostet Ihre Wissensbasis, die die Abfrageplanung, Abfrageausführung und Ergebnissynthese verarbeitet. Sie erstellen einen Suchindex zum Speichern von Inhalten, einer Wissensquelle, die auf den Index verweist, und einer Wissensbasis, die einen Hybridabruf aus der Wissensquelle durchführt.

• Microsoft Foundry hostet Ihre Azure OpenAI-Modellbereitstellungen, Projektverbindung und Agent. Sie erstellen eine Projektverbindung, die auf den MCP-Endpunkt Ihrer Wissensbasis verweist, und dann einen Agent erstellen, der das MCP-Tool verwendet, um auf die Wissensbasis zuzugreifen.

Ein Benutzer initiiert die Abfrageverarbeitung, indem er mit einer Client-App interagiert, z. B. mit einem Chatbot, der den Agent aufruft. Der Agent verwendet das MCP-Tool, um Anforderungen an die Wissensbasis zu koordinieren und Antworten zu synthetisieren. Wenn der Chatbot den Agent aufruft, ruft das MCP-Tool die Wissensbasis in Azure KI-Suche auf und sendet die Antwort an den Agenten und Chatbot.

Konfigurieren des Zugriffs

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Berechtigungen für den Zugriff auf Inhalte und Vorgänge verfügen. Wir empfehlen Microsoft Entra ID für die Authentifizierung und den rollenbasierten Zugriff für die Autorisierung. Sie müssen ein Besitzer oder Benutzerzugriffsadministrator sein, um Rollen zuzuweisen. Wenn Rollen nicht machbar sind, verwenden Sie stattdessen die schlüsselbasierte Authentifizierung .

So konfigurieren Sie den Zugriff für diese Lösung:

1. Melden Sie sich beim portal Azure an.

2. Aktivieren Sie eine vom System zugewiesene verwaltete Identität sowohl für Ihren Suchdienst als auch für Ihr Projekt. Sie können dies auf der Seite "Identität" jeder Ressource tun.

3. Aktivieren Sie im Suchdienst den rollenbasierten Zugriff , und weisen Sie die folgenden Rollen zu.

   Rolle	Zugewiesene Person	Zweck
   Suchdienstmitwirkender	Ihr Benutzerkonto	Erstellen von Objekten
   Suchindexdatenmitwirkender	Ihr Benutzerkonto	Laden von Daten
   Suchindexdatenleser	Ihr Benutzerkonto und die vom Projekt verwaltete Identität	Indizierte Inhalte lesen

4. Weisen Sie der übergeordneten Ressource Ihres Projekts die folgenden Rollen zu.

   Rolle	Zugewiesene Person	Zweck
   Foundry-Benutzer	Ihr Benutzerkonto	Zugriff auf Modellbereitstellungen und Agents erstellen
   Foundry-Projektmanager	Ihr Benutzerkonto	Erstellen einer Projektverbindung und Verwenden des MCP-Tools in Agents
   Cognitive Services-Benutzer	Verwaltete Identität des Suchdiensts	Zugriff auf Wissensdatenbank

Einrichten Ihrer Umgebung

1. Erstellen Sie einen Ordner namens tutorial-agentic-retrieval auf Ihrem lokalen System.

2. Öffnen Sie den Ordner in Visual Studio Code.

3. Wählen Sie View>Command Palette und dann Python: Create Environment aus. Folgen Sie den Anweisungen, um eine virtuelle Umgebung zu erstellen.

4. Wählen Sie Terminal>Neues Terminal aus.

5. Installieren Sie die erforderlichen Pakete.

   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. Erstellen Sie eine Datei namens .env im Ordner tutorial-agentic-retrieval.

7. Fügen Sie der .env Datei die folgenden Variablen hinzu, und ersetzen Sie die Platzhalterwerte durch Eigene.

   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
   

   Sie finden die Endpunkte und Ressourcen-ID im Azure Portal:

   • AZURE_SEARCH_ENDPOINT befindet sich auf der Seite "Übersicht" Ihres Suchdiensts.

   • PROJECT_ENDPOINT befindet sich auf der Seite "Endpunkte" Ihres Projekts.

   • PROJECT_RESOURCE_ID befindet sich auf der Seite "Eigenschaften" ihres Projekts.

   • AZURE_OPENAI_ENDPOINT befindet sich auf der Seite "Endpunkte" der übergeordneten Ressource Ihres Projekts.

8. Melden Sie sich für die schlüssellose Authentifizierung mit Microsoft Entra ID bei Ihrem Azure-Konto an. Wenn Sie über mehrere Abonnements verfügen, wählen Sie das Abonnement aus, das Ihre Azure KI-Suche und Microsoft Foundry-Ressourcen enthält.

   az login
   

9. Erstellen Sie eine Datei namens tutorial.ipynb im Ordner tutorial-agentic-retrieval. Sie fügen dieser Datei im nächsten Abschnitt Codezellen hinzu.

Erstellen der Lösung

In diesem Abschnitt erstellen Sie die Komponenten der agentischen Abruflösung. Fügen Sie jeden Codeausschnitt zu einer separaten Codezelle im tutorial.ipynb Notizbuch hinzu, und führen Sie die Zellen sequenziell aus.

Die Schritte in diesem Abschnitt umfassen:

1. Verbindungen laden
2. Erstellen eines Suchindexes
3. Hochladen von Dokumenten in den Index
4. Erstellen einer Wissensquelle
5. Erstellen einer Wissensbasis
6. Einrichten eines Projektclients
7. Erstellen einer Projektverbindung
8. Erstellen eines Agents mit dem MCP-Tool
9. Chatten mit dem Agent
10. Ressourcen bereinigen

Verbindungen laden

Der folgende Code lädt die Umgebungsvariablen aus der Datei .env und stellt Verbindungen zu Azure KI-Suche und Microsoft Foundry her.

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

Erstellen eines Suchindexes

In Azure KI-Suche ist ein Index eine strukturierte Sammlung von Daten. Der folgende Code erstellt einen Index zum Speichern durchsuchbarer Inhalte für Ihre Wissensbasis.

Das Indexschema enthält Felder für Dokumentidentifikation und Seiteninhalte, Einbettungen und Zahlen. Das Schema enthält auch Konfigurationen für die semantische Rangfolge und die Vektorsuche, die Ihre text-embedding-3-large Bereitstellung verwendet, um Text zu vektorisieren und Dokumente basierend auf semantischer Ähnlichkeit abzugleichen.

Weitere Informationen zu diesem Schritt finden Sie unter Erstellen Sie einen Index für die agentengestützte Suche in Azure KI-Suche.

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

Hochladen von Dokumenten in den Index

Derzeit ist der Index leer. Der folgende Code füllt den Index mit JSON-Dokumenten aus NASA es Earth at Night e-book auf. Je nach Azure KI-Suche entspricht jedes Dokument den im Indexschema definierten Feldern und Datentypen.

Weitere Informationen zu diesem Schritt finden Sie unter Pushing data to an index.

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

Erstellen einer Wissensquelle

Eine Wissensquelle ist ein wiederverwendbarer Verweis auf Quelldaten. Der folgende Code erstellt eine Wissensquelle, die auf den zuvor erstellten Index ausgerichtet ist.

source_data_fields Gibt an, welche Indexfelder in Zitatverweise enthalten sind. Dieses Beispiel enthält nur lesbare Felder, um langwierige, uninterpretierbare Einbettungen in Antworten zu vermeiden.

Weitere Informationen zu diesem Schritt finden Sie unter Erstellen einer Suchindex-Wissensquelle.

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

Erstellen einer Wissensbasis

Der folgende Code erstellt eine Wissensbasis, die den agentischen Abruf aus Ihrer Wissensquelle koordiniert. Der Code speichert auch den MCP-Endpunkt der Knowledge Base, den Ihr Agent für den Zugriff auf die Knowledge Base verwendet.

Für die Integration mit dem Foundry Agent Service wird die Knowledge Base mit den folgenden Parametern konfiguriert:

• output_mode ist auf extraktive Daten festgelegt, die dem Agent unverarbeitete Inhalte als Grundlage für seine Schlussfolgerungen liefern. Der alternative Modus, Antwortsynthese, gibt vorab generierte Antworten zurück, die die Fähigkeit des Agents einschränken, über Quellinhalte zu gründen.

• retrieval_reasoning_effort ist auf minimalen Aufwand festgelegt, wodurch die LLM-basierte Abfrageplanung umgangen wird, um Kosten und Latenz zu reduzieren. Für andere Schlussfolgerungsbemühungen verwendet die Wissensdatenbank ein LLM, um Benutzerabfragen vor dem Abruf umzuformulieren.

Weitere Informationen zu diesem Schritt finden Sie unter Create a knowledge base in Azure KI-Suche.

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"

Einrichten eines Projektclients

Verwenden Sie AIProjectClient, um eine Clientverbindung mit Ihrem Microsoft Foundry-Projekt zu erstellen. Ihr Projekt enthält möglicherweise noch keine Agents, aber wenn Sie dieses Lernprogramm bereits abgeschlossen haben, wird der Agent hier aufgeführt.

from azure.ai.projects import AIProjectClient

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

list(project_client.agents.list())

Erstellen einer Projektverbindung

Der folgende Code erstellt eine Projektverbindung in Microsoft Foundry, die auf den MCP-Endpunkt Ihrer Wissensbasis verweist. Diese Verbindung verwendet Ihre vom Projekt verwaltete Identität, um sich bei Azure KI-Suche zu authentifizieren.

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

Erstellen eines Agents mit dem MCP-Tool

Mit dem folgenden Code wird ein Agent erstellt, der mit dem MCP-Tool konfiguriert ist. Wenn der Agent eine Benutzerabfrage empfängt, kann er Ihre Wissensbasis über das MCP-Tool aufrufen, um relevante Inhalte für die Reaktionserdierung abzurufen.

Die Agentdefinition enthält Anweisungen, die das Verhalten und die zuvor erstellte Projektverbindung angeben. Basierend auf unseren Experimenten sind diese Anweisungen effektiv, um die Genauigkeit von Wissensbasisaufrufen zu maximieren und eine ordnungsgemäße Zitatformatierung sicherzustellen.

Weitere Informationen zu diesem Schritt finden Sie in der Schnellstartanleitung: Erstellen eines neuen Agents.

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

(Optional) Berechtigungen mit anforderungsspezifischen Headern erzwingen

Wenn eine Ihrer Wissensquellen berechtigungsgeschützte Inhalte enthält, kann das Abrufmodul Ergebnisse filtern, sodass jeder Benutzer nur die Dokumente sieht, auf die er für den Zugriff autorisiert ist. Um diese Filterung zu aktivieren, leiten Sie das Identitätstoken des angemeldeten Benutzers im x-ms-query-source-authorization Header der MCP-Toolverbindung weiter. Ohne das Token geben berechtigungsfähige Quellen Ergebnisse ungefiltert zurück. Weitere Informationen finden Sie unter Erzwingen von Berechtigungen zur Abfragezeit (Vorschau).

Um MCP-Header pro Anforderung zu variieren, z. B. das Übergeben eines anderen Benutzertokens für jeden Aufruf, deklarieren Sie eine strukturierte Eingabe in der Agentdefinition, und verweisen Sie sie als ein {{placeholder}} Element im Tool headers. Der Aufrufer übergibt den Wert bei jedem Aufruf. Dieser Ansatz funktioniert für MCP-Tools, die an eine Projektverbindung gebunden sind.

Für die Benutzerautorisierung für einen MCP-Server können Sie auch OAuth Identity Passthrough verwenden.

Der folgende Code aktualisiert den Agent aus dem vorherigen Schritt, sodass das MCP-Tool seinen Autorisierungsheader aus einer strukturierten Eingabe liest.

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

Wenn Sie den Agent aufrufen, geben Sie ein Azure KI-Suche Token in structured_inputs. In diesem Beispiel wird ein Token aus dem aktuellen credential aufgelöst. Übergeben Sie für eine Mehrbenutzer-App stattdessen das Token jedes angemeldeten Benutzers. Verwenden Sie z. B. ein Token, das über einen On-Behalf-Of-Flow bezogen wurde, damit die Abruf-Engine die Ergebnisse für diesen Benutzer filtern kann.

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

Chatten mit dem Agent

Ihre Client-App verwendet die Unterhaltungs- und Responses-APIs aus Azure OpenAI, um mit dem Agent zu interagieren.

Der folgende Code erstellt eine Unterhaltung und übergibt Benutzernachrichten an den Agent und ähnelt einer typischen Chaterfahrung. Der Agent entscheidet, wann die Wissensdatenbank über das MCP-Tool aufgerufen wird und liefert eine Antwort in natürlicher Sprache mit Verweisen. Durch die Einstellung tool_choice="required" wird sichergestellt, dass der Agent beim Verarbeiten von Abfragen immer das Knowledge Base-Tool verwendet.

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

Die Antwort sollte dem folgenden Beispiel ähneln.

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)

Überprüfen der Antwort

Die zugrunde liegende Antwort des Agents enthält Metadaten zu den Abfragen, die an die Knowledge Base gesendet wurden, und die gefundenen Zitate. Sie können diese Metadaten überprüfen, um zu verstehen, wie der Agent die Benutzereingabe verarbeitet hat.

response.to_dict()

Bereinigen von Ressourcen

Wenn Sie in Ihrem eigenen Abonnement arbeiten, ist es ratsam, ein Projekt abzuschließen, indem Sie die nicht mehr benötigten Ressourcen entfernen. Ressourcen, die Sie weiterhin ausführen, können Sie Geld kosten.

Wählen Sie im Azure Portal All resources or Resource groups aus dem linken Bereich aus, um Ressourcen zu suchen und zu verwalten. Sie können Ressourcen einzeln löschen oder die Ressourcengruppe löschen, um alle Ressourcen gleichzeitig zu entfernen.

Sie können auch den folgenden Code ausführen, um einzelne Objekte zu löschen:

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

Verbessern der Datenqualität

Standardmäßig werden Suchergebnisse aus Wissensdatenbanken zu einer großen, einheitlichen Zeichenfolge zusammengeführt, die Sie zur Kontextverankerung an Agenten übergeben können. Azure KI-Suche stellt die folgenden Indizierungs- und Relevanzoptimierungsfeatures bereit, mit denen Sie qualitativ hochwertige Ergebnisse generieren können. Sie können diese Features im Suchindex implementieren, und die Verbesserungen der Suchrelevanz werden in der Qualität der Abrufantworten deutlich.

• Bewertungsprofile bieten integrierte Verbesserungskriterien. Ihr Index muss ein Standardbewertungsprofil angeben, das vom Abrufmodul verwendet wird, wenn Abfragen Felder enthalten, die diesem Profil zugeordnet sind.

• Die semantische Konfiguration ist erforderlich, aber Sie bestimmen, welche Felder priorisiert und für die Rangfolge verwendet werden.

• Bei Nur-Text-Inhalten können Sie Analysegeräte verwenden, um die Tokenisierung während der Indizierung zu steuern.

• Für multimodale oder Bildinhalte können Sie während der Indizierung Bildverbalisierung für LLM-generierte Beschreibungen Ihrer Bilder oder klassische OCR und Bildanalyse über Skillsets verwenden.

Steuern der Anzahl von Unterabfragen

Sie können die Anzahl der Unterabfragen steuern, indem Sie den Begründungsaufwand für den Abruf in der Wissensbasis festlegen. Der Grundaufwand bestimmt den Grad der LLM-Verarbeitung für die Abfrageplanung, von minimal (keine LLM-Verarbeitung) bis hin zu mittleren (tieferen Such- und Nachverfolgungsdurchläufen).

Bei nicht minimalem Aufwand bei der Argumentation bestimmt das LLM die Anzahl der Unterabfragen basierend auf den folgenden Faktoren:

• Benutzerabfrage
• Chatverlauf
• Eingabeeinschränkungen für semantischen Rangierer

Den an den Agenten gesendeten Kontext steuern.

Die Antwort-API steuert, was an den Agent und die Knowledge Base gesendet wird. Um die Leistung und Relevanz zu optimieren, passen Sie die Agent-Anweisungen an, um den Chatverlauf zusammenzufassen oder zu filtern, bevor Sie ihn an das MCP-Tool senden.

Kosten kontrollieren und Betriebsabläufe einschränken

Um Einblicke in den Abfrageplan zu erhalten, sehen Sie sich Ausgabetoken im Aktivitätsarray von Wissensdatenbank-Antworten an.

Verbessern der Leistung

Berücksichtigen Sie die folgenden Strategien, um die Leistung zu optimieren und die Latenz zu reduzieren:

• Zusammenfassung von Nachrichtenthreads.

• Verwenden Sie gpt-5-mini oder ein kleineres Modell, das schneller ausgeführt wird.

• Legen Sie maxOutputSize bei der Abrufen-Aktion fest, um die Größe der Antwort zu steuern oder maxRuntimeInSeconds um die zeitgebundene Verarbeitung zu verwalten.

• Teilen Sie große Dokumente in kleinere Teile, bevor sie indiziert werden. Dokumente, die das Ausgabebudget überschreiten, können stillschweigend aus fundierten Ergebnissen ausgeschlossen werden.

Verwandte Inhalte

• Agentic-Abruf in Azure KI-Suche
• Agentic RAG: Erstellen Sie ein Begründungsabrufmodul mit Azure KI-Suche (YouTube-Video)
• Azure OpenAI-Demo mit agentengesteuertem Abruf