Dodaj aplikację App Service jako narzędzie w Usłudze agenta Foundry (Python)

W tym samouczku dowiesz się, jak uwidocznić funkcjonalność aplikacji FastAPI za pomocą OpenAPI, dodać ją jako narzędzie do usługi Foundry Agent oraz wchodzić w interakcję z aplikacją przy użyciu języka naturalnego w środowisku agentów.

Jeśli aplikacja internetowa ma już przydatne funkcje, takie jak zakupy, rezerwacja hotelowa lub zarządzanie danymi, można łatwo udostępnić te możliwości agentowi sztucznej inteligencji w usłudze Agent usługi Foundry. Po prostu dodając schemat interfejsu OpenAPI do aplikacji, możesz umożliwić agentowi zrozumienie możliwości aplikacji i korzystanie z nich podczas odpowiadania na monity użytkowników. Oznacza to, że wszystko, co może zrobić twoja aplikacja, agent sztucznej inteligencji może również zrobić, przy minimalnym nakładzie pracy poza tworzeniem punktu końcowego interfejsu OpenAPI dla aplikacji. W tym samouczku zaczniesz od prostej aplikacji klasyfikacji restauracji. Na koniec będzie można zobaczyć oceny restauracji, a także tworzyć nowe restauracje i nowe recenzje z agentem za pośrednictwem konwersacyjnej sztucznej inteligencji.

Wymagania wstępne

W tym samouczku założono, że pracujesz z przykładem używanym w temacie Deploy a Python FastAPI web app with PostgreSQL in Azure (Wdrażanie aplikacji internetowej FastAPI w języku Python za pomocą bazy danych PostgreSQL na platformie Azure).

Otwórz co najmniej przykładową aplikację w usłudze GitHub Codespaces i wdróż aplikację, uruchamiając polecenie azd up.

Dodawanie funkcji interfejsu OpenAPI do aplikacji internetowej

FasAPI zawiera już funkcje interfejsu OpenAPI w ścieżce /openapi.jsondomyślnej . Wystarczy wprowadzić kilka zmian w istniejącym kodzie, aby umożliwić zdalne wywoływanie go przez agenta.

1. Otwórz plik src/fastapi_app/app.py i znajdź wiersz 24, w którym zadeklarowana jest aplikacja FastAPI. Zastąp app = FastAPI() ciąg następującym kodem:

   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}],
   )
   

   Ten kod dodaje metadane do schematu Interfejsu OpenAPI, na przykład title i description. Co najważniejsze, dodaje adres URL serwera punktu końcowego interfejsu API.

2. Otwórz plik src/fastapi_app/app.py, dodaj operation_id do / interfejsów API get i /details/{id} . Te dwa interfejsy API zwracają dokumenty HTML, które agent sztucznej inteligencji może analizować. W przypadku wszystkich innych interfejsów API dodaj include_in_schema=False parametr .

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

   Służy include_in_schema=False do wykluczania GET /createelementów , POST /addi POST /review/{id} , ponieważ są one częścią funkcji opartej na formularzach, natomiast agent sztucznej inteligencji musi przesyłać dane JSON.

3. Aby dodać restaurację i dodać funkcję przeglądu przy użyciu formatu JSON, dodaj następujący kod:

   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
   

   Ten kod pokazuje tylko interfejs API tworzenia dla zwięzłości i równoważności z istniejącą przykładową aplikacją. Jeśli chcesz, możesz również dodać inne interfejsy API, takie jak aktualizowanie i usuwanie.

4. Uruchom serwer deweloperów przykładowej aplikacji przy użyciu następujących poleceń:

   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. Wybierz pozycję Otwórz w przeglądarce.

6. Wyświetl schemat interfejsu OpenAPI, dodając /openapi.json go do adresu URL, który jest domyślną ścieżką używaną przez interfejs FastAPI do obsługi schematu.

7. W terminalu usługi Codespace wdróż zmiany, zatwierdzając zmiany (metodę GitHub Actions) lub uruchamiając azd up (metoda interfejsu wiersza polecenia dewelopera platformy Azure).

8. Po wdrożeniu zmian przejdź do https://<your-app's-url>/openapi.json i skopiuj schemat do późniejszego użycia.

Tworzenie agenta w rozwiązaniu Microsoft Foundry

1. W portalu Foundry w prawym górnym menu wybierz pozycję New Foundry.

2. Jeśli jest to twój pierwszy raz w nowym portalu Foundry, wybierz nazwę projektu i wybierz pozycję Utwórz nowy projekt.

3. Nadaj projektowi nazwę i wybierz pozycję Utwórz.

4. Wybierz pozycję Rozpocznij kompilowanie, a następnie pozycję Utwórz agenta.

5. Nadaj agentowi nazwę i wybierz pozycję Utwórz. Gdy agent jest gotowy, powinien zostać wyświetlony plac zabaw agenta.

   Zwróć uwagę na modele, których można użyć, i dostępnych regionów.

