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

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

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

[前提条件]

このチュートリアルでは、「 チュートリアル: Azure App Service on Linux および Azure Cosmos DB を使用して Java Spring Boot Web アプリを構築する」で使用するサンプルを使用していることを前提としています。

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

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

1. コードスペースで、 pom.xml を開き、次の依存関係を追加します。

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
       <version>2.6.0</version>
   </dependency>
   

2. src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java を開き、次のインポートを追加します。

   import io.swagger.v3.oas.annotations.Operation;
   import io.swagger.v3.oas.annotations.tags.Tag;
   

   TodoListController クラスは@RestControllerを実装するため、いくつかの注釈を追加するだけで、OpenAPI と互換性があります。 さらに、API を Foundry Agent Service と互換性のあるものにするには、operationId注釈に @Operation プロパティを指定する必要があります (OpenAPI 指定ツールで Foundry Agent Service を使用する方法: 前提条件を参照)。

3. 次のスニペットに示すように、クラス宣言を見つけて、 @Tag 注釈を追加します。

   @RestController
   @Tag(name = "Todo List", description = "Todo List management APIs")
   public class TodoListController {
   

4. 次のスニペットに示すように、getTodoItem メソッド宣言を見つけて、@Operationとdescriptionを使用してoperationId注釈を追加します。

   @Operation(description = "Returns a single todo item", operationId = "getTodoItem")
   @GetMapping(path = "/api/todolist/{index}", produces = {MediaType.APPLICATION_JSON_VALUE})
   public TodoItem getTodoItem(@PathVariable("index") String index) {
   

5. 次のスニペットに示すように、getAllTodoItems メソッド宣言を見つけて、@Operationとdescriptionを使用してoperationId注釈を追加します。

   @Operation(description = "Returns a list of all todo items", operationId = "getAllTodoItems")
   @GetMapping(path = "/api/todolist", produces = {MediaType.APPLICATION_JSON_VALUE})
   public List<TodoItem> getAllTodoItems() {
   

6. 次のスニペットに示すように、addNewTodoItem メソッド宣言を見つけて、@Operationとdescriptionを使用してoperationId注釈を追加します。

   @Operation(description = "Creates a new todo item", operationId = "addNewTodoItem")
   @PostMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
   public String addNewTodoItem(@RequestBody TodoItem item) {
   

7. 次のスニペットに示すように、updateTodoItem メソッド宣言を見つけて、@Operationとdescriptionを使用してoperationId注釈を追加します。

   @Operation(description = "Updates an existing todo item", operationId = "updateTodoItem")
   @PutMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
   public String updateTodoItem(@RequestBody TodoItem item) {
   

8. 次のスニペットに示すように、deleteTodoItem メソッド宣言を見つけて、@Operationとdescriptionを使用してoperationId注釈を追加します。

   @Operation(description = "Deletes a todo item by ID", operationId = "deleteTodoItem")
   @DeleteMapping("/api/todolist/{id}")
   public String deleteTodoItem(@PathVariable("id") String id) {
   

   この最小限の構成では、 springdoc-openapi に記載されている次の設定が提供されます。

   • /swagger-ui.html の Swagger UI。
   • /v3/api-docsでの OpenAPI 仕様。

9. codespace ターミナルで、 mvn spring-boot:runを使用してアプリケーションを実行します。

10. [ブラウザーで開く] を選択します。

11. URL に /swagger-ui.html を追加して、Swagger UI に移動します。

12. Swagger UI で試して、API 操作が機能することを確認します。

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

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

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

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

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

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

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

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

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

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

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

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

9. 保存 を選択します。

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

1. [手順] で、"todosApp ツールを使用してタスクを管理してください" などの簡単な手順を説明します。

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

   • すべてのタスクを表示します。
   • 「3つのレタスジョークを思い付く」というタスクを作成します。
   • それを「3つのノックノックジョークを考えてください」に変えてください。

   

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

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

• 認証と承認: Microsoft Entra 認証を使用して OpenAPI エンドポイントを保護します。 詳細な手順については、「 Foundry Agent Service の OpenAPI エンドポイントをセキュリティで保護する」を参照してください。 また、 Microsoft Entra ID を使用して Azure API Management の背後にあるエンドポイントを保護し、承認されたユーザーまたはエージェントのみがツールにアクセスできるようにすることもできます。
• 入力データの検証とサニタイズ: このチュートリアルのコード例では、わかりやすくするために入力の検証とサニタイズを省略しています。 運用環境のシナリオでは、アプリケーションを保護するために、常に適切な検証とサニタイズを実装します。 Spring については、 Spring: フォーム入力の検証に関するページを参照してください。
• 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 アプリやモバイル アプリに埋め込んだりすることができます。

その他のリソース

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