Foundry Agent Service (Python) で App Service アプリをツールとして追加する

このチュートリアルでは、OpenAPI を使用して FastAPI アプリの機能を公開し、Foundry Agent Service にツールとして追加し、エージェントプレイグラウンドで自然言語を使用してアプリと対話する方法について説明します。

Web アプリケーションにショッピング、ホテル予約、データ管理などの便利な機能が既にある場合は、Foundry Agent Service の AI エージェントでそれらの機能を簡単に使用できます。 OpenAPI スキーマをアプリに追加するだけで、エージェントがユーザーのプロンプトに応答したときにアプリの機能を理解して使用できるようになります。 つまり、アプリでできることは何でも、AI エージェントでも実行でき、アプリの OpenAPI エンドポイントを作成する以外の労力は最小限です。 このチュートリアルでは、簡単なレストラン評価アプリから始めます。 最終的には、会話型 AI を使用して、レストランの評価を確認したり、エージェントで新しいレストランや新しいレビューを作成したりできます。

[前提条件]

このチュートリアルでは、「Azure で PostgreSQL を使用して Python FastAPI Web アプリをデプロイする」で使用するサンプルを使用していることを前提としています。

少なくとも、GitHub Codespaces で サンプル アプリケーション を開き、 azd upを実行してアプリをデプロイします。

で開く

Web アプリに OpenAPI 機能を追加する

FasAPI には、既定のパス /openapi.jsonにある OpenAPI 機能が既に含まれています。 エージェントがリモートで呼び出し可能にするには、既存のコードにいくつかの変更を加える必要があります。

1. src/fastapi_app/app.py を開き、FastAPI アプリが宣言されている 24 行目を見つけます。 app = FastAPI()を次のコードに置き換えます。

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

   このコードは、 title や descriptionなどのメタデータを OpenAPI スキーマに追加します。 最も重要なのは、API エンドポイントのサーバー URL を追加することです。

2. src/fastapi_app/app.py を開き、operation_idに/を追加し、GET API を/details/{id}します。 これら 2 つの API は、AI エージェントが解析できる HTML ドキュメントを返します。 その他のすべての API に対して、 include_in_schema=False パラメーターを追加します。

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

   include_in_schema=Falseを使用して、フォーム ベースの機能の一部であるため、GET /create、POST /add、およびPOST /review/{id}を除外します。一方、AI エージェントは JSON データを送信する必要があります。

3. JSON を使用してレストランの追加機能を追加し、レビュー機能を追加するには、次のコードを追加します。

   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
   

   このコードでは、簡潔で、既存のサンプル アプリケーションと同等の create API のみを示します。 必要に応じて、更新や削除などの他の API を追加することもできます。

4. 次のコマンドを使用して、サンプル アプリの開発サーバーを起動します。

   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. [ ブラウザーで開く] を選択します。

6. URL に /openapi.json を追加して OpenAPI スキーマを表示します。これは、FastAPI がスキーマを提供するために使用する既定のパスです。

7. codespace ターミナルに戻り、変更をコミットして変更をデプロイするか (GitHub Actions メソッド)、または azd up (Azure Developer CLI メソッド) を実行します。

8. 変更がデプロイされたら、 https://<your-app's-url>/openapi.json に移動し、後で使用できるようにスキーマをコピーします。

Microsoft Foundry でエージェントを作成する

1. Foundry ポータルの右上のメニューで、[New Foundry] を選択します。

2. 新しい Foundry ポータルでこれが初めての場合は、プロジェクト名を選択し、[ 新しいプロジェクトの作成] を選択します。

3. プロジェクトに名前を付け、[ 作成] を選択します。

4. [ ビルドの開始]、[ エージェントの作成] の順に選択します。

5. エージェントに名前を付け、[ 作成] を選択します。 エージェントの準備ができたら、エージェントのプレイグラウンドが表示されます。

   使用できるモデルと使用可能なリージョンに注意してください。

