チュートリアル: Microsoft セマンティック カーネルまたは Foundry エージェント サービス (Spring Boot) を使用して Azure App Service でエージェント Web アプリを構築する

セマンティック カーネル エージェントは、ユーザーが新しいブラウザー セッションで最初のプロンプトを入力すると、 src/main/java/com/example/crudtaskswithagent/controller/AgentController.java で初期化されます。

初期化コードは、 SemanticKernelAgentService コンストラクター ( src/main/java/com/example/crudtaskswithagent/service/SemanticKernelAgentService.java 内) にあります。 初期化コードでは、次の処理が行われます。

• チャット補完用のカーネルを作成します。
• CRUD アプリケーションの機能をカプセル化するカーネル プラグインを追加します ( src/main/java/com/example/crudtaskswithagent/plugin/TaskCrudPlugin.java)。 プラグインの興味深い部分は、カーネルがプラグインをインテリジェントに呼び出すのに役立つメソッド宣言とDefineKernelFunctionとdescriptionパラメーターのreturnType注釈です。
• チャット完了エージェントを作成し、AI モデルが関数 (FunctionChoiceBehavior.auto(true)) を自動的に呼び出すように構成します。
• チャット履歴を自動的に管理するエージェント スレッドを作成します。

        // Create OpenAI client
        OpenAIAsyncClient openAIClient = new OpenAIClientBuilder()
                .endpoint(endpoint)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildAsyncClient();
        
        // Create chat completion service
        OpenAIChatCompletion chatCompletion = OpenAIChatCompletion.builder()
                .withOpenAIAsyncClient(openAIClient)
                .withModelId(deployment)
                .build();
        
        // Create kernel plugin from the task plugin
        KernelPlugin kernelPlugin = KernelPluginFactory.createFromObject(taskCrudPlugin, "TaskPlugin");
        
        // Create kernel with TaskCrudPlugin and chat completion service
        Kernel kernel = Kernel.builder()
                .withAIService(OpenAIChatCompletion.class, chatCompletion)
                .withPlugin(kernelPlugin)
                .build();
        
        // Use automatic function calling
        InvocationContext invocationContext = InvocationContext.builder()
            .withFunctionChoiceBehavior(FunctionChoiceBehavior.auto(true))
            .build();

        // Create ChatCompletionAgent
        configuredAgent = ChatCompletionAgent.builder()
                .withKernel(kernel)
                .withName("TaskAgent")
                .withInvocationContext(invocationContext)
                .withInstructions(
                    "You are an agent that manages tasks using CRUD operations. " +
                    "Use the TaskCrudPlugin functions to create, read, update, and delete tasks. " +
                    "Always call the appropriate plugin function for any task management request. " +
                    "Don't try to handle any requests that are not related to task management."
                )
                .build();
        
    } catch (Exception e) {
        logger.error("Error initializing SemanticKernelAgentService: {}", e.getMessage(), e);
    }
}

this.agent = configuredAgent;

// Initialize thread for this instance
this.thread = ChatHistoryAgentThread.builder().build();

プロンプトが受信されるたびに、サーバー コードは ChatCompletionAgent.invokeAsync() を使用して、ユーザー プロンプトとエージェント スレッドを使用してエージェントを呼び出します。 エージェント スレッドはチャット履歴を追跡します。

