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

2025-07-01

This tutorial demonstrates how to add agentic capability to an existing data-driven ASP.NET Core CRUD application. It does this using two different approaches: Microsoft Semantic Kernel and Azure AI 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 Semantic Kernel) or as an OpenAPI endpoint (for AI 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
Azure AI Foundry Agent Service

Screenshot of a chat completion session with a semantic kernel agent.

Both Semantic Kernel and Azure AI 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	Azure AI 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

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 functionaltiy into an OpenAPI endpoint for Azure AI Foundry Agent Service.
Call an Azure AI 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.

Navigate to the GitHub repository at https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent.
Select the Code button, select the Codespaces tab, and select Create codespace on main.
Wait a few moments for your Codespace to initialize. When ready, you'll see a fully configured development environment in your browser.
Run the application locally:
```
dotnet run
```
When you see Your application running on port 5280 is available, select Open in Browser and add a few tasks.

Review the agent code

Both approaches use the same implementation pattern, where the agent is initialized as a service (in Program.cs) in a provider and injected into the respective Blazor component.

Semantic Kernel
Azure AI Foundry Agent Service

The SemanticKernelAgentProvider is initialized in Services/SemanticKernelAgentProvider.cs. 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 Plugins/TaskCrudPlugin.cs). The only interesting parts of the plugin are the KernelFunction attributes on the method definitions and the Description attributes 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 = FunctionChoiceBehavior.Auto()).

public class SemanticKernelAgentProvider : ISemanticKernelAgentProvider
{
    public bool IsConfigured { get; }
    public ChatCompletionAgent? Agent { get; }

    public SemanticKernelAgentProvider(IConfiguration config, IServiceProvider sp)
    {
        IsConfigured = false;
        Agent = null;

        // Initialize a semantic kernel
        var deployment = config["ModelDeployment"];
        var endpoint = config["AzureOpenAIEndpoint"];
        if (string.IsNullOrWhiteSpace(deployment) || string.IsNullOrWhiteSpace(endpoint))
        {
            return;
        }
        var kernel = Kernel.CreateBuilder()
            .AddAzureOpenAIChatCompletion(
                deploymentName: deployment,
                endpoint: endpoint,
                new DefaultAzureCredential()
            ).Build();
        // Add the tasks CRUD plugin
        kernel.Plugins.AddFromType<TaskCrudPlugin>(serviceProvider: sp);

        // Create a chat completion agent
        Agent = new ChatCompletionAgent
        {
            Name = "TaskManagerAgent",
            Instructions =
                @"""
                Your 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.
                When handling requests, if you're missing any information, don't make it up but prompt the user for it instead.
                """,
            Kernel = kernel,
            Arguments = new KernelArguments(new AzureOpenAIPromptExecutionSettings()
            {
                FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
            })
        };

        IsConfigured = true;
    }
}

The FoundryAgentProvider provider is initialized in Services/FoundryAgentProvider.cs. The initialization code does the following:

Creates a new agents client.
Creates a new thread.
Gets the named agent, specified by the agent ID.

public class FoundryAgentProvider : IFoundryAgentProvider
{
    public bool IsConfigured { get; }
    public PersistentAgentsClient? Client { get; }
    public string? ThreadId { get; }
    public PersistentAgent? Agent { get; }

    public FoundryAgentProvider(IConfiguration config)
    {
        IsConfigured = false;

        // Create a new client instance
        var endpoint = config["AzureAIFoundryProjectEndpoint"];
        if (string.IsNullOrWhiteSpace(endpoint))
        {
            return; // Fail gracefully
        }
        Client = new PersistentAgentsClient(endpoint, new Azure.Identity.DefaultAzureCredential());

        // Create a new thread. 
        PersistentAgentThread agentThread = Client.Threads.CreateThread();
        ThreadId = agentThread.Id;

        // Create a new angent instance
        var agentId = config["AzureAIFoundryAgentId"];
        if (string.IsNullOrWhiteSpace(agentId))
        {
            return; // Fail gracefully
        }
        Agent = Client.Administration.GetAgent(agentId);

        IsConfigured = true;
    }
}

This initialization code doesn't define any functionality for the agent, because you would typically build the agent in the Azure AI 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 Azure AI Foundry Agent Service (.NET), 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 code is defined in Program.cs. For example, the "get tasks" API defines the operation ID with WithName(), as required by the OpenAPI spec tool in Azure AI Foundry, and WithDescription() helps the agent determine how to call the API:

app.MapGet("/api/tasks", async (TaskService taskService) =>
{
    return Results.Ok(await taskService.GetAllTasksAsync());
})
.WithDescription("Gets all tasks.")
.WithName("GetAllTasks");

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.

In the terminal, log into Azure using Azure Developer CLI:
```
azd auth login
```
Follow the instructions to complete the authentication process.
Deploy the Azure App Service app with the AZD template:
```
azd up
```

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 any region. The resources will actually be created in East US 2.
Enter a name for the new resource group:	Type Enter.

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>
 
```
Select the OpenAPI schema item to open the autogenerated OpenAPI schema at the default /openapi/v1.json path. You need this schema later.
After successful deployment, you'll see a URL for your deployed application.

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

Create and configure the Azure AI Foundry resource

In the Azure AI Foundry portal, deploy a model of your choice (see Quickstart: Get started with Azure AI Foundry). A project and a default agent are created for you in the process.
From the left menu, select Overview.
Select Azure AI Foundry and copy the URL in Azure AI Foundry project endpoint.
Select Azure OpenAI and copy the URL in Azure OpenAI endpoint for later.
From the left menu, select Agents, then select the default agent.
From the Setup pane, copy Agent ID, as well as the model name in Deployment.
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 How to use Azure AI Foundry Agent Service with OpenAPI Specified Tools: Prerequisites.
Select Try in playground and test your AI 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

At the upper right corner of the foundry portal, select the name of the resource, then select Resource Group to open it in the Azure portal.

Add a role for each of the two resources for the App Service app's manage identity using the following table:

Target resource	Required role	Needed for
Azure AI Foundry	Cognitive Services OpenAI User	The chat completion service in the semantic kernel.
Azure AI Foundry Project	Azure AI User	Reading and calling the AI Foundry agent.

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

Configure connection variables in your sample application

Open appsettings.json. Using the values you copied earlier from the AI Foundry portal, configure the following variables:

Variable	Description
`AzureOpenAIEndpoint`	Azure OpenAI endpoint (copied from the Overview page). This is needed by the Semantic Kernel agent.
`ModelDeployment`	Model name in the deployment (copied from the Agents setup pane). This is needed by the Semantic Kernel agent.
`AzureAIFoundryProjectEndpoint`	Azure AI Foundry project endpoint (copied from Overview page). This is needed for the Azure AI Foundry Agent Service.
`AzureAIFoundryAgentId`	Agent ID (copied from the Agents setup pane). This is needed to invoke an existing Azure AI Foundry agent.

Note

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

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.
Run the application locally:
```
dotnet run
```
When you see Your application running on port 5280 is available, select Open in Browser.
Select the Semantic Kernel Agent link and the Azure AI Foundry Agent link to try out the chat interface. If you get a response, your application is connecting successfully to the Azure AI Foundry resource.
Back in the GitHub codespace, deploy your app changes.
```
azd up
```
Navigate to the deployed application again and test the chat agents.

Semantic Kernel
Azure AI Foundry Agent Service

Screenshot of a chat completion session with a semantic kernel agent.

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 Azure AI Foundry resources, you need to delete them manually if you want.