Lernprogramm: Erstellen einer agentischen Web-App in Azure App Service mit LangGraph oder Foundry Agent Service (Python)

In diesem Tutorial wird veranschaulicht, wie Sie einer vorhandenen datengesteuerten FastAPI CRUD-Anwendung Agentfunktionen hinzufügen. Dazu werden zwei verschiedene Ansätze verwendet: LangGraph und Foundry Agent Service.

Wenn Ihre Webanwendung bereits nützliche Funktionen wie Shopping, Hotelbuchung oder Datenverwaltung aufweist, ist es relativ einfach, Ihrer Webanwendung Agent-Funktionen hinzuzufügen, indem diese Funktionen in ein Plug-In (für LangGraph) oder als OpenAPI-Endpunkt (für Foundry Agent Service) eingeschlossen werden. In diesem Tutorial beginnen Sie mit einer einfachen Aufgabenlisten-App. Am Ende können Sie Aufgaben mit einem Agent in einer App Service App erstellen, aktualisieren und verwalten.

Sowohl der LangGraph- als auch der Foundry-Agent-Dienst ermöglichen es Ihnen, agentische Webanwendungen mit KI-gesteuerten Funktionen zu erstellen. LangGraph ähnelt Microsoft Agent Framework und ist ein SDK. In der folgenden Tabelle sind einige Überlegungen und Kompromisse aufgeführt:

Überlegung LangGraph oder Microsoft Agent Framework Gießerei-Agentendienst
Leistung Schnell (lokal ausgeführt) Langsamer (verwaltet, Remotedienst)
Entwicklung Vollständiger Code, maximale Kontrolle Wenig Code, schnelle Integration
Testen Manuelle/Komponententests im Code Integrierter Playground für schnelle Tests
Skalierbarkeit App-verwaltet Von Azure verwaltet, automatisch skaliert
Sicherheitsschutzschienen Benutzerdefinierte Implementierung erforderlich Integrierte Sicherheit und Moderation von Inhalten
Identität Benutzerdefinierte Implementierung erforderlich Integrierte Agent-ID und Authentifizierung
Enterprise Benutzerdefinierte Integration erforderlich Integrierte Microsoft 365/Teams-Bereitstellung und Integrierte Microsoft 365-Toolaufrufe.

In diesem Tutorial lernen Sie Folgendes:

  • Konvertieren Sie vorhandene App-Funktionen in ein Plug-In für LangGraph.
  • Fügen Sie das Plug-In einem LangGraph-Agent hinzu, und verwenden Sie es in einer Web-App.
  • Konvertieren Sie vorhandene App-Funktionen in einen OpenAPI-Endpunkt für den Foundry Agent Service.
  • Rufen Sie einen Foundry-Agent in einer Web-App auf.
  • Weisen Sie die erforderlichen Berechtigungen für die Konnektivität der verwalteten Identität zu.

Voraussetzungen

Öffnen des Beispiels mit Codespaces

Die einfachste Möglichkeit für den Einstieg ist die Verwendung von GitHub Codespaces, die eine vollständige Entwicklungsumgebung mit allen erforderlichen vorinstallierten Tools bereitstellt.

  1. Navigieren Sie zum GitHub-Repository unter https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-python.

  2. Wählen Sie die Schaltfläche Code, dann die Registerkarte Codespaces und dann Codespace im Hauptfeld erstellen aus.

  3. Warten Sie einen Moment, bis Ihr Codespace initialisiert wurde. Wenn Sie fertig sind, wird in Ihrem Browser eine vollständig konfigurierte Entwicklungsumgebung angezeigt.

  4. Lokales Ausführen der Anwendung:

    python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn src.app:app --host 0.0.0.0 --port 3000

  5. Wenn Sie sehen, dass Ihre Anwendung auf Port 3000 ausgeführt wird, wählen Sie Im Browser öffnen aus, und fügen Sie einige Aufgaben hinzu.

    Die Agents sind nicht vollständig konfiguriert, sodass sie noch nicht funktionieren. Sie konfigurieren sie später.

Überprüfen des Agent-Codes

Beide Ansätze verwenden das gleiche Implementierungsmuster, bei dem der Agent beim Anwendungsstart initialisiert wird und mit POST-Anforderungen auf Benutzernachrichten reagiert.

Dies LangGraphTaskAgent wird im Konstruktor in src/agents/langgraph_task_agent.py initialisiert. Der Initialisierungscode führt Folgendes aus:

  • Konfiguriert den AzureChatOpenAI-Client mithilfe von Umgebungsvariablen.
  • Erstellt den vordefinierten ReAct-Agent mit Arbeitsspeicher und einer Reihe von CRUD-Tools für die Aufgabenverwaltung (siehe Schnellstart von LangGraph).
  • Wählt einen serververwalteten Konversationsthread für die authentifizierte Probe aus.
self.memory = InMemorySaver()
# App Service authentication protects this sample, which intentionally
# keeps one server-managed conversation thread per worker process.
self.thread_id = "authenticated-conversation"

