Lernprogramm: Aufrufen einer App Service-Web-App aus dem Azure AI Foundry Agent Service

Mit dem Azure AI Foundry Agent Service können Sie KI-Agents erstellen, die auf Ihre Anforderungen zugeschnitten sind, indem Sie benutzerdefinierte Anweisungen ausführen und durch erweiterte Tools wie Codedolmetscher und benutzerdefinierte Funktionen erweitert werden. Sie können jetzt Ihren Azure AI-Agent mit einer externen API verbinden, indem Sie ein angegebenes OpenAPI 3.0-Tool verwenden, was eine skalierbare Interoperabilität mit verschiedenen Anwendungen ermöglicht.

Azure App Service ist eine vollständig verwaltete Plattform zum Erstellen, Bereitstellen und Skalieren von Web-Apps und APIs. Wenn Ihre API in Azure App Service gehostet wird, können Sie Ihren KI-Agent mit der API mithilfe der OpenAPI-Spezifikation verbinden. Die OpenAPI-Spezifikation definiert die API und die Interaktion damit. Sie können dann die natürliche Sprache verwenden, um die API über Ihren KI-Agent aufzurufen. Dieses Tool ist leistungsfähig, da es Ihnen ermöglicht, Ihren vorhandenen Apps KI-Agent-Funktionen mit minimalen Codeänderungen hinzuzufügen. Außerdem hat dieser Agent die Möglichkeit, direkt mit Ihrer App zu interagieren. Es ist nicht erforderlich, erhebliche Codeänderungen oder Implementierungsarbeiten durchzuführen, außer kleinen Updates, um mit dem Agenten mithilfe der verfügbaren SDKs zu interagieren.

In diesem Lernprogramm verwenden Sie einen Azure AI Foundry-Agent, um eine vorhandene API aufzurufen, die auf Azure App Service gehostet wird. Am Ende dieses Lernprogramms haben Sie eine Mode-Assistent-Chatanwendung, die in App Service mit einem KI-Agent aus dem Azure AI Foundry Agent Service ausgeführt wird.

Voraussetzungen

• Ein GitHub-Konto. Sie können auch kostenlos eine bekommen.
• Ein Azure-Konto mit einem aktiven Abonnement. Wenn Sie nicht über ein Azure-Konto verfügen, können Sie ein konto kostenlos erstellen.

1. Untersuchen des Beispiels in GitHub Codespaces

Sehen Sie sich zunächst das Beispiel in GitHub an:

1. Melden Sie sich bei Ihrem GitHub-Konto an und navigieren Sie zu https://github.com/Azure-Samples/ai-agent-openai-web-app/fork.
2. Wählen Sie Create fork (Fork erstellen) aus.
3. Wählen Sie Code>Codespace im Mainbranch erstellen aus. Das Einrichten des Codespace dauert einige Minuten.

Das Beispiel-Repository enthält Folgendes:

2. Bereitstellen der Azure-Infrastruktur und -Anwendung

So stellen Sie die Azure-Infrastruktur und -Anwendung bereit:

1. Melden Sie sich mithilfe des Befehls azd auth login bei Ihrem Azure-Konto an, und folgen Sie der Eingabeaufforderung:

   azd auth login
   

2. Erstellen Sie die App Service-App, und stellen Sie den Code mithilfe des Befehls azd up bereit:

   azd up
   

   Die Ausführung des Befehls azd up kann einige Minuten dauern. azd up verwendet die Bicep-Dateien in Ihren Projekten, um einen App-Dienst im P0v3-Preisniveau zu erstellen und die .NET-App in src/webapp bereitzustellen. Der Befehl erstellt außerdem die Azure AI Foundry und unterstützende Ressourcen für den Agent.

3. Erstellen des KI-Agents

So erstellen Sie den KI-Agent:

1. Navigieren Sie im Azure-Portal zu der Ressourcengruppe , die von der azd-Vorlage erstellt wird. Der Name der Ressourcengruppe befindet sich in der Ausgabe des azd-Befehls, den Sie ausführen.

