Hinzufügen einer App Service-App als Tool im Foundry Agent Service (Python)

In diesem Lernprogramm erfahren Sie, wie Sie die Funktionen einer FastAPI-App über OpenAPI verfügbar machen, sie als Tool zum Foundry Agent Service hinzufügen und mit Ihrer App mit natürlicher Sprache im Agents-Playground interagieren.

Wenn Ihre Webanwendung bereits nützliche Funktionen wie Shopping, Hotelbuchung oder Datenverwaltung aufweist, ist es einfach, diese Funktionen einem KI-Agenten im Foundry Agent Service zur Verfügung zu stellen. Indem Sie Ihrer App einfach ein OpenAPI-Schema hinzufügen, ermöglichen Sie es dem Agenten, die Funktionalitäten Ihrer App zu verstehen und zu nutzen, wenn er auf die Benutzenden reagiert. Das bedeutet, dass alles, was Ihre App kann, auch Ihr KI-Agent kann, und zwar mit minimalem Aufwand, der über das Erstellen eines OpenAPI-Endpunkts für Ihre App hinausgeht. In diesem Tutorial beginnen Sie mit einer einfachen App für Restaurantbewertungen. Am Ende werden Sie in der Lage sein, Restaurantbewertungen zu sehen sowie neue Restaurants und neue Bewertungen mit einem Agent durch dialogorientierte KI zu erstellen.

• Fügen Sie Ihrer Web-App OpenAPI-Funktionen hinzu.
• Stellen Sie sicher, dass das OpenAPI-Schema mit dem Foundry Agent Service kompatibel ist.
• Registrieren Sie Ihre App als OpenAPI-Tool im Foundry Agent Service.
• Testen Sie Ihren Agent im Agent-Playground.

Voraussetzungen

In dieser Anleitung wird davon ausgegangen, dass Sie mit dem Beispiel aus Bereitstellen einer Python FastAPI Web-App mit PostgreSQL in Azure arbeiten.

Öffnen Sie zumindest die Beispielanwendung in GitHub Codespaces und stellen Sie die App bereit, indem Sie azd up ausführen.

Hinzufügen von OpenAPI-Funktionen zu Ihrer Web-App

FasAPI enthält bereits OpenAPI-Funktionalität unter dem Standardpfad /openapi.json. Sie müssen nur ein paar Änderungen am bestehenden Code vornehmen, damit er von einem Agent remote aufgerufen werden kann.

1. Öffnen Sie src/fastapi_app/app.py und suchen Sie die Zeile 24, in der die FastAPI App deklariert wird. Ersetzen Sie den Code app = FastAPI() durch folgenden Code:

   if os.getenv("WEBSITE_HOSTNAME"):
       server_url = f"https://{os.getenv('WEBSITE_HOSTNAME')}"
   else:
       server_url = "http://localhost:8000"
   app = FastAPI(
       title="Restaurant Review API",
       version="1.0.0",
       description="Can show restaurant ratings HTML and add new restaurants and reviews.",
       servers=[{"url": server_url}],
   )
   

   Dieser Code fügt dem OpenAPI-Schema Metadaten hinzu, wie z. B. title und description. Vor allem aber fügt er die Server-URL des API-Endpunkts hinzu.

2. Öffnen Sie src/fastapi_app/app.py, fügen Sie operation_id zu den / und /details/{id} GET APIs hinzu. Diese beiden APIs geben HTML-Dokumente zurück, die ein KI-Agent auswerten kann. Für alle anderen APIs fügen Sie den Parameter include_in_schema=False hinzu.

   @app.get("/", response_class=HTMLResponse, operation_id="getRestaurantsWithRatingsHtml")
       ...    
   
   @app.get("/create", response_class=HTMLResponse, include_in_schema=False)
       ...    
   
   @app.post("/add", response_class=RedirectResponse, include_in_schema=False)
       ...
   
   @app.get("/details/{id}", response_class=HTMLResponse, operation_id="getRestaurantDetails")
       ...    
   
   @app.post("/review/{id}", response_class=RedirectResponse, include_in_schema=False)
       ...
   

   Sie verwenden include_in_schema=False, um GET /create, POST /add und POST /review/{id} auszuschließen, da diese Elemente Teil der formularbasierten Funktionalität sind, während der KI-Agent JSON-Daten senden muss.