// Use the agent to process the message with automatic function calling
return agent.invokeAsync(userMessageContent, thread)
        .<String>map(responses -> {
            
            if (responses != null && !responses.isEmpty()) {
                // Process all responses and concatenate them
                StringBuilder combinedResult = new StringBuilder();
                
                for (int i = 0; i < responses.size(); i++) {
                    var response = responses.get(i);
                    
                    // Update thread with the last response thread (as per Microsoft docs)
                    if (i == responses.size() - 1) {
                        var responseThread = response.getThread();
                        if (responseThread instanceof ChatHistoryAgentThread) {
                            this.thread = (ChatHistoryAgentThread) responseThread;
                        }
                    }
                    
                    // Get response content
                    ChatMessageContent<?> content = response.getMessage();
                    String responseContent = content != null ? content.getContent() : "";
                    
                    if (!responseContent.isEmpty()) {
                        if (combinedResult.length() > 0) {
                            combinedResult.append("\n\n"); // Separate multiple responses
                        }
                        combinedResult.append(responseContent);
                    }
                }
                
                String result = combinedResult.toString();
                if (result.isEmpty()) {
                    result = "No content returned from agent.";
                }
                return result;
            } else {
                return "I'm sorry, I couldn't process your request. Please try again.";
            }
        })
        .onErrorResume(throwable -> {
            logger.error("Error in processMessage: {}", throwable.getMessage(), throwable);
            return Mono.just("Error processing message: " + throwable.getMessage());
        });

Foundry エージェントは、ユーザーが新しいブラウザー セッションで最初のプロンプトを入力すると、 src/main/java/com/example/crudtaskswithagent/controller/AgentController.java で初期化されます。

初期化コードは、 FoundryAgentService コンストラクター ( src/main/java/com/example/crudtaskswithagent/service/FoundryAgentService.java 内) にあります。 初期化コードでは、次の処理が行われます。

• エンドポイントと資格情報を使用して AgentsClientBuilder を作成します。
• 特殊な非同期クライアント ( ConversationsAsyncClient と ResponsesAsyncClient) を構築します。
• エージェントを名前で参照します (Foundry ポータルで構成)。
• セッションの会話を作成します。

// Configure Foundry client with endpoint and credentials
AgentsClientBuilder builder = new AgentsClientBuilder()
        .endpoint(endpoint)
        .serviceVersion(AgentsServiceVersion.V2025_11_15_PREVIEW)
        .credential(new DefaultAzureCredentialBuilder().build());

// Build specialized async clients for conversations and responses
this.conversationsClient = builder.buildConversationsAsyncClient();
this.responsesClient = builder.buildResponsesAsyncClient();

// Reference the agent by name (configured in Foundry portal)
this.agentReference = new AgentReference(agentName);

// Create a conversation for this session
this.conversationId = conversationsClient.getConversationServiceAsync()
        .create()
        .get() // Blocking call - must be on boundedElastic thread
        .id();

この初期化コードでは、通常は Foundry ポータルでエージェントをビルドするため、エージェントの機能は定義されません。 シナリオ例の一部として、「 Foundry Agent Service (Spring Boot) で App Service アプリをツールとして追加する (Spring Boot)」に示されている OpenAPI パターンに従い、その CRUD 機能を OpenAPI エンドポイントとして使用できるようにします。 これにより、後で呼び出し可能なツールとしてエージェントに追加できます。

OpenAPI 注釈は、 TaskController クラスで定義されます。 たとえば、"GET /api/tasks" ルートでは、operationIdの要求に応じて、@Operation注釈を使用してを定義し、エージェントが API を呼び出す方法を決定するのにsummaryとdescriptionを支援します。

@GetMapping
@Operation(
    summary = "Get all tasks",
    description = "Retrieves all tasks from the database",
    operationId = "getAllTasks"
)
@ApiResponse(responseCode = "200", description = "List of tasks")
public Flux<TaskItem> getAllTasks() {
    return taskRepository.findAllOrderById();
}

プロンプトを受信するたびに、サーバー コードは responsesClient.createWithAgentConversation() を使用して Foundry エージェントにメッセージを送信し、応答を取得します。 会話 ID は、チャット履歴を追跡します。

// Send message to agent and get response
return responsesClient
    .createWithAgentConversation(agentReference, conversationId, paramsBuilder)
    .map(response -> {
        // Extract text from response - find the message item in output array
        return response.output().stream()
            .filter(item -> item.message().isPresent())
            .findFirst()
            .flatMap(item -> item.message())
            .map(msg -> !msg.content().isEmpty() && msg.content().get(0).isOutputText()
                ? msg.content().get(0).asOutputText().text()
                : "I received your message but couldn't generate a response.")
            .orElse("I received your message but couldn't generate a response.");
    })
    .timeout(Duration.ofSeconds(60))
    .onErrorResume(throwable -> {
        logger.error("Error processing message: {}", throwable.getMessage(), throwable);
        return Mono.just("Sorry, I encountered an error processing your request: " + throwable.getMessage());
    });

