Tutorial: Build an agentic web app in Azure App Service with Microsoft Semantic Kernel or Foundry Agent Service (Spring Boot)

This tutorial demonstrates how to add agentic capability to an existing data-driven Spring Boot WebFlux CRUD application. It does this using Microsoft Semantic Kernel and Foundry Agent Service.

If your web application already has useful features, like shopping, hotel booking, or data management, it's relatively straightforward to add agent functionality to your web application by wrapping those functionalities in a plugin (for LangGraph) or as an OpenAPI endpoint (for Foundry Agent Service). In this tutorial, you start with a simple to-do list app. By the end, you'll be able to create, update, and manage tasks with an agent in an App Service app.

Semantic Kernel

Foundry Agent Service

Both Semantic Kernel and Foundry Agent Service enable you to build agentic web applications with AI-driven capabilities. The following table shows some of the considerations and trade-offs:

Consideration	Semantic Kernel	Foundry Agent Service
Performance	Fast (runs locally)	Slower (managed, remote service)
Development	Full code, maximum control	Low code, rapid integration
Testing	Manual/unit tests in code	Built-in playground for quick testing
Scalability	App-managed	Azure-managed, autoscaled
Security guardrails	Custom implementation required	Built-in content safety and moderation
Identity	Custom implementation required	Built-in agent ID and authentication
Enterprise	Custom integration required	Built-in Microsoft 365/Teams deployment and Microsoft 365 integrated tool calls.

In this tutorial, you learn how to:

• Convert existing app functionality into a plugin for Semantic Kernel.
• Add the plugin to a Semantic Kernel agent and use it in a web app.
• Convert existing app functionality into an OpenAPI endpoint for Foundry Agent Service.
• Call a Foundry agent in a web app.
• Assign the required permissions for managed identity connectivity.

Prerequisites

• An Azure account with an active subscription - Create an account for free.
• GitHub account to use GitHub Codespaces - Learn more about GitHub Codespaces.

Open the sample with Codespaces

The easiest way to get started is by using GitHub Codespaces, which provides a complete development environment with all required tools preinstalled.

1. Navigate to the GitHub repository at https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-java.

2. Select the Code button, select the Codespaces tab, and select Create codespace on main.

3. Wait a few moments for your Codespace to initialize. When ready, you'll see a fully configured development environment in your browser.

4. Run the application locally:

   mvn spring-boot:run
   

5. When you see Your application running on port 8080 is available, select Open in Browser and add a few tasks.

Review the agent code

Semantic Kernel

The Semantic Kernel agent is initialized in src/main/java/com/example/crudtaskswithagent/controller/AgentController.java, when the user enters the first prompt in a new browser session.

You can find the initialization code in the SemanticKernelAgentService constructor (in src/main/java/com/example/crudtaskswithagent/service/SemanticKernelAgentService.java). The initialization code does the following:

• Creates a kernel with chat completion.
• Adds a kernel plugin that encapsulates the functionality of the CRUD application (in src/main/java/com/example/crudtaskswithagent/plugin/TaskCrudPlugin.java). The interesting parts of the plugin are the DefineKernelFunction annotations on the method declarations and the description and returnType parameters that help the kernel call the plugin intelligently.
• Creates a chat completion agent, and configures it to let the AI model automatically invoke functions (FunctionChoiceBehavior.auto(true)).
• Creates an agent thread that automatically manages the chat history.

        // 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();

Each time the prompt is received, the server code uses ChatCompletionAgent.invokeAsync() to invoke the agent with the user prompt and the agent thread. The agent thread keeps track of the chat history.

// 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 Agent Service

The Foundry agent is initialized in src/main/java/com/example/crudtaskswithagent/controller/AgentController.java, when the user enters the first prompt in a new browser session.

You can find the initialization code in the FoundryAgentService constructor (in src/main/java/com/example/crudtaskswithagent/service/FoundryAgentService.java). The initialization code does the following:

• Creates an AgentsClientBuilder with endpoint and credentials.
• Builds specialized async clients: ConversationsAsyncClient and ResponsesAsyncClient.
• References the agent by name (configured in the Foundry portal).
• Creates a conversation for the session.

// 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();

Note

The constructor performs blocking operations (credential acquisition and conversation creation), so the controller (in src/main/java/com/example/crudtaskswithagent/controller/AgentController.java) creates the service on a boundedElastic thread using .subscribeOn(Schedulers.boundedElastic()).

This initialization code doesn't define any functionality for the agent, because you would typically build the agent in the Foundry portal. As part of the example scenario, it also follows the OpenAPI pattern shown in Add an App Service app as a tool in Foundry Agent Service (Spring Boot), and makes its CRUD functionality available as an OpenAPI endpoint. This lets you add it to the agent later as a callable tool.

The OpenAPI annotations are defined in the TaskController class. For example, the "GET /api/tasks" route defines operationId using the @Operation annotation, as required by the OpenAPI spec tool in Microsoft Foundry, and summary and description help the agent determine how to call the API:

@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();
}

Each time the prompt is received, the server code uses responsesClient.createWithAgentConversation() to send the message to the Foundry agent and retrieve the response. The conversation ID keeps track of the chat history.

// 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());
    });

Deploy the sample application

The sample repository contains an Azure Developer CLI (AZD) template, which creates an App Service app with managed identity and deploys your sample application.