3. Um die Funktionen Restaurant hinzufügen und Rezension hinzufügen mithilfe von JSON hinzuzufügen, fügen Sie den folgenden Code ein:

   from typing import Optional
   from fastapi import Body, HTTPException
   
   @app.post("/api/restaurants", response_model=Restaurant, status_code=status.HTTP_201_CREATED, operation_id="createRestaurant")
   async def create_restaurant_json(
       name: str = Body(...),
       street_address: str = Body(...),
       description: str = Body(...),
       session: Session = Depends(get_db_session),
   ):
       restaurant = Restaurant(name=name, street_address=street_address, description=description)
       session.add(restaurant)
       session.commit()
       session.refresh(restaurant)
       return restaurant
   
   
   @app.post("/api/restaurants/{id}/reviews", response_model=Review, status_code=status.HTTP_201_CREATED,operation_id="createReview")
   async def create_review_for_restaurant_json(
       id: int,
       user_name: str = Body(...),
       rating: Optional[int] = Body(None),
       review_text: str = Body(...),
       session: Session = Depends(get_db_session),
   ):
       if not session.get(Restaurant, id):
           raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Restaurant not found")
   
       review = Review(
           restaurant=id, user_name=user_name, rating=rating, review_text=review_text, review_date=datetime.now()
       )
       session.add(review)
       session.commit()
       session.refresh(review)
       return review
   

   Dieser Code zeigt der Kürze halber und aus Gründen der Parität mit der vorhandenen Beispielanwendung nur die erstellte API. Wenn Sie möchten, können Sie auch andere APIs hinzufügen, wie z. B. aktualisieren und löschen.

4. Starten Sie den Entwicklungsserver für die Beispiel App mit den folgenden Befehlen:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r src/requirements.txt
   pip install -e src
   python3 src/fastapi_app/seed_data.py
   python3 -m uvicorn fastapi_app:app --reload --port=8000
   

5. Klicken Sie auf In Browser öffnen.

6. Zeigen Sie das OpenAPI-Schema an, indem Sie /openapi.json zur URL hinzufügen. Dies ist der Standardpfad, der von FastAPI verwendet wird, um das Schema bereitzustellen.

7. Stellen Sie ihre Änderungen wieder im Codespace-Terminal bereit, indem Sie Änderungen übernehmen (GitHub Actions-Methode) oder azd up ausführen (Azure Developer CLI-Methode).

8. Sobald Ihre Änderungen bereitgestellt sind, navigieren Sie zu https://<your-app's-url>/openapi.json und kopieren Sie das Schema für später.

Erstellen eines Agents in Microsoft Foundry

Hinweis

Diese Schritte verwenden das neue Foundry-Portal.

1. Wählen Sie im Findry-Portal im oberen rechten Menü die Option "Neue Gießerei" aus.

2. Wenn Dies Ihr erstes Mal im neuen Foundry-Portal ist, wählen Sie den Projektnamen und dann "Neues Projekt erstellen" aus.

3. Geben Sie Ihrem Projekt einen Namen, und wählen Sie "Erstellen" aus.

4. Wählen Sie "Erstellen beginnen" und dann "Agent erstellen" aus.

5. Geben Sie Ihrem Agent einen Namen, und wählen Sie "Erstellen" aus. Wenn der Agent bereit ist, sollten Sie den Agent-Playground sehen.

   Beachten Sie die Modelle, die Sie verwenden können, und die verfügbaren Regionen.

6. Erweitern Sie im Agent-Playground Tools und wählen Sie Hinzufügen>Benutzerdefiniertes>OpenAPI-Tool>Erstellen aus.

7. Geben Sie dem Tool einen Namen und eine Beschreibung. Fügen Sie im Feld "OpenAPI 3.0+" das Zuvor kopierte Schema ein.

8. Wählen Sie "Tool erstellen" aus.

9. Wählen Sie Speichern aus.

Tipp

In diesem Lernprogramm ist das OpenAPI-Tool so konfiguriert, dass Ihre App anonym ohne Authentifizierung aufgerufen wird. Für Produktionsszenarien sollten Sie das Tool mit verwalteter Identitätsauthentifizierung sichern. Schrittweise Anleitungen finden Sie unter Secure OpenAPI-Endpunkte für Foundry Agent Service.

Testen des Agents

1. Geben Sie in Den Anweisungen einige einfache Anweisungen, z. B. "Bitte verwenden Sie das RestaurantReview-Tool, um Restaurantbewertungen zu verwalten."

