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

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

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

OpenAPI ツールを使用してアクションを実行する会話の途中にあるエージェントのプレイグラウンドを示すスクリーンショット。

Web アプリに OpenAPI 機能を追加します。
OpenAPI スキーマが Foundry Agent Service と互換性があることを確認します。
Foundry Agent Service でアプリを OpenAPI ツールとして登録します。
エージェントのプレイグラウンドでエージェントをテストします。

[前提条件]

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

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

で開く

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

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

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 を追加することです。
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 データを送信する必要があります。

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 を追加することもできます。

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

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

[ ブラウザーで開く] を選択します。
URL に /openapi.json を追加して OpenAPI スキーマを表示します。これは、FastAPI がスキーマを提供するために使用する既定のパスです。
codespace ターミナルに戻り、変更をコミットして変更をデプロイするか (GitHub Actions メソッド)、または azd up (Azure Developer CLI メソッド) を実行します。
変更がデプロイされたら、 https://<your-app's-url>/openapi.json に移動し、後で使用できるようにスキーマをコピーします。

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

注

これらの手順では、新しい Foundry ポータルを使用します。

Foundry ポータルの右上のメニューで、[New Foundry] を選択します。
新しい Foundry ポータルでこれが初めての場合は、プロジェクト名を選択し、[ 新しいプロジェクトの作成] を選択します。
プロジェクトに名前を付け、[ 作成] を選択します。
[ ビルドの開始]、[ エージェントの作成] の順に選択します。
エージェントに名前を付け、[ 作成] を選択します。エージェントの準備ができたら、エージェントのプレイグラウンドが表示されます。

使用できるモデルと使用可能なリージョンに注意してください。
エージェントのプレイグラウンドで、[ ツール ] を展開し、[ 追加>Custom>OpenAPI ツール>Create を選択します。
ツールに名前と説明を付けます。 OpenAPI 3.0 以降のスキーマ ボックスに、先ほどコピーしたスキーマを貼り付けます。
[ 作成ツール] を選択します。
保存を選択します。

ヒント

このチュートリアルでは、認証なしでアプリを匿名で呼び出すように OpenAPI ツールを構成します。運用シナリオでは、マネージド ID 認証を使用してツールをセキュリティで保護する必要があります。詳細な手順については、「 Foundry Agent Service の OpenAPI エンドポイントをセキュリティで保護する」を参照してください。

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

[手順] で、"restaurantReview ツールを使用してレストランのレビューを管理してください" などの簡単な手順を説明します。
次のプロンプトの提案を使用してエージェントとチャットします。
- 「レストランのレビューの一覧を見せて」
- "レストランを作成します。あなたの想像力を使って詳細を見てください。
- 「このレストランの食べ物が気に入らなかった。 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 内で直接エージェントを実行する方法については、次のチュートリアルを参照してください。

チュートリアル: LangGraph または Foundry Agent Service (Python) を使用して Azure App Service でエージェント Web アプリを構築する

その他のリソース

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-12-16

次の方法で共有

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

[前提条件]

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

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

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

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

次のステップ

その他のリソース

フィードバック

その他のリソース

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