2. Wählen Sie die Azure AI-Projektressource aus. Der Name sollte im Format vorliegen ai-aiproject-<identifier>. Stellen Sie sicher, dass Sie die Projektressource und nicht die Hub- oder KI-Dienstressourcen auswählen. Agents werden aus der Azure AI-Projektressource erstellt.

3. Wählen Sie "Studio starten" aus, um das Azure AI Foundry Studio zu öffnen.

4. Wählen Sie im linken Menü unter "Erstellen und Anpassen" "Agents" aus.

5. Wenn die Seite geladen wird, wählen Sie in der Dropdownliste die automatisch generierte Azure OpenAI-Dienstressource aus, die für Sie erstellt wird, und wählen Sie dann "Los geht's".

6. Wählen Sie +Neuer Agent aus, um einen neuen Agent zu erstellen, oder verwenden Sie den Standard-Agent, wenn dieser bereits für Sie erstellt wurde.

7. Wenn der Agent erstellt wird, fügen Sie die folgenden Anweisungen im rechten Menü hinzu. Diese Anweisungen stellen sicher, dass Ihr Agent nur Fragen beantwortet und Aufgaben im Zusammenhang mit der Fashion Store-App ausführt.

    You are an agent for a fashion store that sells clothing. You have the ability to view inventory, update the customer's shopping cart, and answer questions about the clothing items that are in the inventory. You should not answer questions about topics that are unrelated to the fashion store. If a user asks an unrelated question, please respond by telling them that you can only talk about things that are related to the fashion store.
    

4. Hinzufügen des angegebenen OpenAPI-Tools zum KI-Agent

Ausführliche Anleitungen mit Screenshots und zusätzlichen Informationen finden Sie im Abschnitt Hinzufügen des OpenAPI-Spezifikationstools im Azure AI Foundry-Portal. Die Schritte werden in den folgenden Anweisungen zusammengefasst.

1. Wählen Sie + Hinzufügen neben Aktion aus.

2. Wählen Sie das angegebene Tool OpenAPI 3.0 aus.

3. Geben Sie Ihrem Tool einen Namen und die folgende Beschreibung. Die Beschreibung wird vom Modell verwendet, um zu entscheiden, wann und wie das Tool verwendet wird.

    This tool is used to interact with and manage an online fashion store. The tool can add or remove items from a shopping cart as well as view inventory.
    

4. Behalten Sie die Authentifizierungsmethode als anonym bei. Es gibt keine Authentifizierung in der Web-App. Wenn die App einen API-Schlüssel oder eine verwaltete Identität benötigt hat, um darauf zuzugreifen, geben Sie an diesem Speicherort diese Informationen an.

5. Kopieren Sie die OpenAPI-Spezifikation, und fügen Sie sie in das Textfeld ein. Die OpenAPI-Spezifikation befindet sich im Codespace im src/webapp Verzeichnis und heißt swagger.json.

6. Bevor Sie das Tool erstellen, müssen Sie die URL Ihrer App in die OpenAPI-Spezifikation kopieren und einfügen. Ersetzen Sie den Platzhalter <APP-SERVICE-URL> in Zeile 10 der OpenAPI-Spezifikation durch die URL Ihrer App. Sie hat das Format https://<app-name>.azurewebsites.net.

   • Um die URL Ihrer App zu finden, wechseln Sie zurück zur Ressourcengruppe, und navigieren Sie zu Ihrem App-Dienst. Die URL befindet sich auf der Seite "Übersicht" Ihres App-Diensts.

7. Wählen Sie "Weiter" aus, überprüfen Sie die von Ihnen bereitgestellten Details, und wählen Sie dann " Tool erstellen" aus.

5. Verbinden Ihres App-Diensts mit dem KI-Agent