try:
    endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    deployment_name = os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME")
    
    if not endpoint or not deployment_name:
        print("Azure OpenAI configuration missing for LangGraph agent")
        return
    
    # Initialize Azure OpenAI client
    credential = DefaultAzureCredential()
    azure_ad_token_provider = get_bearer_token_provider(
        credential, "https://cognitiveservices.azure.com/.default"
    )
    
    self.llm = AzureChatOpenAI(
        azure_endpoint=endpoint,
        azure_deployment=deployment_name,
        azure_ad_token_provider=azure_ad_token_provider,
        api_version="2024-10-21"
    )
    
    # Define tools
    tools = [
        self._create_task_tool(),
        self._get_tasks_tool(),
        self._get_task_tool(),
        self._update_task_tool(),
        self._delete_task_tool()
    ]
    
    # Create the agent
    self.agent = create_react_agent(self.llm, tools, checkpointer=self.memory)

Bei der Verarbeitung von Benutzernachrichten ruft der Agent ainvoke() mit der serverseitig verwalteten Thread-ID auf:

config = {"configurable": {"thread_id": self.thread_id}}

# Process the message
result = await self.agent.ainvoke(
    {"messages": [("user", message)]},
    config=config
)

Die Browseranfrage enthält nur die Nachricht. Er kann keinen anderen Thread auswählen, indem er eine Sitzungs- oder Konversationskennung angibt.

Bereitstellen der Beispielanwendung

Das Beispiel-Repository enthält eine Azure Developer CLI (AZD)-Vorlage, die eine App Service-App erstellt und deine Beispielanwendung bereitstellt. Die vom App Service systemzugeordneten verwalteten Identität wird für ausgehende Azure-KI-Aufrufe beibehalten. Eine separate, vom Benutzer zugewiesene verwaltete Identität und eine föderierte Identitätszugangsdaten ermöglichen es der App Service-Authentifizierung, als generierte Microsoft Entra-Anwendung ohne Client-Geheimnis zu fungieren.

  1. Im Terminal melden Sie sich mit Azure Developer CLI bei Azure an:

    azd auth login

    Folgen Sie den Anweisungen, um den Authentifizierungsprozess abzuschließen.

  2. Deploye die Azure App Service App mit der AZD-Vorlage:

    azd up

  3. Wenn Sie dazu aufgefordert werden, geben Sie die folgenden Antworten:

    Frage Antwort
    Geben Sie einen neuen Umgebungsnamen ein: Geben Sie einen eindeutigen Namen ein.
    Wählen Sie ein zu verwendende Azure-Abonnement aus: Wählen Sie das Abonnement aus.
    Wählen Sie eine zu verwendende Ressourcengruppe aus: Wählen Sie Eine neue Ressourcengruppe erstellen aus.
    Wählen Sie einen Speicherort aus, an dem die Ressourcengruppe erstellt werden soll: Wählen Sie "Schweden Zentral" aus.
    Geben Sie einen Namen für die neue Ressourcengruppe ein: Geben Sie Eingeben ein.

  4. Suchen Sie in der AZD-Ausgabe die URL für Ihre App, und navigieren Sie im Browser dorthin. Kopiere außerdem den Wert für die Foundry OpenAPI-Zielgruppe der verwalteten Identität zur späteren Verwendung. Die Ausgabe sieht wie folgt aus:

     Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: <URL>

 Foundry OpenAPI managed identity audience:
     api://<generated-client-id>

  5. Wenn Microsoft Sie auffordert, melden Sie sich mit einem Konto im Deployment-Tenant an und überprüfen Sie, ob die Aufgabenliste geladen ist.

  6. Im selben authentifizierten Browser hängen Sie /openapi.json dem App-Service-Endpunkt an. Kopiere oder speichere das generierte OpenAPI-Schema für später.

    Hinweis

    Die App Service-Authentifizierung gibt eine HTTP-302-Weiterleitung für nicht authentifizierte Browseranfragen zurück. Dieses Beispiel enthält sowohl eine Browser-Benutzeroberfläche als auch APIs, sodass die Weiterleitung ein brauchbares Anmeldeerlebnis bietet. API-only-Apps verwenden stattdessen häufig HTTP 401.

Erstellen und Konfigurieren der Microsoft Foundry-Ressource

  1. Im Foundry-Portal erstellen Sie ein Projekt.

  2. Stellen Sie ein Modell Ihrer Wahl bereit (siehe Schnellstart von Microsoft Foundry: Erstellen von Ressourcen).

  3. Kopieren Sie den Namen des Modells aus dem oberen Bereich des Modell-Playrounds.

  4. Auf der Startseite kopieren Sie den Azure OpenAI-Endpunkt für später.