6. Na placu zabaw dla agentów rozwiń Narzędzia i wybierz Dodaj>Niestandardowe>narzędzie OpenAPI>Utwórz.

7. Nadaj narzędziu nazwę i opis. W polu schematu OpenAPI 3.0+ wklej skopiowany wcześniej schemat.

8. Wybierz pozycję Utwórz narzędzie.

9. Wybierz Zapisz.

Testowanie agenta

1. W obszarze Instrukcje podaj proste instrukcje, takie jak "Użyj narzędzia restaurantReview, aby ułatwić zarządzanie recenzjami restauracji".

2. Porozmawiaj z agentem z następującymi sugestiami:

   • "Pokaż mi listę recenzji restauracji."
   • "Utwórz restaurację. Użyj wyobraźni, aby uzyskać szczegółowe informacje.
   • "Nie podobało mi się jedzenie w tej restauracji. Utwórz recenzję 2 gwiazdki".

   

Najlepsze rozwiązania dotyczące zabezpieczeń

W przypadku uwidaczniania interfejsów API za pośrednictwem interfejsu OpenAPI w usłudze Azure App Service postępuj zgodnie z następującymi najlepszymi rozwiązaniami w zakresie zabezpieczeń:

• Uwierzytelnianie i autoryzacja: ochrona punktów końcowych interfejsu OpenAPI przy użyciu uwierzytelniania firmy Microsoft Entra. Aby uzyskać instrukcje krok po kroku, zobacz Zabezpieczanie punktów końcowych interfejsu OpenAPI dla usługi agenta Foundry. Możesz również chronić punkty końcowe za pomocą usługi Azure API Management przy użyciu identyfikatora Microsoft Entra ID i upewnić się, że tylko autoryzowani użytkownicy lub agenci mogą uzyskiwać dostęp do narzędzi.
• Weryfikowanie danych wejściowych: Zawsze weryfikuj dane przychodzące, aby zapobiec nieprawidłowym lub złośliwym danym wejściowym. W przypadku aplikacji języka Python użyj bibliotek, takich jak Pydantic , aby wymusić reguły walidacji danych z dedykowanymi modelami schematów żądań (takimi jak RestaurantCreate i ReviewCreate). Zapoznaj się z ich dokumentacją, aby uzyskać szczegółowe informacje na temat najlepszych rozwiązań i implementacji.
• Użyj protokołu HTTPS: Przykład opiera się na usłudze Azure App Service, która domyślnie wymusza protokół HTTPS i udostępnia bezpłatne certyfikaty TLS/SSL do szyfrowania danych przesyłanych.
• Ogranicz mechanizm CORS: Ogranicz udostępnianie zasobów między źródłami (CORS) tylko do zaufanych domen. Aby uzyskać więcej informacji, zobacz Włączanie mechanizmu CORS.
• Zastosuj ograniczanie szybkości: Użyj usługi API Management lub niestandardowego oprogramowania pośredniczącego, aby zapobiec nadużyciom i atakom typu "odmowa usługi".
• Ukryj poufne punkty końcowe: Unikaj uwidaczniania wewnętrznych lub administracyjnych interfejsów API w schemacie interfejsu OpenAPI.
• Przejrzyj schemat OpenAPI: Upewnij się, że schemat interfejsu OpenAPI nie wycieka poufnych informacji (takich jak wewnętrzne adresy URL, wpisy tajne lub szczegóły implementacji).
• Zachowaj zaktualizowane zależności: Regularnie aktualizuj pakiety NuGet i monitoruj je pod kątem biuletynów zabezpieczeń.
• Monitorowanie i rejestrowanie aktywności: Włącz rejestrowanie i monitoruj dostęp do wykrywania podejrzanych działań.
• Użyj tożsamości zarządzanych: Podczas wywoływania innych usług platformy Azure użyj tożsamości zarządzanych zamiast zakodowanych na stałe poświadczeń.

Aby uzyskać więcej informacji, zobacz Zabezpieczanie aplikacji usługi App Service i Najlepsze rozwiązania dotyczące zabezpieczeń interfejsu API REST.

Następny krok

Aplikacja App Service została teraz skonfigurowana do użycia jako narzędzie przez Servis Agentów Foundry, umożliwiając interakcję z interfejsami API aplikacji za pomocą języka naturalnego w środowisku testowym agentów. W tym miejscu możesz nadal dodawać funkcje do agenta w portalu Foundry, integrować je z własnymi aplikacjami przy użyciu zestawu Microsoft Foundry SDK lub interfejsu API REST albo wdrażać je w ramach większego rozwiązania. Agentów utworzonych w rozwiązaniu Microsoft Foundry można uruchamiać w chmurze, integrować z czatbotami lub osadzać w aplikacjach internetowych i mobilnych.

Aby wykonać następny krok i dowiedzieć się, jak uruchomić agenta bezpośrednio w usłudze Azure App Service, zobacz następujący samouczek:

Więcej zasobów

• Integrowanie sztucznej inteligencji z aplikacjami usługi Azure App Service
• Co to jest usługa agenta programu Foundry?