Schnellstart: Hinzufügen einer Knowledge Base für Foundry IQ zu einem gehosteten Agent mit einer Toolbox

In dieser Schnellstartanleitung binden Sie einen gehosteten Agenten an die Wissensbasis Foundry IQ in Foundry Tools an und greifen über eine Toolbox auf diese Wissensbasis zu. Eine Wissensbasis in Foundry IQ verwendet die agentische Abfrage von Azure KI-Suche, um eine Abfrage zu planen, Ihre Daten zu durchsuchen, Ergebnisse neu einzustufen und eine Antwort mit Quellenangaben zu erstellen. Die Toolbox macht den MCP-Endpunkt (Model Context Protocol) der Knowledge Base als einzelnes Tool verfügbar, und der Agent ruft dieses Tool mit einer eigenen verwalteten Identität für die schlüssellose Authentifizierung auf.

Sie schließen drei Teile ab:

• Richten Sie eine Wissensdatenbank einmalig mit einem Python-Skript ein, das einen Suchindex erstellt, ihn mit Beispieldokumenten befüllt und die Wissensquelle sowie die Wissensdatenbank einrichtet.
• Erstellen Sie eine Toolboxverbindung , die auf den MCP-Endpunkt der Wissensbasis abzielt und sich mit der verwalteten Identität des Agents authentifiziert.
• Stellen Sie einen gehosteten Agent bereit , der das knowledge_base_retrieve Tool über die Toolbox ermittelt und seine Antworten in den abgerufenen Quellen begründet.

Der Agentcode, das Knowledge Base-Bereitstellungsskript, die Toolboxdefinition und ein Automatisierungshaken stammen aus dem Foundry IQ-Beispiel, sodass Sie sich nicht auf die Implementierung, sondern auf den Workflow konzentrieren.

Voraussetzungen

Dieser Schnellstart basiert auf der Toolchain des gehosteten Agenten. Führen Sie zunächst die Voraussetzungen in der Schnellstartanleitung des gehosteten Agents aus, die das Azure Abonnement, Projektrollen, Python, die Azure Developer CLI (azd) und die microsoft.foundry Erweiterung abdecken.

Außerdem benötigen Sie:

• Ein Azure KI-Suche Dienst, der den agentischen Abruf unterstützt. Aktivieren Sie eine vom System zugewiesene verwaltete Identität für den Dienst, und aktivieren Sie die rollenbasierte Zugriffssteuerung. Wechseln Sie im Azure-Portal im Suchdienst zu "Einstellungsschlüssel>", und legen Sie die API-Zugriffssteuerung auf "Sowohl" als auch auf "Rollenbasierte Zugriffssteuerung" fest.
• Die Bereitstellung eines Chatmodells in Ihrem Foundry-Projekt, z. B. gpt-5.4-mini. Die Wissensbasis verwendet dasselbe Modell, um Antworten zu synthetisieren.

Erforderliche Rollen

Weisen Sie vor der Bereitstellung die folgenden Rollen zu. Die Wissensdatenbank ruft das Modell mit der verwalteten Identität des Suchdiensts auf, daher benötigt diese Identität Zugriff auf Ihr Foundry-Konto.

Die verwaltete Identität des Agents ist erst vorhanden, nachdem Sie den Agent bereitgestellt haben, sodass Sie den Suchindexdatenleser in Schritt 6 zuweisen.

Schritt 1: Initialisieren des gehosteten Agents

Initialisieren Sie einen gehosteten Agent aus dem Foundry IQ-Beispiel. Das Beispiel enthält den Agentcode, das provision_kb.py Skript, die toolbox.yaml Definition und die Automatisierungshaken. Führen Sie diese Befehle in einem leeren Verzeichnis aus.

mkdir my-foundry-iq-agent
cd my-foundry-iq-agent
azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/17-foundry-iq-toolbox/azure.yaml"