Zuweisen der erforderlichen Berechtigungen

  1. Im Foundry-Portal wählen Sie im oberen Menü "Verwalten " aus.

  2. In Project Details wählen Sie die Elternressource Ihres Projekts aus und wählen Sie dann im Azure-Portal öffnen.

    Vom Azure-Portal aus können Sie rollenbasierten Zugriff für die Ressource zuweisen.

  3. Fügen Sie die folgende Rolle sowohl für die verwaltete Identität der App Service-App als auch für den Benutzer hinzu, den Sie mit az login verwenden:

    Zielressource Erforderliche Rolle Erforderlich für
    Gießerei Kognitive Dienste OpenAI-Nutzer Der Chatabschlussdienst in Microsoft Agent Framework.

    Anweisungen hierzu finden Sie unter Zuweisen von Azure-Rollen über das Azure-Portal.

Konfigurieren von Verbindungsvariablen in Ihrer Beispielanwendung

  1. Öffnen Sie .env. Konfigurieren Sie mithilfe der Werte, die Sie zuvor aus dem Foundry-Portal kopiert haben, die folgenden Variablen:

    Variable Description
    AZURE_OPENAI_ENDPOINT Azure OpenAI-Endpunkt (kopiert von der Startseite des Foundry-Portals).
    AZURE_OPENAI_DEPLOYMENT_NAME Modellname in der Bereitstellung (kopiert aus dem Modell-Playground im New Foundry Portal).

    Hinweis

    Um das Tutorial einfach zu halten, verwenden Sie diese Variablen in ENV, anstatt sie mit App-Einstellungen in App Service zu überschreiben.

    Hinweis

    Um das Tutorial einfach zu halten, verwenden Sie diese Variablen in ENV, anstatt sie mit App-Einstellungen in App Service zu überschreiben.

    Die Werte in .env konfigurieren die ausgehende Verbindung der App zu Foundry. AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID konfiguriert die separate eingehende Foundry-to-App-Service OpenAPI-Verbindung und wird in der AZD-Umgebung gespeichert.

  2. Anmelden bei Azure mit der Azure CLI:

    az login

    Dadurch kann die Azure Identity-Clientbibliothek im Beispielcode ein Authentifizierungstoken für den angemeldeten Benutzer empfangen. Denken Sie daran, dass Sie die erforderliche Rolle für diesen Benutzer zuvor hinzugefügt haben.

  3. Lokales Ausführen der Anwendung:

    source venv/bin/activate
uvicorn src.app:app --host 0.0.0.0 --port 3000

  4. Wenn Sie sehen, dass Ihre Anwendung auf Port 3000 ausgeführt wird, wählen Sie Im Browser öffnen aus.

  5. Validiere beide Pivots separat:

    • LangGraph: Wählen Sie LangGraph Agent und bitten Sie den Agenten, eine Aufgabe zu erstellen. LangGraph ruft das In-Process-Aufgabentool auf.
    • Foundry Agent Service: Wählen Sie Foundry Agent aus und bitten Sie den Agenten, einen Task zu erstellen. Der entfernte Foundry-Agent ruft den bereitgestellten, geschützten /api/tasks Endpunkt mit verwalteter Identität auf.

    Die Aufgabe, die der Foundry-Agent erstellt, erscheint in der bereitgestellten App Service-Instanz, nicht in der lokalen SQLite-Datenbank. Das Foundry OpenAPI-Tool verwendet immer die Server-URL, die im OpenAPI-Schema eingebettet ist.

  6. Stellen Sie ihre App-Änderungen wieder im GitHub-Codespace bereit.

    azd up

  7. Navigiere erneut zur bereitgestellten Anwendung und teste beide Chat-Agenten. Der Browser sendet nur Nachrichtentext; Es sendet weder eine Sitzungs-ID noch eine Konversations-ID für einen der beiden Agenten.

Häufig gestellte Fragen

Wie füge ich dem Foundry-Agenten Retrieval-Augmented Generation (RAG) hinzu?

Diese Anleitung gilt für den Foundry Agent Service-Weg in diesem Tutorial. Es ändert nicht die im anderen Tab gezeigten Implementierungen von LangGraph, Semantischer Kernel oder Microsoft Agent Framework.

Erstellen oder wählen Sie eine Foundry IQ Wissensdatenbank und verbinden Sie diese dann mit dem Foundry Agent Service Agenten. Die Verbindung wird dem Agenten als verwaltetes MCP-Wissenswerkzeug zur Verfügung gestellt.

Der App Service-Code ruft denselben Agenten weiterhin namentlich über seinen bestehenden Foundry-Client und agent_referenceauf. Die Webanwendung benötigt keine direkte Azure KI-Suche-Integration oder einen eigenen MCP-Client. Wenn die Benutzeroberfläche Quellen anzeigt, verarbeiten Sie die vom Agenten zurückgegebenen Zitationsanmerkungen.

Bereinigen von Ressourcen

Wenn Sie mit der Anwendung fertig sind, können Sie die App Service Ressourcen löschen, um weitere Kosten zu vermeiden:

azd down --purge

Der AZD-Hook postdown löscht außerdem die für die App Service-Authentifizierung erstellte Microsoft Entra-Anwendung auf Tenant-Ebene.

Dann lösche die Foundry-Ressource, falls du sie separat erstellt hast.

Weitere Ressourcen

  • Last updated on