1. In the terminal, log into Azure using Azure Developer CLI:

   azd auth login
   

   Follow the instructions to complete the authentication process.

2. Deploy the Azure App Service app with the AZD template:

   azd up
   

3. When prompted, give the following answers:

   Question	Answer
   Enter a new environment name:	Type a unique name.
   Select an Azure Subscription to use:	Select the subscription.
   Pick a resource group to use:	Select Create a new resource group.
   Select a location to create the resource group in:	Select Sweden Central.
   Enter a name for the new resource group:	Type Enter.

4. In the AZD output, find the URL of your app and navigate to it in the browser. The URL looks like this in the AZD output:

    Deploying services (azd deploy)
   
      (✓) Done: Deploying service web
      - Endpoint: <URL>
    

5. Open the autogenerated OpenAPI schema at the https://....azurewebsites.net/api/schema path. You need this schema later.

   You now have an App Service app with a system-assigned managed identity.

Create and configure the Microsoft Foundry resource

Semantic Kernel

1. In the Foundry portal, make sure the top New Foundry radio button is set to active and create a project.

2. Deploy a model of your choice (see Microsoft Foundry Quickstart: Create resources).

3. From top of the model playground, copy the model name.

4. The easiest way to get the Azure OpenAI endpoint is still from the classic portal. Select the New Foundry radio button, then Azure OpenAI, and then copy the URL in Azure OpenAI endpoint for later.

   

Foundry Agent Service

1. In the Foundry portal, make sure the top New Foundry radio button is set to active and create a project.

2. In the home page, copy the Project endpoint for later.

3. Select Start building > Create agent and follow the prompt.

4. In the new agent's playground, create an OpenAPI tool to call your web app by selecting Tools > Add > Custom > OpenAPI tool > Create. In the Setup pane, add an action with the OpenAPI spec tool. Use the OpenAPI schema that you get from the deployed web app and anonymous authentication. For detailed steps, see How to use the OpenAPI spec tool.

   Your application code is already configured to include the server's url and operationId, which are needed by the agent. For more information, see Connect to OpenAPI Specification.

5. Be sure to select Save.

6. Select Try in playground and test your Foundry agent with prompts like "Show me all the tasks" and "Please add a task."

   If you get a valid response, the agent is making tool calls to the OpenAPI endpoint on your deployed web app.

Assign required permissions

Semantic Kernel

1. From the top menu of the new Foundry portal, select Operate, then select Admin. In the row for your Foundry project, you should see two links. The one in the Name column is the Foundry project resource, and the one in the Parent resource column is the Foundry resource.

   

2. Select the Foundry resource in the Parent resource and then select Manage this resource in the Azure portal. From the Azure portal, you can assign role-based access for the resource to the deployed web app.

3. Add the following role for the App Service app's managed identity:

   Target resource	Required role	Needed for
   Foundry	Cognitive Services OpenAI User	The chat completion service in Microsoft Agent Framework.

   For instructions, see Assign Azure roles using the Azure portal.

Foundry Agent Service

1. From the top menu of the new Foundry portal, select Operate, then select Admin. In the row for your Foundry project, you should see two links. The one in the Name column is the Foundry project resource, and the one in the Parent resource column is the Foundry resource.

   

2. Select the Foundry project resource in the Name column and then select Manage this resource in the Azure portal. From the Azure portal, you can assign role-based access for the resource to the deployed web app.

3. Add the following role for the App Service app's managed identity:

   Target resource	Required role	Needed for
   Foundry Project	Azure AI User	Reading and calling the Foundry agent.

   For instructions, see Assign Azure roles using the Azure portal.

Configure connection variables in your sample application

1. Open src/main/resources/application.properties. Using the values you copied earlier from the Foundry portal, configure the following variables:

   Semantic Kernel

   Variable	Description
   azure.openai.endpoint	Azure OpenAI endpoint (copied from the classic Foundry portal).
   azure.openai.deployment	Model name in the deployment (copied from the model playground in the new Foundry portal).

   Note

   To keep the tutorial simple, you'll use these variables in .env instead of overwriting them with app settings in App Service.

   Foundry Agent Service

   Variable	Description
   azure.foundry.endpoint	Microsoft Foundry project endpoint from the new Foundry portal.
   azure.foundry.agent.name	Agent name (from the agent playground in the Foundry portal).

   Note

   To keep the tutorial simple, you'll use these variables in src/main/resources/application.properties instead of overwriting them with app settings in App Service.

2. Sign in to Azure with the Azure CLI:

   az login
   

   This allows the Azure Identity client library in the sample code to receive an authentication token for the logged in user. Remember that you added the required role for this user earlier.

3. Run the application locally:

   mvn spring-boot:run
   

4. When you see Your application running on port 8080 is available, select Open in Browser.

5. Try out the chat interface. If you get a response, your application is connecting successfully to the Microsoft Foundry resource.

6. Back in the GitHub codespace, deploy your app changes.

   azd up
   

7. Navigate to the deployed application again and test the chat agents.

   Semantic Kernel

   

   Foundry Agent Service

   

Clean up resources

When you're done with the application, you can delete the App Service resources to avoid incurring further costs:

azd down --purge

Since the AZD template doesn't include the Microsoft Foundry resources, you need to delete them manually if you want.

More resources

• Integrate AI into your Azure App Service applications
• Introduction to Semantic Kernel