Folgen Sie den Anweisungen, um Ihr Abonnement, das Foundry-Projekt und die Bereitstellung eines Chatmodells wie z. B. gpt-5.4-mini auszuwählen. Wenn Sie nicht über ein Projekt verfügen, führt Sie der Fluss durch das Erstellen eines Projekts. Initialisierung legt das ausgewählte Projekt als aktives Projekt fest und kopiert die Beispieldateien in ein neues Dienstverzeichnis. src/agent-framework-foundry-iq-knowledge-base-responses/

Schritt 2: Aktivieren Sie die Bereitstellung mit einem einzigen Befehl

Das Beispiel enthält einen postprovision Hook, der das Knowledge Base-Skript ausführt, die Toolboxverbindung erstellt, die Toolbox erstellt und die TOOLBOX_ENDPOINT Umgebungsvariable bei jeder Bereitstellung festlegt. Binden Sie den Hook in die von azure.yaml generierte azd ai agent init-Datei ein.

Öffnen Sie azure.yaml und fügen Sie diesen Block auf oberster Ebene hinzu. Der postprovision-Hook muss sich auf der obersten Ebene befinden, da dienstbezogene Hooks nur den Paket- und Bereitstellungslebenszyklus unterstützen.

hooks:
  postprovision:
    posix:
      shell: sh
      run: ./src/agent-framework-foundry-iq-knowledge-base-responses/hooks/postprovision.sh
    windows:
      shell: pwsh
      run: ./src/agent-framework-foundry-iq-knowledge-base-responses/hooks/postprovision.ps1

Der Hook sucht sein eigenes Verzeichnis, sodass er unabhängig davon funktioniert, aus welchem Verzeichnis azd ihn ausführt.

Schritt 3: Bereitstellen Azure Ressourcen und der Wissensbasis

1. Verweisen Sie mit dem Hook auf Ihren vorhandenen Suchdienst:

   azd env set AZURE_SEARCH_ENDPOINT "https://<your-search>.search.windows.net"
   

   Der Hook leitet den Modellendpunkt für die Antwortsynthese vom Projektendpunkt ab. Um eine andere Azure OpenAI-Ressource zu verwenden, legen Sie sie zunächst mit azd env set AZURE_OPENAI_ENDPOINT "https://<account>.openai.azure.com" fest.

2. Bereitstellen der Ressourcen und der Wissensbasis:

   azd provision
   

   azd provision erstellt Ihr Foundry-Projekt und Ihre Modellbereitstellung oder verwendet diese wieder. Der postprovision Haken dann:

   1. Führt provision_kb.py aus, um den foundry-iq-index Suchindex zu erstellen, die „Earth at night“-Dokumente einzuspielen und die foundry-iq-ks Wissensquelle sowie die foundry-iq-kb Wissensbasis zu erstellen. Das Skript speichert den MCP-Endpunkt der Knowledge Base als KB_MCP_ENDPOINT.
   2. Erstellt die knowledge-base-mcp Verbindung. Diese Verbindung zielt auf den MCP-Endpunkt der Wissensbasis ab und verwendet Agentic Identity, sodass sich die verwaltete Identität des Agents ohne gespeicherten geheimen Schlüssel authentifiziert.
   3. Erstellt die knowledge-base Toolbox aus toolbox.yaml, aus der das knowledge_base_retrieve Tool verfügbar gemacht wird.
   4. Legt TOOLBOX_ENDPOINT so fest, dass der Agent eine Verbindung zur Toolbox herstellt.

Schritt 4: Agenten lokal ausführen

1. Starten Sie den Agent:

   azd ai agent run
   

   Dieser Befehl erstellt eine virtuelle Umgebung, installiert Abhängigkeiten und stellt den Agenten unter http://localhost:8088 bereit. Vorschaupakete können während des Setups Pip-Warnungen erzeugen. Diese Warnungen sind nicht blockierend.

2. Stellen Sie dem Agenten in einem separaten Terminal eine Frage, die die Wissensbasis beantworten kann:

   azd ai agent invoke --local "What can you tell me about the Earth at night?"
   

   Der lokale Agent stellt eine Verbindung mit der Toolbox her, aber das Abrufen aus der Knowledge Base erfordert die Identität des bereitgestellten Agents. Verwenden Sie die lokale Ausführung, um zu bestätigen, dass der Agent gestartet wird und die Toolbox erreicht. Sie überprüfen fundierte Antworten nach der Bereitstellung.