Nachdem Sie den KI-Agent eingerichtet und das angegebene OpenAPI-Tool hinzugefügt haben, müssen Sie Ihren App-Dienst mit den entsprechenden Umgebungsvariablen konfigurieren, damit die App weiß, mit welchem Agent eine Verbindung hergestellt werden soll. Die App verfügt bereits über eine verwaltete Identität, die ihm Zugriff auf den AI-Agent-Dienst gewährt. Diese verwaltete Identität ist erforderlich, damit die App den Agent erreicht und mit der azd-Vorlage erstellt wird.

1. Notieren Sie im Agents-Dashboard, in dem Sie das OpenAPI-Tool hinzugefügt haben, die Agent-ID. Sie hat das Format asst_<unique-identifier>.
2. Wählen Sie im Menü "Übersicht" aus, und notieren Sie sich die Verbindungszeichenfolge des Projekts. Sie hat das Format <region>.api.azureml.ms;<subscription-id>;<resource-group-name>;<project-name>.
3. Navigieren Sie im Azure-Portal zu Ihrer App Service-Instanz.
4. Wählen Sie "Umgebungsvariablen " im linken Menü aus.
5. Wählen Sie auf der Registerkarte "App-Einstellungen " +Hinzufügen aus, und fügen Sie die folgende Einstellung hinzu:
   • Name: AzureAIAgent__ConnectionString
   • Wert: Die Verbindungszeichenfolge, die Sie von Ihrem KI-Agenten-Dienst notiert haben
6. Fügen Sie eine weitere App-Einstellung hinzu:
   • Name: AzureAIAgent__AgentId
   • Wert: Die Agent-ID, die Sie beim Erstellen Ihres Agents notiert haben
7. Wählen Sie unten auf der Seite Anwenden aus, wenn Sie dazu aufgefordert werden. Die App wird neu gestartet, wobei die neuen Einstellungen angewendet wurden.

6. Überprüfen der ausgeführten App

Suchen Sie in der azd-Ausgabe die URL für Ihre App, und navigieren Sie im Browser dorthin. Die URL sieht in der azd-Ausgabe wie folgt aus:

Deploying services (azd deploy)

    (✓) Done: Deploying service web
    - Endpoint: https://<app-name>.azurewebsites.net/

Stellen Sie im Chatfenster Fragen an den Agenten wie:

• Was befindet sich in meinem Warenkorb?
• Hinzufügen einer kleinen Denim-Jacke zu meinem Warenkorb
• Haben wir blazer auf Lager? Sie können auch allgemeine Fragen zu den Elementen stellen und der Agent sollte Informationen bereitstellen können.
• Erzählen Sie mir von Red Slim Fit Checked Casual Shirt
• Ist der Blazer warm?

Bereinigen von Ressourcen

Wenn Sie mit dieser App fertig sind, führen Sie Folgendes aus, um die Ressourcengruppe mit allen ressourcen zu löschen, die während dieses Lernprogramms erstellt wurden.

azd down

Problembehandlung

Häufige Probleme

1. Chat funktioniert nicht
   • Stellen Sie sicher, dass die Umgebungsvariablen (AzureAIAgent__ConnectionString und AzureAIAgent__AgentId) in den App Service-Umgebungsvariablen korrekt festgelegt sind.
   • Überprüfen Sie, ob der AI-Agent ordnungsgemäß erstellt und mit dem richtigen OpenAPI-Tool konfiguriert ist.
   • Stellen Sie sicher, dass auf die OpenAPI-Spezifikations-URL über den Azure AI Foundry Agent Service zugegriffen werden kann.
   • Stellen Sie sicher, dass die App-Dienst-URL im für das OpenAPI Specified Tool bereitgestellte swagger.json aktualisiert wird.
2. Berechtigungsprobleme
   • Wenn Authentifizierungsfehler auftreten, stellen Sie sicher, dass die verwaltete Identität Ihres App-Diensts über die richtigen Berechtigungen für den Zugriff auf den Azure AI Foundry Agent Service verfügt. Die verwaltete Identität benötigt mindestens die Microsoft.MachineLearningServices/workspaces/agents/action Berechtigung, um mit dem Agenten zu interagieren. Die bereitgestellte "Azure AI-Entwicklerrolle" verfügt über diese Berechtigung und sollte ausreichend sein. Wenn Sie sich entscheiden, diese Rolle zu ändern, stellen Sie sicher, dass sie über die erforderliche Berechtigung verfügt.