2. Chatten Sie mit dem Agent mit den folgenden Prompt-Empfehlungen:

   • „Zeig mir die Liste der Restaurantbewertungen.“
   • "Erstelle ein Restaurant. Verwenden deine Phantasie für die Details.
   • Mir hat das Essen in diesem Restaurant nicht geschmeckt. Bitte erstelle eine 2-Sterne-Bewertung."

   

Bewährte Sicherheitsmethoden

Wenn Sie APIs über OpenAPI in Azure App Service zur Verfügung stellen, sollten Sie die folgenden bewährten Verfahren für die Sicherheit beachten:

• Authentifizierung und Autorisierung: Schützen Sie Ihre OpenAPI-Endpunkte mit der Microsoft Entra-Authentifizierung. Schrittweise Anleitungen finden Sie unter Secure OpenAPI-Endpunkte für Foundry Agent Service. Sie können Ihre Endpunkte auch hinter Azure API Management mit Microsoft Entra ID schützen und sicherstellen, dass nur autorisierte Benutzer oder Agents auf die Tools zugreifen können.
• Validieren Sie Eingabedaten: Validieren Sie eingehende Daten immer, um ungültige oder schädliche Eingaben zu verhindern. Verwenden Sie für Python Apps Bibliotheken wie Pydantic, um Datenvalidierungsregeln mit speziellen Anfrage-Schema-Modellen (wie z. B. RestaurantCreate und ReviewCreate) zu erzwingen. Bewährte Verfahren und Details zur Implementierung finden Sie in der Dokumentation dieser Bibliotheken.
• Verwenden Sie HTTPS: Das Beispiel basiert auf Azure App Service, der standardmäßig HTTPS erzwingt und freie TLS/SSL-Zertifikate zur Verschlüsselung von Daten bei der Übertragung bereitstellt.
• Beschränken Sie CORS: Beschränken Sie die herkunftsübergreifende gemeinsame Nutzung von Ressourcen (CORS) nur auf vertrauenswürdige Domänen. Weitere Informationen finden Sie weiter unten unter Aktivieren von CORS.
• Ratenbegrenzung anwenden: Verwenden Sie API Management oder angepasste Middleware, um Missbrauch und Denial-of-Service-Angriffe zu verhindern.
• Verstecken Sie vertrauliche Endpunkte: Vermeiden Sie es, interne oder Admin-APIs in Ihrem OpenAPI-Schema zur Verfügung zu stellen.
• Überprüfen Sie Ihr OpenAPI-Schema: Stellen Sie sicher, dass Ihr OpenAPI-Schema keine vertraulichen Informationen preisgibt (wie z. B. interne URLs, Secrets oder Details zur Implementierung).
• Aktualisieren Sie Abhängigkeiten: Aktualisieren Sie regelmäßig NuGet Pakete und überwachen Sie diese auf Sicherheitshinweise.
• Überwachen und protokollieren Sie Aktivitäten: Aktivieren Sie die Protokollierung und überwachen Sie den Zugriff, um verdächtige Aktivitäten zu erkennen.
• Verwenden Sie verwaltete Identitäten: Wenn Sie andere Azure Services aufrufen, verwenden Sie verwaltete Identitäten anstelle von hart kodierten Anmeldeinformationen.

Weitere Informationen finden Sie unter Sichern der App Service App und Bewährte Verfahren für REST-API-Sicherheit.

Nächster Schritt

Sie haben Ihre App Service-App jetzt so aktiviert, dass sie als Tool vom Foundry Agent Service genutzt werden kann und über natürliche Sprache mit den APIs Ihrer App im Agents-Playground interagiert. Von hier aus können Sie Ihrem Agent weiterhin Features im Foundry-Portal hinzufügen, sie mithilfe des Microsoft Foundry SDK oder der REST-API in Ihre eigenen Anwendungen integrieren oder als Teil einer größeren Lösung bereitstellen. In Microsoft Foundry erstellte Agents können in der Cloud ausgeführt, in Chatbots integriert oder in Web- und mobile Apps eingebettet werden.

Wenn Sie den nächsten Schritt machen und lernen möchten, wie Sie Ihren Agent direkt im Azure App Service ausführen, lesen Sie das folgende Tutorial:

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

Weitere Ressourcen

• Integrieren von KI in Ihre Azure App Service Anwendungen
• Was ist Foundry Agent Service?