1. Foundry ポータルで、上部の [New Foundry] ラジオ ボタンがアクティブに設定されていることを確認し、プロジェクトを作成します。

2. 任意のモデルをデプロイします ( Microsoft Foundry クイック スタート: リソースの作成を参照)。

3. モデルプレイグラウンドの上部から、モデル名をコピーします。

4. Azure OpenAI エンドポイントを取得する最も簡単な方法は、まだクラシック ポータルから行う方法です。 New Foundry のラジオ ボタンと Azure OpenAI を順に選択し、後で使用するために Azure OpenAI エンドポイント の URL をコピーします。

   

1. Foundry ポータルで、上部の [New Foundry] ラジオ ボタンがアクティブに設定されていることを確認し、プロジェクトを作成します。

2. ホームページで、後で使うために Project エンドポイント をコピーします。

3. [ ビルドの開始]>[エージェントの作成 ]を選択し、プロンプトに従います。

4. 新しいエージェントのプレイグラウンドで、ツール>追加>Custom>OpenAPI ツール> を選択して、Web アプリを呼び出す OpenAPI ツールを作成します。 [セットアップ] ウィンドウで、OpenAPI 仕様ツールを使用してアクションを追加します。 デプロイされた Web アプリと 匿名 認証から取得した OpenAPI スキーマを使用します。 詳細な手順については、「 OpenAPI 仕様ツールの使用方法」を参照してください。

   アプリケーション コードは、エージェントが必要とするサーバーの url と operationIdを含むように既に構成されています。 詳細については、「 OpenAPI 仕様への接続」を参照してください。

5. 必ず [保存] を選択してください。

6. [ プレイグラウンドで試す ] を選択し、"すべてのタスクを表示する" や "タスクを追加してください" などのプロンプトで Foundry エージェントをテストします。

   有効な応答を受け取った場合、エージェントはデプロイされた Web アプリで OpenAPI エンドポイントに対してツール呼び出しを行います。

1. 新しい Foundry ポータルの上部メニューから [ 操作] を選択し、[ 管理者] を選択します。Foundry プロジェクトの行には、2 つのリンクが表示されます。 [名前] 列の 1 つは Foundry プロジェクト リソースで、[親リソース] 列のリソースは Foundry リソースです。

   

2. 親リソースで Foundry リソース を選択し、 Azure portal で [このリソースの管理] を選択します。 Azure portal から、デプロイされた Web アプリにリソースのロールベースのアクセス権を割り当てることができます。

3. App Service アプリのマネージド ID に次のロールを追加します。

   ターゲット リソース	必要なロール	次の場合に必要です
   鋳造所	Cognitive Services OpenAI ユーザー	Microsoft Agent Framework のチャット完了サービス。

   手順については、「Azure portal を使用して Azure ロールを割り当てる」を参照してください。

1. 新しい Foundry ポータルの上部メニューから [ 操作] を選択し、[ 管理者] を選択します。Foundry プロジェクトの行には、2 つのリンクが表示されます。 [名前] 列の 1 つは Foundry プロジェクト リソースで、[親リソース] 列のリソースは Foundry リソースです。

   

2. [名前] 列で Foundry プロジェクト リソースを選択し、Azure portal で [このリソースの管理] を選択します。 Azure portal から、デプロイされた Web アプリにリソースのロールベースのアクセス権を割り当てることができます。

3. App Service アプリのマネージド ID に次のロールを追加します。

   ターゲット リソース	必要なロール	次の場合に必要です
   Foundry プロジェクト	Azure AI ユーザー	Foundry エージェントの読み取りと呼び出し。

   手順については、「Azure portal を使用して Azure ロールを割り当てる」を参照してください。