3. API-Probleme
   • Wenn der Agent keine Aktionen für den Bestand oder den Warenkorb ausführen kann, überprüfen Sie die API-Routen in der OpenAPI-Spezifikation.
   • Stellen Sie sicher, dass die API-Endpunkte korrekt reagieren, indem Sie sie direkt in der Swagger-Benutzeroberfläche unter /api/docstesten.

Anzeigen von Protokollen

So zeigen Sie Protokolle für Ihren App-Dienst an:

1. Navigieren Sie im Azure-Portal zu Ihrer App Service-Instanz.
2. Wählen Sie im linken Menü denÜberwachungsprotokolldatenstrom> aus, um Echtzeitprotokolle anzuzeigen.
3. In diesen Protokollen werden alle Anwendungsprobleme angezeigt, die Sie möglicherweise beheben müssen.

Grundlegendes zu den API-Funktionen

Die OpenAPI-Spezifikation stellt dem KI-Agent Informationen zu verfügbaren Endpunkten bereit:

Cart-API-Endpunkte

• GET /api/Cart: Ruft den aktuellen Warenkorbinhalt und die Gesamtkosten ab.
• DELETE /api/Cart: Löscht alle Artikel aus dem Warenkorb
• POST /api/Cart/add: Fügt dem Einkaufswagen einen Artikel hinzu
• PUT /api/Cart/{productId}/size/{size}: Aktualisiert die Menge eines bestimmten Artikels.
• DELETE /api/Cart/{productId}/size/{size}: Entfernt einen bestimmten Artikel aus dem Warenkorb.

Bestands-API-Endpunkte

• GET /api/Inventory: Listet alle verfügbaren Bestandselemente auf
• GET /api/Inventory/{id}: Ruft Details zu einem bestimmten Produkt ab
• GET /api/Inventory/{id}/size/{size}: Überprüft den Bestand auf eine bestimmte Produktgröße.
• GET /api/Inventory/sizes: Ruft alle verfügbaren Größen im Bestand ab.

Erweiterte Agentinteraktionen

Über grundlegende Interaktionen hinaus kann der KI-Agent komplexere Szenarien behandeln:

• Personalisierte Empfehlungen: "Ich benötige ein business casual Outfit für eine Besprechung"
• Größenleitfaden: "Welche Größe blazer würde jemanden passen, der 6'2" und 180 Pfund hat?"
• OutfitKoordination: "Was würde gut mit der schwarzen Denimjacke gehen?"
• Einkaufswagenverwaltung: „Entfernen Sie das Hemd in Größe L und fügen Sie stattdessen eins in Größe M hinzu“
• Bestandsprüfungen: "Haben Sie rote Hemden in Größe M?"
• Preisanfragen: "Was ist die Preisspanne für Blazer?"

Sicherheitsüberlegungen

• Die Anwendung verwendet von Azure verwaltete Identitäten für die sichere Authentifizierung bei Azure AI Foundry Agent Service in Produktionsumgebungen.
• Sie können Ihre App und Ihren Agent mithilfe einer der Standardpraktiken und Azure-Ressourcen weiter schützen. Sichere Azure AI Agent-Infrastrukturvorlagen finden Sie im Azureai-Beispiel-Repository.

Verwandte Inhalte

Nachdem Sie nun erfahren haben, wie Sie Ihren KI-Agent mit einer API für Azure App Service verbinden, können Sie die anderen KI-Integrationen erkunden, die mit App Service verfügbar sind:

• Lernprogramm: Erstellen eines Chatbots mit Azure App Service und Azure OpenAI (.NET)
• Lernprogramm: Ausführen eines Chatbots in App Service mit einer Phi-4-Sidecar-Erweiterung (ASP.NET Core)
• Bereitstellen einer .NET Blazor-App, die mit Azure SQL und Azure OpenAI in Azure App Service verbunden ist