Schritt 5: Bereitstellen für den Foundry Agent Service

Stellen Sie den Agent-Quellcode bereit. azd packt die Quelle als ZIP-Datei und lädt sie in Foundry hoch, wodurch Abhängigkeiten aufgelöst und der gehostete Agent remote erstellt wird:

azd deploy

Wenn der Befehl abgeschlossen ist, zeigt die Ausgabe Links zum Agent-Playground und zum Agent-Endpunkt an.

Schritt 6: Gewähren des Agents Zugriff auf die Knowledge Base

Der bereitgestellte Agent ruft mit seiner eigenen verwalteten Identität Daten aus der Wissensdatenbank ab. Gewähren Sie dieser Identität die Rolle "Suchindexdatenleser " im Suchdienst.

1. Suchen Sie die Identitätsobjekt-ID des Agents im Findry-Portal. Wechseln Sie zu "Agents", wählen Sie Ihren Agent und dann "Identität" aus.

2. Weisen Sie die Rolle für den Suchdienst zu:

   searchId=$(az search service show -n <search-name> -g <resource-group> --query id -o tsv)
   az role assignment create --assignee-object-id <agent-identity-object-id> \
     --assignee-principal-type ServicePrincipal \
     --role "Search Index Data Reader" --scope $searchId
   

   Verwenden Sie in PowerShell ein Graviszeichen zur Zeilenfortsetzung (`) anstelle von \.

Schritt 7: Aufrufen des bereitgestellten Agents

Senden Sie eine Frage an den bereitgestellten Agenten und bestätigen Sie, dass er anhand der Wissensdatenbank antwortet:

azd ai agent invoke "What can you tell me about the Earth at night?"

Der Agent liefert eine fundierte Antwort mit Verweisen auf die Beispieldokumente. Probieren Sie noch ein paar Fragen aus, um zu sehen, wie das Retrieval im Beispielkorpus funktioniert:

azd ai agent invoke "Why do some lights appear over the open ocean?"
azd ai agent invoke "How is nighttime imagery used to study light pollution?"

Bereinigen von Ressourcen

Löschen Sie die Ressourcen, wenn Sie fertig sind, damit Keine Gebühren anfallen.

1. Löschen Sie die Knowledge Base, die Wissensquelle und den Index aus Ihrem Suchdienst. Löschen Sie im Azure-Portal im Suchdienst foundry-iq-kb, foundry-iq-ks und den foundry-iq-index-Index. Sie können den Suchdienst für andere Projekte beibehalten.

2. Löschen Sie den Agent und seine Azure Ressourcen:

   Warning

   Wenn die aktuelle azd Umgebung das Foundry-Projekt erstellt hat, azd down werden die Ressourcengruppe des Projekts und alles darin endgültig gelöscht. Wenn Sie während der Initialisierung ein vorhandenes Projekt ausgewählt haben, azd down bleibt das Projekt, seine Ressourcengruppe, der gehostete Agent und andere Schnellstartressourcen vorhanden. Um Ressourcen zu löschen, die Sie nicht mehr aus dem vorhandenen Projekt benötigen, löschen Sie sie separat.

   azd down
   

Problembehandlung

Was Sie gelernt haben

In dieser Schnellstartanleitung führen Sie die folgenden Schritte aus:

• Erstellt eine Foundry IQ Knowledge Base mit einem Suchindex, einer Wissensquelle und Beispieldokumenten.
• Die Wissensdatenbank wurde über eine Toolboxverbindung verfügbar gemacht, die die verwaltete Identität des Agents verwendet.
• Bereitstellung eines gehosteten Agents, der seine Antworten in der Wissensbasis mit Zitaten begründet.

Nächster Schritt

Verwandte Inhalte

• Was ist Foundry IQ?
• Verbinden einer Foundry IQ Knowledge Base mit dem Foundry Agent Service
• Erstellen einer absichtsbasierten Toolbox in Foundry
• Schnellstart: Bereitstellen Ihres ersten gehosteten Agents