6. エージェントのプレイグラウンドで、[ ツール ] を展開し、[ 追加>Custom>OpenAPI ツール>Create を選択します。

7. ツールに名前と説明を付けます。 OpenAPI 3.0 以降のスキーマ ボックスに、先ほどコピーしたスキーマを貼り付けます。

8. [ 作成ツール] を選択します。

9. 保存 を選択します。

エージェントをテストする

1. [手順] で、"restaurantReview ツールを使用してレストランのレビューを管理してください" などの簡単な手順を説明します。

2. 次のプロンプトの提案を使用してエージェントとチャットします。

   • 「レストランのレビューの一覧を見せて」
   • "レストランを作成します。 あなたの想像力を使って詳細を見てください。
   • 「このレストランの食べ物が気に入らなかった。 2 つ星のレビューを作成してください。"

   

セキュリティのベスト プラクティス

Azure App Service で OpenAPI 経由で API を公開する場合は、次のセキュリティのベスト プラクティスに従います。

• 認証と承認: Microsoft Entra 認証を使用して OpenAPI エンドポイントを保護します。 詳細な手順については、「 Foundry Agent Service の OpenAPI エンドポイントをセキュリティで保護する」を参照してください。 また、 Microsoft Entra ID を使用して Azure API Management の背後にあるエンドポイントを保護し、承認されたユーザーまたはエージェントのみがツールにアクセスできるようにすることもできます。
• 入力データを検証します。 無効または悪意のある入力を防ぐために、常に受信データを検証します。 Python アプリの場合は、 Pydantic などのライブラリを使用して、専用の要求スキーマ モデル (RestaurantCreate や ReviewCreate など) でデータ検証規則を適用します。 ベスト プラクティスと実装の詳細については、ドキュメントを参照してください。
• HTTPS を使用する: このサンプルは、既定で HTTPS を適用し、転送中のデータを暗号化するための無料の TLS/SSL 証明書を提供する Azure App Service に依存しています。
• CORS の制限: クロスオリジン リソース共有 (CORS) を信頼されたドメインのみに制限します。 詳細については、「 CORS を有効にする」を参照してください。
• レート制限の適用:API Management またはカスタム ミドルウェアを使用して、不正使用やサービス拒否攻撃を防ぎます。
• 機密性の高いエンドポイントを非表示にする: OpenAPI スキーマで内部 API または管理者 API を公開しないようにします。
• OpenAPI スキーマを確認します。 OpenAPI スキーマが機密情報 (内部 URL、シークレット、実装の詳細など) を漏らさないようにします。
• 依存関係を更新したままにする: NuGet パッケージを定期的に更新し、セキュリティ アドバイザリを監視します。
• アクティビティの監視とログ記録: ログ記録を有効にし、アクセスを監視して疑わしいアクティビティを検出します。
• マネージド ID を使用する: 他の Azure サービスを呼び出す場合は、ハードコーディングされた資格情報の代わりにマネージド ID を使用します。

詳細については、 App Service アプリのセキュリティ保護 と REST API セキュリティのベスト プラクティスに関する説明を参照してください。

次のステップ

これで、App Service アプリを Foundry Agent Service のツールとして使用し、エージェントのプレイグラウンドで自然言語を使用してアプリの API と対話できるようになりました。 ここから、Foundry ポータルで引き続きエージェントに機能を追加したり、Microsoft Foundry SDK または REST API を使用して独自のアプリケーションに統合したり、大規模なソリューションの一部としてデプロイしたりできます。 Microsoft Foundry で作成されたエージェントは、クラウドで実行したり、チャットボットに統合したり、Web アプリやモバイル アプリに埋め込んだりすることができます。

次の手順を実行し、Azure App Service 内で直接エージェントを実行する方法については、次のチュートリアルを参照してください。

その他のリソース

• AI を Azure App Service アプリケーションに統合する
• Foundry Agent Service とは