But the challenge comes in when you have a service that sits outside of Microsoft ecosystem for example GitHub.

The authentication and authorization model is fundamentally different from Microsoft services and it becomes even more challenging when the MAF agent needs to access this service that has their own identity and authorization model.

For instance, you can generally establish a Microsoft Entra identity context and use Microsoft-native authorization mechanisms when accessing Microsoft services as the identity and permissions flow through the Microsoft security model. But for external service like GitHub the permission model does not flow through Microsoft authorization model and has its own security limitation.

In this article we will look into the approach on how to overcome this limitation. We wont use any third party authorization providers and will try to leverage native techniques that can be available at our disposal.

So, the intended flow is straightforward : a user sends a GitHub request through an MAF agent to create an issue in a repository. The agent should perform the operation only if the user has the required permissions on that repository. If the user does not have the necessary permissions the operation should fail and the issue should not be created.

We will use Azure Functions for MCP for MCP endpoint and Octokit to perform GitHub operations.

The biggest challenge is that, unlike MSAL which provides a redirect flow for authentication in windows, GitHub requires the application to manage the OAuth flow itself. But it does provide redirects to the callback URL with a temporary authorization code and through this code we can derive the GitHub access token .

We will use HttpListener to act as a temporary local callback server to call URL once GitHub authenticates the user credentials.

Our MCP endpoint will be an Azure Function and the client will be a console application that calls the MCP endpoint .

We will implement an OAuth based authentication model for GitHub. Think of it as a delegated authority where the application acts on behalf of the user. The OAuth will return an access token for the logged in user.

A token for the logged in user and GitHub uses the delegated authorization in combination with the user's existing permissions.

GitHub Settings

Repo GithubActions has two users : Sachin- Nand and SachinNandanwar

Sachin-Nand has write access while SachinNandanwar only has read access.

We first have to set OAuth Apps to enable GitHub OAuth flow.

Under Settings >> Profile >> Developer settings

Click on OAuth Apps and New OAuth apps

Enter App name and create a new client secret.

Note down the Client Id and Client Secret

The app created above is named GHub API.

Scroll down to the bottom of the page and for Redirect URI enter value

http://127.0.0.1:50505/callback. This is our loopback url.

You can use any port of your choice.

Azure Function

Create a new Azure Function for MCP project and add the following packages

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Mcp
dotnet add package Microsoft.Extensions.Logging
dotnet add package Octokit

Create a MCP function that accepts the repo name and the owner name.

[Function(nameof(GetGitHubRepository))]
public async Task<string> GetGitHubRepository(
  [McpToolTrigger("get_github_repository", "Gets information about a GitHub repository.")] ToolInvocationContext context,
  [McpToolProperty("owner", "GitHub repository owner.", isRequired: true)] string owner,
  [McpToolProperty("repository", "GitHub repository name.", isRequired: true)] string repository)
{
    var client = new GitHubClient(new ProductHeaderValue("MyGitHubApp"));
  
    if (context.TryGetHttpTransport(out var authHeaders))
    {
        var authenticatedClient = new GitHubClient(new ProductHeaderValue("MyGitHubApp"));

        authenticatedClient.Credentials = new Credentials(authHeaders.Headers["Authorization"]);
        var newIssue = new NewIssue("Bug: App crashes on launch")
        {
            Body = "The application immediately crashes when on start up."
        };
        var issue = await authenticatedClient.Issue.Create(owner, repository, newIssue);
        return "Issue created !!!";
    }
    else
    {
        return "Error !!!";
    }
}

Nothing fancy or complicated. Just a simple function that accepts the user inputs and authenticates the calls through ToolInvocationContext by checking the Authorization value in the request header.

Once authenticated and permissions are validated, an GitHub issue is logged through the GitHubClient object of Octokit.

Ideally the issue title and body should also come through the user input but for brevity I have mentioned it in the MCP function.

MCP Client

As mentioned earlier, the client will be a Console Application.

Add the following references

dotnet add package Azure;
dotnet add package Azure.AI.OpenAI;
dotnet add package Microsoft.Agents.AI;
dotnet add package Microsoft.Extensions.AI;
dotnet add package ModelContextProtocol.Server;
dotnet add package System.Text.Json.Serialization;
dotnet add package Microsoft.Extensions.Configuration;
dotnet add package Microsoft.Extensions.DependencyInjection;
dotnet add package Microsoft.Extensions.Logging;
dotnet add package ModelContextProtocol.Client;

Add appsetting.json to the project

"AppSettings": { 
    "Chat_DeploymentName": "Deployment Name",
    "EndPoint": "Azure OpenAI endpoint",
    "ApiKey": "Azure OpenAI API key"
}

Code

Once all the artifacts in place, add the following code to Program.cs

Program.cs >>

Read from the Config file

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Declare HttpClient

private static readonly HttpClient client = new HttpClient();
public static HttpClient httpClient => client;

Read credentials and register Chatclient

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

servicecollection.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
   .AsIChatClient()
    )
);

Create a DI container

 ServiceCollection servicecollection = new ServiceCollection();

Register ChatClientAgent in the DI container and build the Service Provider

servicecollection.AddSingleton<ChatClientAgent>();
ServiceProvider serviceprovider = servicecollection.BuildServiceProvider();

Fetch keyed IChatclient from DI container

var chatclient = new ChatClientAgent(serviceprovider.GetKeyedService<IChatClient>("ChatClient")).ChatClient;

Create ChatClientAgentOptions

  var options = new ChatClientAgentOptions()
  {
      ChatOptions = new ChatOptions()
      {
          Instructions = "You perform github operations",
          ToolMode = AutoChatToolMode.Auto,
          Tools = [.. await ConnectGitHubMCP()],
      },
      Name = "GitHub Agent"
  };

ConnectGitHubMCP

 public static async Task<List<McpClientTool>> ConnectGitHubMCP()
 {
     string clientId = "XXXXXXXXXXXXXX";
     string redirectUri = "http://127.0.0.1:50505/callback";
     using var listener = new HttpListener();
     listener.Prefixes.Add("http://127.0.0.1:50505/");
     listener.Start();

     var authUrl =
         "https://github.com/login/oauth/authorize" +
         $"?client_id={Uri.EscapeDataString(clientId)}" +
         $"&redirect_uri={Uri.EscapeDataString(redirectUri)}";

     Process.Start(
     new ProcessStartInfo
     {
         FileName = authUrl,
         UseShellExecute = true
     });

     var context = await listener.GetContextAsync();

     var tokenRequest = new Dictionary<string, string>
     {
         ["client_id"] = clientId,
         ["client_secret"] = "XXXXXXXXXXXXXX",
         ["code"] = context.Request.QueryString["code"],
         ["redirect_uri"] = redirectUri
     };
    
     var content = new FormUrlEncodedContent(tokenRequest);
     var response = await httpClient.PostAsync(
         "https://github.com/login/oauth/access_token",
         content);
     var accesstoken = response.Content.ReadAsStringAsync().Result.Split("=")[1].Replace("&expires_in", "");

     const string html = """
         <!DOCTYPE html>
         <html>
         <head>
             <title>Authentication Complete</title>
         </head>
         <body>
             <p>Authentication successful. You can close this window.</p>
             <script>
                 window.close();
             </script>
         </body>
         </html>
         """;

     var buffer = Encoding.UTF8.GetBytes(html);
     context.Response.ContentType = "text/html";
     context.Response.ContentLength64 = buffer.Length;
     await context.Response.OutputStream.WriteAsync(buffer);
     context.Response.OutputStream.Close();

     listener.Stop();
     httpClient.Timeout = Timeout.InfiniteTimeSpan;

     var transport = new ModelContextProtocol.Client.HttpClientTransport(
         new HttpClientTransportOptions
         {
             Endpoint = new Uri("http://localhost:7287/runtime/webhooks/mcp"),
             Name = "Custom GitHub MCP",
             TransportMode = HttpTransportMode.AutoDetect,
             EnableStandaloneGetStream = false,
             AdditionalHeaders = new Dictionary<string, string>
             {
                 { "Authorization" , accesstoken }
             }
         },
             httpClient
        );

     var mcpClient = await McpClient.CreateAsync(transport);
     var tools = await mcpClient.ListToolsAsync();
     return tools.ToList();
 }

Lets look at the important aspects of the above code.

We first create and start a HttpListener with the redirectUri pointed to the GitHub callback URI that we set on the GitHub settings page of the account.

 string clientId = "XXXXXXXXXXXXXX";
 string redirectUri = "http://127.0.0.1:50505/callback";
 using var listener = new HttpListener();
 listener.Prefixes.Add("http://127.0.0.1:50505/");
 listener.Start();

We then build a GitHub OAuth authorization URL with two parameters ,client_id and redirect_uri.

Client id is the GitHub Client Id of the OAuth App called GHub API that we had set earlier and the redirect uri is the callback url.

var authUrl =
    "https://github.com/login/oauth/authorize" +
    $"?client_id={Uri.EscapeDataString(clientId)}" +
    $"&redirect_uri={Uri.EscapeDataString(redirectUri)}";

Start a process to trigger the opening of the GitHub authorization URL in the browser.

Process.Start(
new ProcessStartInfo
{
    FileName = authUrl,
    UseShellExecute = true
});

Create a token request with the following default parameters, the most important one being context.Request.QueryString["code"] that extracts the authorization code that GitHub sends back in the callback URL. Its a temporary authorization code required only for token generation.

var context = await listener.GetContextAsync();

var tokenRequest = new Dictionary<string, string>
{
    ["client_id"] = clientId,
    ["client_secret"] = clientSecret,
    ["code"] = context.Request.QueryString["code"],
    ["redirect_uri"] = redirectUri
};

Exchanging the code for our access token and then extract the accesstoken from the response.

var content = new FormUrlEncodedContent(tokenRequest);

var response = await httpClient.PostAsync(
            "https://github.com/login/oauth/access_token",
            content);

var accesstoken = response.Content.ReadAsStringAsync().Result.Split("=")[1].Replace("&expires_in", "");

The part below is optional. The reason for this code is to notify the user that the authentication is successful and the user can then close the browser window.

Since GitHub does not support a native browser client redirects, I have injected my own custom HTML to the client

 const string html = """
     <!DOCTYPE html>
     <html>
     <head>
         <title>Authentication Complete</title>
     </head>
     <body>
         <p>Authentication successful. You can close this window.</p>
         <script>
             window.close();
         </script>
     </body>
     </html>
     """;

 var buffer = Encoding.UTF8.GetBytes(html);
 context.Response.ContentType = "text/html";
 context.Response.ContentLength64 = buffer.Length;
 await context.Response.OutputStream.WriteAsync(buffer);
 context.Response.OutputStream.Close();
 listener.Stop();

Create a client function that connects to the MCP endpoints and returns the MCP Server tool list.

MCP endpoint used here is : http://localhost:7287/runtime/webhooks/mcp

var transport = new ModelContextProtocol.Client.HttpClientTransport(
    new HttpClientTransportOptions
    {
        Endpoint = new Uri("http://localhost:7287/runtime/webhooks/mcp"),
        Name = "Custom GitHub MCP",
        TransportMode = HttpTransportMode.AutoDetect,
        EnableStandaloneGetStream = false,
        AdditionalHeaders = new Dictionary<string, string>
        {
            { "Authorization" , accesstoken }
        }
    }
  );

var mcpClient = await McpClient.CreateAsync(transport);
var tools = await mcpClient.ListToolsAsync();
return tools.ToList();

Send the following prompt to the agent

Create an issue on the repo GitHubActions owned by Sachin-Nand

as user Sachin-Nand and the GitHub issue is created.

while doing so as user SachinNandanwar the creation fails.

Execution

Conclusion

With this approach the possibilities of leveraging MAF agents to external services that exist out of Microsoft ecosystem becomes significantly broader with out the need for any third party OAuth providers.

More importantly, this approach allows MAF agents to combine capabilities across multiple ecosystems without being restricted to Microsoft native services.

Thanks for reading !!!

At that time my focus was to understand how vector embeddings can be used in Semantic Kernel (SK) along with search embeddings without an external vector database.

But there are some inherent drawbacks with that approach, the major one is that all the embeddings are kept in memory. This works well when dealing with small amount of data but as the data increases coupled with user concurrency, your application will hit a major bottleneck. Hence it becomes prudent to store the embeddings and the underlying data in a persistent storage and query only the necessary data based on the user prompt.

In this article, I will reference the InMemory Vector Embeddings approach and explore how it can be integrated with Microsoft Agent Framework and Redis for persistent storage. The idea is not only to store embeddings in Redis but also to make them useful for an agent so that it can retrieve the relevant information based on the user prompt.

Custom Embedding vs Azure AI Search

Custom Embedding approach is more viable if you require complete control over storage, embedding generation, retrieval process and more importantly if most of the underlying data is centralized. But for a more enterprise applications, Azure AI Search is more relevant when the data is spread across different data sources for instance if your data is spread across say Fabric and Cosmos DB.

A custom embedding approach is preferred when the need is for a simple retrieval requirement. Azure AI Search is preferable when you need a no code/low code enterprise-grade search solution with advanced retrieval capabilities.

This article will look into the custom embedding process. For Azure AI search approach please refer to my article on the topic here and here.

Redis

To get started we will spin up an Redis image on Docker.

docker run -d --name redis-stack -p 6379:6379 -p 8001:8001 redis/redis-stack:latest

You will have to spin up a redis-stack and not local-redis else you will get the following error : RedisVectorStore Fails to Create Index and Upsert Records with "no such index"

More details : https://github.com/microsoft/semantic-kernel/issues/12734 and the solution is in the same thread here .

Though the bug report says that its fixed for SK(Semantic Kernel) this issue crops up with MAF(Microsoft Agent Framework) but honestly I don't believe that issue is related to specific agent framework (SK or MAF) but more with SK embedding library.

The bug report highlighted that Redis integration does work with the Microsoft.SemanticKernel.Connectors.AzureAISearch but this library is deprecated so I couldn't use it.

So I used the Microsoft.SemanticKernel.Connectors.AzureOpenAI library but still ended up with the same error.

Thankfully the solution of using redis-stack worked well and the AzureOpenAI library also provides the necessary DI extension method for registering the embedding services.

Redis on docker is running on port number : 6379

TextSearchProvider

This class was introduced in the Microsoft.Agents.AI namespace. It was not available with Semantic Kernel. With TextSearchProvider we can directly inject the results to the AI agents AI invocation context to enable RAG in the agent.

Now you might ask what advantages does it bring ?

With TextSearchProvider, you don't have to manually implement RAG for the agent.

It also maintains the conversation context through TextSearchProviderState class which exposes a property called RecentMessagesText which is handy if you wish to store the conversational messages to an external storage skipping the complexity of implementing your own custom ChatChistoryProvider.

I have an article on ChatChistoryProvider for MAF that you can refer here.

TextSearchProvider also exposes another class called TextSearchResult that can be used to retrieve the raw representation of the search result through the RawRepresentation property along with the Text property which returns the textual context.

Project SetUp

Create a new console application and add the following packages

dotnet add package Azure;
dotnet add package Azure.AI.OpenAI;
dotnet add package Microsoft.Agents.AI;
dotnet add package Microsoft.Extensions.AI;
dotnet add package StackExchange.Redis;
dotnet add package System.Text.Json.Serialization;
dotnet add package Microsoft.Extensions.Configuration;
dotnet add package Microsoft.Extensions.DependencyInjection;
dotnet add package Microsoft.Extensions.Logging;
dotnet add package CommunityToolkit.VectorData.Redis;

Of the above CommunityToolkit.VectorData.Redis is a .NET package that uses Redis as a vector store for semantic search and StackExchange.Redis is the Redis client that provides API for Redis commands.

Microsoft.Extensions.AI exposes an interface IEmbeddingGenerator to create the necessary embeddings .

Add appsetting.json to the project

"AppSettings": { 
    "Chat_DeploymentName": "Deployment Name",,
    "Embed_DeploymentName": "Embedding model",
    "EndPoint": "Azure OpenAI endpoint",
    "ApiKey": "Azure OpenAI API key"
}

Note : Apart from the chat model, reference to the embedding model is required.

Code

Create a DI container

 ServiceCollection servicecollection = new ServiceCollection();

Read credentials and register Chatclient

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

servicecollection.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
   .AsIChatClient()
    )
);

Read the embedding generator and add it to the DI container

servicecollection.AddAzureOpenAIEmbeddingGenerator(
deploymentName: configuration["AppSettings:Embed_DeploymentName"],
endpoint: configuration["AppSettings:EndPoint"],
apiKey: configuration["AppSettings:ApiKey"]);

Register ChatClientAgent in the DI container and build the Service Provider

servicecollection.AddSingleton<ChatClientAgent>();
ServiceProvider serviceprovider = servicecollection.BuildServiceProvider();

Let's create some sample data. But before that, we have to define the object structure.

using Microsoft.Extensions.VectorData;

public class Hotel
{
      
[VectorStoreKey]
public string HotelId { get; set; }

[VectorStoreData(IsIndexed = true)]
public string HotelName { get; set; }

[VectorStoreData]
public string Description { get; set; }

[VectorStoreData]
public string Source { get; set; }

[VectorStoreVector(1536)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }  

[VectorStoreData]
public string[] Tags { get; set; }

[VectorStoreVector(1536)]
public ReadOnlyMemory<float>? TagListEmbedding { get; set; }

}

What we have above is

• VectorStoreKey → This acts as a unique record identifier (primary key)

• VectorStoreData → This is used to store metadata field and can be optionally indexed

• VectorStoreVector(1536) → This is an embedding vector used for similarity search with specified dimension size. In our case we have the dimension size of 1536 for TagListEmbedding and DescriptionEmbedding

Data

Create some sample data that matches the object structure defined above.

  private static List<Hotel> CreateHotelRecords()
  {
      var hotel = new List<Hotel>
  {
      new Hotel {
          HotelId = "1",
          HotelName = "Sea Breeze Resort",
          Description = "Beachfront resort with stunning ocean-view rooms and a seafood restaurant serving fresh, locally sourced cuisine. Guests can enjoy direct access to the beach, relaxing sunsets, spacious accommodations, and a range of recreational activities. The resort also features a swimming pool, spa services, water sports, and comfortable lounge areas, making it an ideal destination for a relaxing seaside vacation.",
          Source = "www.beachfronthotel.com",
          Tags = new[] { "beach", "resort", "seafood", "luxury" }
      },

      new Hotel {
          HotelId = "2",
          HotelName = "City Central Hotel",
          Description = "Modern hotel located in the heart of the downtown area, offering stylish rooms, contemporary amenities, and convenient access to shopping malls, restaurants, cafes, and vibrant nightlife. Guests can enjoy comfortable accommodations, high-speed Wi-Fi, a fitness center, an on-site restaurant, and easy access to public transportation. The hotel is ideal for both business and leisure travelers looking to explore the city's attractions, entertainment venues, and cultural landmarks.",
            Source = "www.partytimehotel.com",
          Tags = new[] { "city", "business", "shopping", "nightlife" }
      },

      new Hotel {
          HotelId = "3",
          HotelName = "Lakeview Retreat",
          Description = "Peaceful retreat near the lake with spa and yoga facilities. Enjoy breathtaking lake views, serene surroundings, and comfortable accommodations designed for relaxation. The property offers rejuvenating spa treatments, daily yoga sessions, wellness activities, and tranquil spaces to unwind. Guests can also explore scenic walking trails, enjoy healthy meals, and experience a peaceful escape from the hustle and bustle of everyday life.",
          Source = "www.lakeviewhotel.com",
          Tags = new[] { "lake", "spa", "relaxation", "yoga" }
      },

      new Hotel {
          HotelId = "4",
          HotelName = "Desert Mirage Inn",
          Description = "Boutique desert hotel offering a unique blend of traditional charm and modern comfort in a peaceful desert setting. Guests can enjoy guided camel tours across the dunes, breathtaking desert sunsets, and an unforgettable outdoor dining experience featuring local cuisine under the open sky. The property also offers comfortable rooms, relaxing lounge areas, cultural activities, and opportunities to experience the natural beauty and tranquility of the desert.",
           Source = "www.desertadventurehotek.com",
          Tags = new[] { "desert", "boutique", "sunset", "adventure" }
      }
  };
      return hotel;
  }

There are two distinct pipeline processes involved: Insertion and Retrieval.

Insertion

Define an Embedding generator

 var embeddingGenerator = serviceprovider.GetRequiredService<IEmbeddingGenerator<string, Embedding<float>>>();

Earlier, we registered an embedding model inside the Dependency Injection (DI) container. In the above code, we are requesting the same service to be returned back through the IEmbeddingGenerator interface so that the data embeddings could be generated.

JSON Collection

RedisJsonCollection<string, Hotel> redisCollection = new RedisJsonCollection<string, Hotel>(
ConnectionMultiplexer.Connect("localhost:6379").GetDatabase(), "hotel_index", new() { EmbeddingGenerator = embeddingGenerator });

Embeddings will be stored as type RedisJsonCollection.There is a second option called RedisHashSetCollection.

The vabriable redisCollection declared above is essentially a client-side object used to interact with Redis. The actual records and their embeddings are stored in Redis, not inside the redisCollection variable.

With RedisJsonCollection type, the objects are stored in the JSON format while fore RedisHashSetCollection, they are stored in the hash key format.

Our collection is named as hotel_index .The value of the EmbeddingGenerator property is assigned through the variable embeddingGenerator that was declared earlier.

Note : With RedisHashSetCollection, datatype string[] is not supported. Our structure has string[] data for Tags so we cant use the RedisHashSetCollection type.

Data Creation

 await redisCollection.EnsureCollectionExistsAsync();
 var hotelRecords = CreateHotelRecords().ToList();

We first ensure that the Redis collection exists if not then create it and then store the hotel data to the variable hotelRecords.

Note : At this stage we haven't updated the collection with the vector embedding values.

Create Embeddings

To create the embeddings we will have to traverse the collection and create the embeddings for each record in the collection.

void InsertCollection(RedisJsonCollection <string, Hotel> redisCollection) 
{
  redisCollection.EnsureCollectionExistsAsync();

  var hotelRecords = CreateHotelRecords().ToList();

  foreach(var hotel in hotelRecords) {
    var descriptionEmbeddingTask = embeddingGenerator.GenerateAsync(hotel.Description);
    var featureListEmbeddingTask = embeddingGenerator.GenerateAsync(string.Join("\n", hotel.Tags));
    hotel.DescriptionEmbedding =(descriptionEmbeddingTask).Result.Vector;
    hotel.TagListEmbedding = (featureListEmbeddingTask).Result.Vector;
  }
  redisCollection.UpsertAsync(hotelRecords);
}

and finally update the redisCollection(declared earlier)with the UpsertAsync method. This concludes our ingestion pipeline.

Verify Redis Collection

Post execution of the ingestion pipeline, we can verify the collection in Redis. For that we will use have to enable redis-cli .

Execute the following command in the Docker terminal to enable it.

docker exec -it redis-stack redis-cli

Get a list of collection

FT._LIST

Return the details for the collection

FT.INFO hotel_index

It returns a list of different attributes of the collection that we just created.

Retrieval

Now that we have verified the collection in Redis, the next step is the retrieval process.

Retrieval will be through the AI Agent AIContextProvider property.

Before that, we have to set the SearchAdapater which acts as an input to AIContextProvider.

async Task <IEnumerable<TextSearchProvider.TextSearchResult>> SearchAdapter(string query, CancellationToken cancellationToken) {

  List <TextSearchProvider.TextSearchResult> results = new();

  var searchVector = await embeddingGenerator.GenerateAsync(query);

  var resultRecords = await redisCollection.SearchAsync(
    searchVector, top: 1, new() {
      VectorProperty = r => r.DescriptionEmbedding
    }).ToListAsync();

  var finalresults = resultRecords.Select(result =>
    new TextSearchProvider.TextSearchResult {

      Text = result.Record.Description,
        SourceName = result.Record.Source,
        RawRepresentation = result.Record.HotelName,

    });

  return await Task.FromResult <IEnumerable< TextSearchProvider.TextSearchResult>> (finalresults);
}

What we are doing above is that, we are embedding the user input with the embeddinggenerator which acts as an input to the redisCollection that was declared earlier and through SearchAsync we the return the TOP 1 matching rows by comparing the VectorProperty of the user input with the DescriptionEmbedding property of the Hotel object.

var searchVector = await embeddingGenerator.GenerateAsync(query);

var resultRecords = await redisCollection.SearchAsync(
  searchVector, top: 1, new() {
    VectorProperty = r => r.DescriptionEmbedding
  }).ToListAsync();

And finally we return the results in form of TextSearchResult property of the TextSearchProvider object.

 var finalresults = resultRecords.Select(result =>
   new TextSearchProvider.TextSearchResult {
     Text = result.Record.Description,
       SourceName = result.Record.Source,
       RawRepresentation = result.Record.HotelName
   });

return await Task.FromResult <IEnumerable< TextSearchProvider.TextSearchResult>> (finalresults);

This adapter now acts as an input of the AIContextProvider of the agent.

We will set it in the ChatClientAgentOptions of the Agent through TextSearchProvider class.

var options = new ChatClientAgentOptions
        {
            ChatOptions = new ChatOptions
            {
                Instructions = "You are a helpful chat assistant .Answer briefly and succinctly. Be personable.Recommend the best matching hotel.Explain briefly why it matches the request.Use only provided hotels.If the user query matches any of the hotel's tags, recommend it.If no hotel context is provided, say\"I'm sorry, but there is no matching hotel available for your request. If you have any specific preferences or criteria, please let me know, and I'll do my best to assist you!\".Otherwise assume the provided hotel is the correct match.Use the provided hotel data to answer\r\n- Answer based ONLY on given hotel.Use hotels only from the list provided to you.Add more details about the location and activities that the user can enjoy as bulleted point."
            },           
            AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)]

        };

Note the Instructions set for the agent. The instructions are very extensive that provides the agent information on how to handle the user request and how to interpret prompts and what do do incase the underlying data does not have the necessary information for user requests.

Fetch keyed IChatclient from the DI container

var _chatclient = new ChatClientAgent(serviceprovider.GetKeyedService<IChatClient>("ChatClient")).ChatClient;

Set the ChatClientAgentOptions to the above ChatClientAgent

var agent = _chatclient.AsAIAgent(options);

Pass the prompt to the Agent

Console.WriteLine(await agent.RunAsync(new ChatMessage(ChatRole.User, "I am looking for a hotel close to the beach.") 
{
   CreatedAt = DateTimeOffset.UtcNow, AuthorName = "Sachin"
 }, session: agentsession, new AgentRunOptions 
{
   AllowBackgroundResponses = true
 }) + "\n");

Output

Execution

Conclusion

This was an introductory article on how vector embeddings can be created and stored in an external storage that overcomes the shortcomings of InMemoryVector embedding . This approach is more prudent when you need more control over storage ,embeddings and the retrieval process.

Thanks for reading !!!

That implementation was limited in a sense that the entire operation was done through a console application. In this article I tried to take that logic a step ahead by integrating it with MAF and Azure Functions and expose it through MCP.

Introduction

Recently, Fabric Core MCP Server was released and is currently under preview. Its integration with other applications is quite seamless and it exposes a lot of useful tools that can significantly simplify and enhance external tool interactions with Microsoft Fabric.

The screenshot below lists the complete set of tools available through the Fabric MCP server.

I published a detailed article a couple of days ago explaining on how to integrate your external client application with Fabric Core MCP Server. You can go through that article here .

Before we get started, following is a list of key tools and technologies used in the implementation of this MCP tool.

• Fabric REST API's

• Microsoft Graph API

• Microsoft Graph Service Client

• MCP for Azure Functions

• MCP C# SDK

• Microsoft Agent Framework

It would be helpful if you have some understanding of the above tools and technologies. Of the above list, Microsoft Agent Framework (MAF) is the least used as its implementation is limited for setting up the instructions, tool bindings and passing the user prompts to the MCP Server (Azure Function).

What's the need for this MCP tool ?

Imagine an employee leaving an organization and you wanna know which Fabric items does the user has access to. Wouldn't it be great if you could just send a prompt like

Give me list of items user ABC has access to.
Or
Give me list of items user ABC has access to, which are of type Reports

I couldn't find a tool function in the Fabric Core MCP Server that would return item access of an user.

This is exactly why this MCP is designed for. As mentioned at the very start, I created a similar utility about an year and half ago and I blogged it here.

In that implementation I extensively used the Users - List Access Entities Fabric REST API's in a combination with Microsoft Graph API's.

If you want to know more about Microsoft Graph API's, I have a detailed article on that topic as well.

Delegated Permissions and Scopes

We need to assign the following Delegated permissions to the service principal we will be using.

We will require two scopes. One for Graph API and second for Fabric REST API's

• https://graph.microsoft.com/.default

• https://api.fabric.microsoft.com/.default

So the authentication header will required two access tokens. One for Microsoft Graph and second for Microsoft Fabric.

Thank fully MCP SDK supports passing multiple tokens through a type Dictionary.

TokenCredentials

GraphServiceClient authentication requires TokenCredentials for authentication, so just using the access token will not be useful. For that we will have to convert bearer token to TokenCredentials.

I have an detailed article on how that can be implemented.

The example in the above article is specific for OneLake authentication but can be used for other implementations as well. OneLake authentication also requires the bearer access token to be converted into a TokenCredential before it can be used with the Azure SDK.

Along with that, we will use PublicApplicationBuilder from the MSAL(Microsoft Authentication Library) to create the bearer access token so that we don't have maintain client secret of the underlying service principal.

Set Up

We will create a Azure Function for MCP endpoints and a console application as the client. The client will send prompts to the MCP Azure functions through an AIAgent . The agent tools are exposed through the MCP C# SDK.

Lets first set up the Azure Function

The Azure function type is MCP Tool trigger as our Azure Function execution should be tool driven instead of prompt driven.

Add the following references to the Azure Function project.

dotnet add package Microsoft.Azure.Functions.Worker;
dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Mcp
dotnet add package Microsoft.Extensions.Logging;
dotnet add package Microsoft.Graph;
dotnet add package Newtonsoft.Json.Linq;

The Fabric REST API output is in JSON format and is very dynamic.

So we will use Json.NET to traverse the response object.

To get started, declare a bunch of variables and define the constructor of class in the Azure function that is assigned to the _logger variable.

The fabric endpoint used is https://api.fabric.microsoft.com/v1

 private static Dictionary<string, string> itemlist = new();
 private static string endpoint = "https://api.fabric.microsoft.com/v1";
 private static readonly HttpClient client = new HttpClient();
 private static GraphServiceClient graph_Service_Client;
 private ILogger<Function1> _logger;

 public Function1(ILogger<Function1> logger)
 {
     _logger = logger;
 }

GetAsync >>

This function returns HTTP response received from the endpoint using an HttpClient.

  public async static Task<string> GetAsync(string url, string token)
  {
      client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
      HttpResponseMessage response = await client.GetAsync(url);
      try
      {
          response.EnsureSuccessStatusCode();
          return await response.Content.ReadAsStringAsync();
      }
      catch (HttpRequestException httpRequestException)
      {
          return null;
      }

  }

GetUserDetails >>

This function is used to parse the JSON response and extract the relevant data

 [Function(nameof(GetUserDetails))]
 public async Task <IDictionary<string,string>> GetUserDetails
(
   [McpToolTrigger(nameof(GetUserDetails), "Gets the user access details")] ToolInvocationContext context,
   [McpToolProperty(nameof(username), "The name of the user for whom access details are sought")] string ? username) {
   List <string> tokens = new();

   if (context.TryGetHttpTransport(out var authHeaders)) 
   {     tokens.Add(authHeaders.Headers["Authorization_graph"].Replace("Bearer ", ""));
     tokens.Add(authHeaders.Headers["Authorization_fabric"].Replace("Bearer ", ""));
   }

   AccessTokenCredential tokenCredential = new AccessTokenCredential(tokens[0]);
   graph_Service_Client = new GraphServiceClient(tokenCredential);

   Microsoft.Graph.Models.UserCollectionResponse result = await graph_Service_Client.Users.GetAsync((requestConfiguration) => requestConfiguration.QueryParameters.Top = 999);

   IDictionary < string, object > userdetails = new Dictionary < string, object > ();

   int i = 0;

   if (username == "All") 
{
     foreach(var str in result.Value) 
{
       userdetails.Add(result.Value[i].DisplayName.ToString(), result.Value[i]);
       i++;
     }
   } 
else 
{
     foreach(var str in result.Value.Select(i => i.DisplayName == username)) 
{
       if (str == false) { i++; continue; }
       userdetails.Add(result.Value[i].DisplayName.ToString(), result.Value[i]);
       i++;
     }
   }

   i = 0;
   itemlist.Clear();

   foreach(var user in userdetails) 
 {
     string userId = ((Microsoft.Graph.Models.Entity) userdetails.Where(a => a.Key == user.Key).ToList()[0].Value).Id.ToString();
     string response = await GetAsync(endpoint + "/admin/Users/" + userId + "/access", tokens[1]);

     if (response == null) 
     {
       continue;
     }
     JObject j_response = JObject.Parse(response);
     JArray j_array = (JArray) j_response["accessEntities"];
     foreach(JObject path in j_array) {

       JToken itemid = path["id"];
       JToken item = path["itemAccessDetails"]["type"];
       JToken name = path["displayName"];

       JToken permissions = path["itemAccessDetails"]["permissions"];
       JArray permissions_arr = (JArray) permissions;
       string permission = "";
       foreach(JToken p in permissions_arr) 
       {
         permission = permission + ("/" + p.ToString());
         p.ToString();
       }

       JToken additionalPermissions = path["itemAccessDetails"]["additionalPermissions"];
       if (additionalPermissions != null) 
       {
         JArray permissions_ad_arr = (JArray) additionalPermissions;
         string permission_a = "";
         foreach(JToken p in permissions_ad_arr) {
           permission_a = permission_a + ("/" + p.ToString());
           p.ToString();
         }
         itemlist.Add(i + "`" + item, "Item Type" + "~" + item + "~" + "Item Name" + "~" + name + "Permissions" + "~" + permissions + "~" + "Additional Permissions" + "~" + permission_a);
       } 
     else 
       {
         itemlist.Add(i + "`" + item, "Item Type" + "~" + item + "~" + "Item Name" + "~" + name + "Permissions" + "~" + permissions + "~" + "Additional Permissions" + "~" + "N/A");

       }
       i++;
     }
     return itemlist;
   }
   return null;
 }

Lets look at the important aspects of the above function.

We have McpToolTrigger of type GetUserDetails that accepts username as McpToolProperty. It is required for MCP tool to process a prompt, something like the below

Give me list of items user ABC has access to.

Then we have the ToolInvocationContext that exposes the underlying tools, HTTP headers and arguments of the tool call.

With ToolInvocationContext, it becomes quite easy to read the HTTP headers invoked by the client. Recall that earlier I mentioned that we will require two bearer tokens, one for Fabric REST API and second for Graph API.

List <string> tokens = new();

if (context.TryGetHttpTransport(out var authHeaders)) 
{
tokens.Add(authHeaders.Headers["Authorization_graph"].Replace("Bearer ", ""));
  tokens.Add(authHeaders.Headers["Authorization_fabric"].Replace("Bearer ", ""));
}

Also earlier I mentioned that Graph API requires bearer token to be converted to TokenCredentials. The following line of code does that.

AccessTokenCredential tokenCredential = new AccessTokenCredential(tokens[0]);
graph_Service_Client = new GraphServiceClient(tokenCredential);

tokens[0] above is the token for Graph API and AccessTokenCredential is the custom class that does the conversion. I will post the code for that class later in the article.

GraphServiceClient gets a list of users and add it to UserCollectionResponse object of the Graph Model object.

Microsoft.Graph.Models.UserCollectionResponse result = await graph_Service_Client.Users.GetAsync((requestConfiguration) => requestConfiguration.QueryParameters.Top = 999);

We then add the usernames to a dictionary object called userdetails .

IDictionary<string,object> userdetails = new Dictionary<string, object>();
int i = 0;

if (username == "All")
{
    foreach (var str in result.Value)
    {
        userdetails.Add(result.Value[i].DisplayName.ToString(), result.Value[i]);
        i++;
    }
}
else
{
    foreach (var str in result.Value.Select(i => i.DisplayName == username))
    {
        userdetails.Add(result.Value[i].DisplayName.ToString(), result.Value[i]);
        i++;
    }
}

and then filter the dictionary based on filters passed through the prompt.

If the prompt contains the keyword "All" we save all the usernames to userdetails dictionary and if not, then just store the filtered username to the userdetails dictionary.

The code below calls the Users - List Access Entities API for each user object in the userdetails dictionary and the response is traversed with JSON.Net library.

foreach(var user in userdetails) 
{
    string userId = ((Microsoft.Graph.Models.Entity) userdetails.Where(a => a.Key == user.Key).ToList()[0].Value).Id.ToString();
    string response = await GetAsync(endpoint + "/admin/Users/" + userId + "/access", tokens[1]);
    if (response == null) 
    {
      continue;
    }
    JObject j_response = JObject.Parse(response);
    JArray j_array = (JArray) j_response["accessEntities"];
    foreach(JObject path in j_array) 
   {

      JToken itemid = path["id"];
      JToken item = path["itemAccessDetails"]["type"];
      JToken name = path["displayName"];

      JToken permissions = path["itemAccessDetails"]["permissions"];
      JArray permissions_arr = (JArray) permissions;
      string permission = "";
      foreach(JToken p in permissions_arr) 
      {
        permission = permission + ("/" + p.ToString());
        p.ToString();
      }

      JToken additionalPermissions = path["itemAccessDetails"]["additionalPermissions"];
      if (additionalPermissions != null) {
        JArray permissions_ad_arr = (JArray) additionalPermissions;
        string permission_a = "";
        foreach(JToken p in permissions_ad_arr) 
        {
          permission_a = permission_a + ("/" + p.ToString());
          p.ToString();
        }
        itemlist.Add(i + "`" + item, "Item Type" + "~" + item + "~" + "Item Name" + "~" + name + "Permissions" + "~" + permissions + "~" + "Additional Permissions" + "~" + permission_a);
      } 
     else 
     {
        itemlist.Add(i + "`" + item, "Item Type" + "~" + item + "~" + "Item Name" + "~" + name + "Permissions" + "~" + permissions + "~" + "Additional Permissions" + "~" + "N/A");
      }
      i++;
    }
return itemlist;

API call is : https://api.fabric.microsoft.com/v1/admin/users/{userId}/access that fetches the userId from the Graph API.

API Response >>

The access details are finally stored in a dictionary called itemlist with "~" used as the separator.

itemlist Dictionary >>

the user access details are stored in the dictionary object in the following format which is sent back the agent for the display.

GetUserDetailsForItemType >>

This function is similar to the GetUserDetails function with the only difference being that it is used to get access details for a specific item type.

[Function(nameof(GetUserDetailsForItemType))]
public async Task <IDictionary <string,string>> GetUserDetailsForItemType
(
  [McpToolTrigger(nameof(GetUserDetailsForItemType), "Gets the user access detail for a given item type")] ToolInvocationContext context,
  [McpToolProperty(nameof(username), "The name of the user for whom access details are sought")] string ? username,
  [McpToolProperty(nameof(itemtype), "The name of the item type for whom access details are sought")] string ? itemtype) {

  List <string> tokens = new();

  if (context.TryGetHttpTransport(out var authHeaders)) 
{
    tokens.Add(authHeaders.Headers["Authorization_graph"].Replace("Bearer ", ""));
    tokens.Add(authHeaders.Headers["Authorization_fabric"].Replace("Bearer ", ""));

  }
  AccessTokenCredential tokenCredential = new AccessTokenCredential(tokens[0]);
  graph_Service_Client = new GraphServiceClient(tokenCredential);

  Microsoft.Graph.Models.UserCollectionResponse result =
  await graph_Service_Client.Users.GetAsync((requestConfiguration) => requestConfiguration.QueryParameters.Top = 999);

  IDictionary <string,object> userdetails = new Dictionary< string,object> ();
  int i = 0;
  if (username == "All") 
   {
    foreach(var str in result.Value) 
   {
      userdetails.Add(result.Value[i].DisplayName.ToString(), result.Value[i]);
      i++;
    }
  } 
  else 
   {
    foreach(var str in result.Value.Select(i => i.DisplayName == username)) 
    {
      userdetails.Add(result.Value[i].DisplayName.ToString(), result.Value[i]);
      i++;
    }
  }
  itemlist.Clear();

  foreach(var user in userdetails) 
  {
    string userId = ((Microsoft.Graph.Models.Entity) userdetails.Where(a => a.Key == user.Key).ToList()[0].Value).Id.ToString();
    string response = await GetAsync(endpoint + "/admin/Users/" + userId + "/access?type=" + itemtype, tokens[1]);

    if (response == null) 
    {
      continue;
    }

    JObject j_response = JObject.Parse(response);

    JArray j_array = (JArray) j_response["accessEntities"];
    foreach(JObject path in j_array) {

      JToken itemid = path["id"];
      JToken item = path["itemAccessDetails"]["type"];
      JToken name = path["displayName"];

      JToken permissions = path["itemAccessDetails"]["permissions"];
      JArray permissions_arr = (JArray) permissions;
      string permission = "";
      foreach(JToken p in permissions_arr) 
      {
        permission = permission + ("/" + p.ToString());
        p.ToString();
      }

      JToken additionalPermissions = path["itemAccessDetails"]["additionalPermissions"];

      if (additionalPermissions.HasValues == true) 
      {
        JArray permissions_ad_arr = (JArray) additionalPermissions;
        string permission_a = "";
        foreach(JToken p in permissions_ad_arr) 
        {
          permission_a = permission_a + ("/" + p.ToString());
          p.ToString();
        }
        itemlist.Add(i + "`" + item, "Item Type" + "~" + item + "~" + "Item Name" + "~" + name + "Permissions" + "~" + permissions + "~" + "Additional Permissions" + "~" + permission_a);
      } 
     else 
      {
        itemlist.Add(i + "`" + item, "Item Type" + "~" + item + "~" + "Item Name" + "~" + name + "Permissions" + "~" + permissions + "~" + "Additional Permissions" + "~" + "N/A");
      }

      i++;

    }
    return itemlist;

  }
  return null;
}

Unlike GetUserDetails that accepts only username as McpToolProperty, the function GetUserDetailsForItemType has two McpToolProperty: username and itemtype.

This is required for MCP tool to process a prompt something like the below

Get access details for user ABC for item type Notebooks

The API call is now made to the following endpoint :

https://api.fabric.microsoft.com/v1/admin/users/{userId}/access/access?type={itemtype}

Client Console Application >>

This console application is used to call the MCP endpoint. You can use any other client tool like VSCode Copilot or through a Minimal API incase you want to expose the output through API's

using Azure;
using Azure.AI.OpenAI;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Client;
using ModelContextProtocol.Client;

public static class Program 
{
  private static string RedirectURI = "http://localhost";
  private static string clientId = "Service Principal Client Id";
  private static string tenantId = "Tenant Id";
  private static readonly HttpClient client = new HttpClient();
  private static string[] scopes_g = new string[] {
    "https://graph.microsoft.com/.default"};
  private static string[] scopes_f = new string[] {
    "https://api.fabric.microsoft.com/.default"};
  private static string Authority = $"https://login.microsoftonline.com/{tenantId}";
  public static HttpClient Client => client;

  private static async Task Main() 
{

    ServiceCollection servicecollection = new();

    var configuration = new ConfigurationBuilder()
      .SetBasePath(Directory.GetCurrentDirectory())
      .AddJsonFile("appsettings.json", optional: false)
      .Build();

    var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

    servicecollection.AddKeyedChatClient("ChatClient", 
   (sp => new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)      .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
      .AsIChatClient()));

    servicecollection.AddSingleton <ChatClientAgent> (sp => 
   {
      return new ChatClientAgent(sp.GetKeyedService <IChatClient > ("ChatClient"));
    });

    ServiceProvider serviceprovider = servicecollection.BuildServiceProvider();

    var chatlient = serviceprovider.GetServices < ChatClientAgent > ();
    List < ChatClientAgent > lstchatclient = new(chatlient);

    var options = new ChatClientAgentOptions() {

      ChatOptions = new ChatOptions() {
          Instructions = "You are a Fabric Agent and you execute the appropriate tools. " +
            "You will display the results in table format with columns Item Type, Item Name, Access Details. Please singularize the itemtype if use prompt contains them." +
            "For example, if the prompt contains reports then singularize to report and if Notebooks then to Notebook and so and so forth",
            ToolMode = AutoChatToolMode.Auto,
            Tools = [..await ConnectMCP()]
        },
        Name = "Fabric Agent"
    };

    var agent = lstchatclient[0].ChatClient.AsAIAgent(options);

    AgentResponse agentresponse = await agent.RunAsync("Get access details for user ABC that he has access to");

    Console.Write(agentresponse.Text);

  }

  public async static Task <AuthenticationResult> ReturnAuthenticationResult(string[] scopes) {
    string AccessToken;
    PublicClientApplicationBuilder PublicClientAppBuilder =
      PublicClientApplicationBuilder.Create(clientId)
      .WithAuthority(Authority)
      .WithCacheOptions(CacheOptions.EnableSharedCacheOptions)
      .WithRedirectUri(RedirectURI);

    IPublicClientApplication PublicClientApplication = PublicClientAppBuilder.Build();
    var accounts = await PublicClientApplication.GetAccountsAsync();
    AuthenticationResult result;
    try 
    {
      result = await PublicClientApplication.AcquireTokenSilent(scopes, accounts.First())
        .ExecuteAsync()
        .ConfigureAwait(false);
    } 
  catch 
   {
      result = await PublicClientApplication.AcquireTokenInteractive(scopes)
        .ExecuteAsync()
        .ConfigureAwait(false);
    }
    return result;
  }

  public static async Task <List<McpClientTool>> ConnectMCP() 
{
    AuthenticationResult result_graph = await ReturnAuthenticationResult(scopes_g);
    AuthenticationResult result_fabric = await ReturnAuthenticationResult(scopes_f);

    var httpClient = new HttpClient 
    {
      Timeout = Timeout.InfiniteTimeSpan
    };
    var transport = new ModelContextProtocol.Client.HttpClientTransport(
      new HttpClientTransportOptions {
        Endpoint = new Uri("http://{Azure Function URL }/runtime/webhooks/mcp"),
          Name = "Custom Fabric MCP",
          TransportMode = HttpTransportMode.AutoDetect,
          EnableStandaloneGetStream = false,
          AdditionalHeaders = new Dictionary < string, string > {
            {
              "Authorization_graph",
              $ "Bearer {result_graph.AccessToken}"
            },
            {
              "Authorization_fabric",
              $ "Bearer {result_fabric.AccessToken}"
            }
          }
      },
      httpClient
    );

    var mcpClient = await McpClient.CreateAsync(transport);
    var tools = await mcpClient.ListToolsAsync();
    return tools.ToList();
  }
}

The above code is similar to the one used in my earlier article on Fabric MCP. Only difference being that I am passing two tokens through the header

AdditionalHeaders = new Dictionary <string,string> 
         {
            {
              "Authorization_graph",
              $ "Bearer {result_graph.AccessToken}"
            },
            {
              "Authorization_fabric",
              $ "Bearer {result_fabric.AccessToken}"
            }
          }

which is used to call GraphServiceClient & Users - List Access Entities API .

Also notice the agent instructions

You are a Fabric Agent and you execute the appropriate tools.
You will display the results in table format with columns Item Type, Item Name, Access Details. Please singularize the itemtype if use prompt contains them. For example, if the prompt contains reports then singularize to report and if Notebooks then to Notebook and so and so forth.

AccessTokenCredential.cs >>

This class converts bearer token generated by ReturnAuthenticationResult in the client code above to TokenCredentials for reasons explained earlier

using Azure.Core;
using System.IdentityModel.Tokens.Jwt;

namespace AccesTokenCredentials
{
    public class AccessTokenCredential : Azure.Identity.ClientSecretCredential
    {
        public AccessTokenCredential(string accessToken)
        {
            AccessToken = accessToken;
        }

        private string AccessToken;

        public AccessToken FetchAccessToken()
        {
            JwtSecurityToken token = new JwtSecurityToken(AccessToken);
            return new AccessToken(AccessToken, token.ValidTo);
        }

        public override ValueTask<AccessToken> GetTokenAsync(
            TokenRequestContext requestContext,
            CancellationToken cancellationToken
        )
        {
            return new ValueTask<AccessToken>(FetchAccessToken());
        }

        public override AccessToken GetToken(
            TokenRequestContext requestContext,
            CancellationToken cancellationToken
        )
        {
            JwtSecurityToken token = new JwtSecurityToken(AccessToken);
            return new AccessToken(AccessToken, token.ValidTo);
        }
    }
}

Limitations >>

The output does not lists the workspace under which a particular item exists and also it does not lists access details of a service principal. This can be a major shortcoming but I have a solution for that as well :) which I will post in my upcoming blog.

Execution

Conclusion

The intention of this article is not to make a production level agent but to provide a starting point incase you do decide to create a custom agent that interacts with the Fabric services.

The possibilities and quite endless and when coupled with Microsoft Agent Framework(MAF) you can leverage the fantastic features and properties of MAF that could interact with Fabric services and ecosystem.

Thanks for reading !!!

Recently, the Fabric Core MCP Server was released. At the time of this writing this feature is in preview. So please test it thoroughly before you use it in your production environment.

Fabric Core MCP Server is a remote endpoint that enables AI agents to interact with the Microsoft Fabric ecosystem. This opens a window of opportunity where MAF Agents can seamlessly communicate with artifacts within the Microsoft Fabric Ecosystem which eventually can reduce the complexities involved in overall code and structural customization.

Couple of weeks ago I had published an article that demonstrated the integration MAF AIAgent with Azure Services. To be honest, there were a lot of nuts and bolts involved in getting this set up running. But leveraging Fabric Core MCP Server you skip all such complexities when it comes to integrating it with Microsoft Fabric.

In this article we will deep dive in how to integrate MAF AIAgent with Fabric MCP Server.

To get started, we have to setup a few delegated permissions for the service principal that we will use.

The service principal will impersonate the logged in user and based on the user permissions assigned to the user for a specific Fabric item, the AIAgent will interact with the underlying Fabric services.

I granted the following delegated permissions to the service principal that I will use.

We will use the usual Fabric scope : https://api.fabric.microsoft.com/.default and MSAL (Microsoft Authentication Library) for token generation and the Fabric MCP Server endpoint https://api.fabric.microsoft.com/v1/mcp/core

SetUp

There are two Entra users

sachin.nandanwar @ azureguru.net and sachin_nandanwar @ azureguru.net

User sachin.nandanwar @ azureguru.net is an admin on the Fabric tenant while the user sachin_nandanwar @ azureguru.net only has Viewer access on one of the Fabric workspaces called "My Test workspace"

We will test a few prompts that would allow us to interact with the workspace "My Test workspace" on the Fabric tenant.

Following is the list of all the tools available through the Fabric MCP server.

By a simple prompt, you could list workspaces, create workspaces, create/update/delete items and so and so forth.

Of course the outcome of these actions will be dependent on the level of access the logged in user has for the underlying objects.

As mentioned earlier, there are Entra two users

• (Sachin.Nand) sachin.nandanwar @ azureguru.net

• (Sachin Nandanwar) sachin_nandanwar @ azureguru.net

I will test the prompts by logging in with both users.

Code

Add the following references to a new C# console project

dotnet add package Azure;
dotnet add package Azure.Core;
dotnet add package Microsoft.Agents.AI;
dotnet add package Azure.AI.OpenAI;
dotnet add package Microsoft.Extensions.AI;
dotnet add package ModelContextProtocol.Client;
dotnet add package Microsoft.Identity.Client;
dotnet add package Microsoft.Extensions.DependencyInjection;

Declare a bunch of variables in Program.cs

private static string RedirectURI = "http://localhost";
private static string clientId = "Service Principal Client Id";
private static string tenantId = "Fabric tenant Id";
private static readonly HttpClient client = new HttpClient();
private static string[] scopes = new string[] { "https://api.fabric.microsoft.com/.default" };
private static string Authority = $"https://login.microsoftonline.com/{tenantId}";
public static HttpClient Client => client;

Next , define an Authentication method that validates the user sign-in and delegated scopes using Microsoft Entra ID and returns AuthenticationResult.

ReturnAuthenticationResult >>

public async static Task <AuthenticationResult> ReturnAuthenticationResult() {
  string AccessToken;
  PublicClientApplicationBuilder PublicClientAppBuilder =
    PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(Authority)
    .WithCacheOptions(CacheOptions.EnableSharedCacheOptions)
    .WithRedirectUri(RedirectURI);

  IPublicClientApplication PublicClientApplication = PublicClientAppBuilder.Build();
  var accounts = await PublicClientApplication.GetAccountsAsync();
  AuthenticationResult result;
  try {

    result = await PublicClientApplication.AcquireTokenSilent(scopes, accounts.First())
      .ExecuteAsync()
      .ConfigureAwait(false);
  } catch {
    result = await PublicClientApplication.AcquireTokenInteractive(scopes)
      .ExecuteAsync()
      .ConfigureAwait(false);

  }
  return result;
}

Add the following code in Program.cs to read settings from the config file appsettings.json

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Read credentials and register Chatclient and return a ChatClientAgent

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

servicecollection.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)
                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
   .AsIChatClient()
    )
);

builder.Services.AddSingleton<ChatClientAgent>(sp =>
{
    return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"));
});

Now create a DI container to the ChatClientAgent

ServiceProvider serviceprovider = servicecollection.BuildServiceProvider();

var chatlient = serviceprovider.GetServices<ChatClientAgent>();

List<ChatClientAgent> lstchatclient = new(chatlient);

Create a client function that connects to the MCP endpoints and returns the MCP Server tool list.

public static async Task <List<McpClientTool>> ConnectMCP() 
{
 
AuthenticationResult result = await ReturnAuthenticationResult();

      var httpClient = new HttpClient {
        Timeout = Timeout.InfiniteTimeSpan
      };
      var transport = new ModelContextProtocol.Client.HttpClientTransport(
        new HttpClientTransportOptions {
          Endpoint = new Uri("https://api.fabric.microsoft.com/v1/mcp/core"),
            Name = "MCP Client",
            TransportMode = HttpTransportMode.AutoDetect,
            EnableStandaloneGetStream = false,
            AdditionalHeaders = new Dictionary <string,string> {
              {
                "Authorization",$ "Bearer {result.AccessToken}"
              }
            }
        },
        httpClient
      );

      var mcpClient = await McpClient.CreateAsync(transport);
      var tools = await mcpClient.ListToolsAsync();
      return tools.ToList();
    }

In the above code, we connect to MCP server endpoint through the MCP HttpClientTransport class and pass the bearer token through the method ReturnAuthenticationResult which returns an AuthenticationResult object.

Now, configure the ChatClientAgentOptions and set its Tools property to the method ConnectMCP() that was defined above.

  var options = new ChatClientAgentOptions()
  {
      ChatOptions = new ChatOptions()
      {
          Instructions = "You are a Fabric Agent and you execute the appropriate tools",
          ToolMode = AutoChatToolMode.Auto,
          Tools = [.. await ConnectMCP()]
      },
      Name = "Fabric Agent"
  };

Next, assign the options configured above to the ChatClient, create an AIAgent from it and then send a prompt to the agent to create a lakehouse.

var agent = lstchatclient [0].ChatClient.AsAIAgent(options);

AgentResponse  agentresponse = await agent.RunAsync("Create a lakehouse with name Fabric_MCP_LakeHouse in workspace My Test Workspace.");

Console.Write(agentresponse.Text);

Logging in as sachin.nandanwar @ azureguru.net and the lakehouse creation succeeds

Trying to do the same logging in as sachin_nandanwar @ azureguru.net

This is because sachin_nandanwar @ azureguru.net only has Viewer access for the workspace "My Test Workspace".

Now let me try to list items(semantic models) in the same workspace. The prompt should return list of the semantic models as the user (sachin_nandanwar @ azureguru.net ) has viewer access for the workspace.

The updated prompt is

AgentResponse  agentresponse = await agent.RunAsync("Provide a list of semantic models in My Test Workspace.");

Console.Write(agentresponse.Text);

There are many amazing things that you could do using the Fabric MCP Server tools, of course being limited to the underlying permissions the logged in user has.

But you might argue that all these features are already available through VS Code GitHub Copilot.

Yes it is, but what if you want to extend this functionality to other external applications or AI agents ?

This is where exposing your agent through MCP becomes particularly useful. Instead of limiting the functionality to a specific environment you can now make your agent available as an MCP tool for Fabric ecosystem that can be consumed by any MCP-compatible client.

Execution

Conclusion

Integrating the Microsoft Agent Framework (MAF) with the Fabric Core MCP Server provides a powerful way to extend AI agents with Fabric capabilities.

Through this article I tried to demonstrates how MAF and MCP can work together to connect AI agents with external data and services while maintaining authentication and integrating the Fabric security model.

Thanks for reading !!!

I will explain the reason, the problems and why I think that the title reflects what I am about to discuss in this article.

Model Context Protocol (MCP)

To get started with MCP, there are many online resources available that cover everything from MCP fundamental concepts and architecture to tools, resources, prompts and so on and so forth.

You can refer to the following links to understand what MCP is all about

• Introduction to MCP >> https://modelcontextprotocol.io/docs/2026-07-28/getting-started/intro

• C# MCP SDK >> https://csharp.sdk.modelcontextprotocol.io/v1/api/ModelContextProtocol.Server.McpServerTool.html

• Build MCP Server in C# >> https://devblogs.microsoft.com/dotnet/build-a-model-context-protocol-mcp-server-in-csharp/

I don't want to repeat the same MCP concepts in this article that are already covered in abundance in the above resources and are more technically superior and in-depth compared to my abilities to explain them :)

The intention of this article is to focus on a specific issue that I faced.

Problem Statement

So, I had a scenario where I wanted to expose an AIAgent as an MCP tool . The conventional approach is to expose it as the .AsAIFunction() method to the McpServerTool class.

McpServerTool tool = McpServerTool.Create(agent.AsAIFunction());

and then add McpServerTool (tool) to the builder services collection

builder.Services
    .AddMcpServer()
    .WithHttpTransport()
    .WithTools([tool]);

This registers the McpServerTool with the MCP server, adding it to the server's tool collection so that the tool can be exposed to MCP clients.

Assume that there is an agent called SomeAIAgent with SomeAIFunction registered as one of its tools.

AIAgent SomeAIAgent = new OpenAIClient(apiKey)
   .......,
   .......,
   .AsAIAgent(.....),
   tools: [AIFunctionFactory.Create(SomeAIFunction)]
   );

But here comes the twist.

What if your AIFunctions are registered with DI (Dependency Injection) and you have to resolve and invoke these AIFunctions as MCP endpoint ?

Look at the following example where an AIFunction is registered with the DI container.

builder.Services.AddSingleton<AIFunction>(sp =>
    {
 return AIFunctionFactory.Create(SomeAIFunction, new AIFunctionFactoryOptions { Name = "SomeAIFunctionName", Description = "Some Description", SerializerOptions = SomeeSerializerContext.Default.Options });
    });

This is where things starts to get interesting.

Normally, to use the above function I will have to rewrite them in a class marked [McpServerToolType] and expose methods with the [McpServerTool] annotation.

For example the following screenshot taken from the example here shows how MCP Server tool is defined so that they can be exposed through a MCP endpoint.

Of course I didn't wanted to redesign all my AIFunctions to be inline and compatible with the above design. This would had required a lot of code refactoring.

So I had to somehow figure out a way where in I can use the DI registered AIFunctions without having to rewrite them all over again.

MCP Inspector

But before we get into more details of the issue , lets first walkthrough the basic steps of setting up and installing MCP inspector to test our MCP endpoints.

To run MCP inspector you need Node.js in your system. To verify if Node.js is installed , run the following command in PowerShell

node -v

If it does not return a version number then it indicates that Node.js is not installed.

Execute the following command in PowerShell to install Node.js

winget install OpenJS.NodeJS.LTS

Accept the license agreement and verify the installation by re executing the following command.

node -v

It should now return the node version number.

Once its verified that node.js is installed , execute the following command to install MCP inspector

npm install -g @modelcontextprotocol/inspector

Now execute the following command in PowerShell to run MCP inspector.

 npx -y @modelcontextprotocol/inspector

This will open the MCP inspector UI in a new browser page.

We will have to add MCP server details which basically is going to be the AIAgent that we are going to expose as a MCP tool. We will come back to this later in the article.

Project Setup

Create a new ASP.Net core project and add the following packages

dotnet add package Azure;
dotnet add package Azure.AI.OpenAI;
dotnet add package Microsoft.Agents.AI;
dotnet add package Microsoft.Extensions.AI;
dotnet add package ModelContextProtocol.Server;
dotnet add package System.Text.Json.Serialization;
dotnet add package Microsoft.Extensions.Configuration;
dotnet add package Microsoft.Extensions.DependencyInjection;
dotnet add package Microsoft.Extensions.Logging;

Add appsetting.json to the project

"AppSettings": { 
    "Chat_DeploymentName": "Deployment Name",
    "EndPoint": "Azure OpenAI endpoint",
    "ApiKey": "Azure OpenAI API key"
}

Code

Once all the artifacts in place, add the following code to Program.cs

Program.cs >>

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Create a web application instance

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

Read credentials and register Chatclient

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

servicecollection.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
   .AsIChatClient()
    )
);

Inject and register a ChatClientAgent

 builder.Services.AddSingleton<ChatClientAgent>(sp =>
 {
     return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"));
 });

Lets have a function called ReturnCityTemperature that returns the temperature of a given city. This function is to be registered with the DI container as an AIFunction.

We define the required request and response objects for CityTemperature

CityTemperatureSearchRequest & CityTemperatureSearchResponse >>

 public class CityTemperatureSearchRequest
 {
     public string City { get; set; }
 }

 public class CityTemperatureSearchResponse
 {
     public string City { get; set; }
     public string Temperature { get; set; }
 }

Next, create serialization metadata for both request and response types.

[JsonSerializable(typeof(CityTemperatureSearchRequest))]
[JsonSerializable(typeof(CityTemperatureSearchResponse))]
internal sealed partial class CityTemperatureSerializerContext : JsonSerializerContext;

The following delegate returns the underlying data

ReturnCityTemperature >>

public static Func<CityTemperatureSearchRequest, CityTemperatureSearchResponse> ReturnCityTemperature = (CityTemperatureSearchRequest) =>

{
    switch (CityTemperatureSearchRequest.City)
    {

        case "Mumbai":

            return new CityTemperatureSearchResponse
            {

                City = "Mumbai",
                Temperature = "40"
            };

            break;

        case "Pune":

            return new CityTemperatureSearchResponse
            {

                City = "Pune",
                Temperature = "41"
            };

            break;

        case "Delhi":

            return new CityTemperatureSearchResponse
            {

                City = "Delhi",
                Temperature = "42"
            };

            break;

        case "Chennai":

            return new CityTemperatureSearchResponse
            {

                City = "Chennai",
                Temperature = "43"
            };
            break;
    }

    return new CityTemperatureSearchResponse
    {

        City = CityTemperatureSearchRequest.City,
        Temperature = "Unknown"
    };

};

Register the above delegate function with the DI container as an AIFunction along with the corresponding SerializerOptions that were defined earlier.

  builder.Services.AddSingleton <AIFunction> (sp => {
   return AIFunctionFactory.Create(ReturnCityTemperature, new AIFunctionFactoryOptions {
     Name = "ReturnCityTemperature", Description = "Gets the temperature of a city", SerializerOptions = CityTemperatureSerializerContext.Default.Options
   });
 });

Register the MCP Server >>

MCP server is added to the service collection and with streamable HTTP configured through WithHttpTransport extension and mapped to "api/mcp".

builder.Services.AddMcpServer()
.WithHttpTransport(options =>
{      
    options.Stateless = true;
}
);
    WebApplication app = builder.Build();        
    app.MapMcp(pattern: "api/mcp");
    app.Run();

There is a very important extension called .WithToolsFromAssembly() that auto discovers all classes and tools annotated with [McpServerToolType] and [McpServerTool] respectively.

which unfortunately will be of no use for me, as my tools are DI registered.

Now, here comes the interesting and the important aspect.

How to expose all the DI registered tools through the MCP Server ?

This is how to do it

builder.Services.AddSingleton <McpServerTool> (sp => 
{
  var chatClientList = sp.GetRequiredKeyedService <IChatClient> ("ChatClient");
  var aifunctions = sp.GetServices <AIFunction> ();
  List <AITool> functions = new(aifunctions);

  var options = new ChatClientAgentOptions 
{
    ChatOptions = new ChatOptions 
    {
      Tools = functions
    }
};
  var agent = chatClientList.AsAIAgent(options);
  return McpServerTool.Create(agent.AsAIFunction
(
 new AIFunctionFactoryOptions 
{    Name = "WeatherAgent"
  }));
});

builder.Services.AddMcpServer()
  .WithHttpTransport(options => 
  {
    options.Stateless = true;
  });

WebApplication app = builder.Build();
app.MapMcp(pattern: "api/mcp");
app.Run();

Lets dig into the above code step by step >>

Register McpServerTool as a singleton in the DI container.

builder.Services.AddSingleton<McpServerTool>

Fetch keyed IChatClient and AIFunction from the DI container.

Add them to the collection variable functions of type List

var chatClientList = sp.GetRequiredKeyedService<IChatClient>("ChatClient");

  var aifunctions = sp.GetServices<AIFunction>();

  List<AITool> functions = new(aifunctions);

  var options = new ChatClientAgentOptions
  {
      ChatOptions = new ChatOptions
      {
          Tools = functions
      }
  };

  var agent = chatClientList.AsAIAgent(options);

Set ChatClientAgentOptions and assign functions variable to Tools property in ChatOptions and then assign it to chatClientList with an .AsAIAgent() extension method chain to create an AIAgent.

var agent = chatClientList.AsAIAgent(options);

Now return the agent as an AIFunction with the required options

return McpServerTool.Create(agent.AsAIFunction(new AIFunctionFactoryOptions
   {
       Name = "WeatherAgent"
   }));

Now things even get more interesting.

Let me send a prompt that queries the underlying data.

What is the temperature in Pune?

The result is just the response text with no additional details that you would normally expect from an agent response.

Now, let me make a few changes in how I expose the agent to the MCP Server.

    builder.Services.AddSingleton<McpServerTool>(sp =>
   {
       var chatClientList = sp.GetRequiredKeyedService<IChatClient>("ChatClient");

       var aifunctions = sp.GetServices<AIFunction>();

       List<AITool> functions = new(aifunctions);

       var options = new ChatClientAgentOptions
       {
           ChatOptions = new ChatOptions
           {

               Tools = functions
           }
       };
       var agent = chatClientList.AsAIAgent(options);

      var agentFunction = AIFunctionFactory.Create(

     async (string message) =>
     {
         var response = await agent.RunAsync(message);

         return response;
     },
     new AIFunctionFactoryOptions
     {
         Name = "WeatherAgent"
     });

       return McpServerTool.Create(agentFunction);

   });

    builder.Services.AddMcpServer()
   .WithHttpTransport(options =>
   {
       options.Stateless = true;

   }
   );

    WebApplication app = builder.Build();
    app.MapMcp(pattern: "api/mcp");
    app.Run();
}

So the changes that I have done is that I am executing the agent by capturing the user i/p and agent response in the AIFunction itself and then exposing the AIFunction(agentFunction) to the McpServerTool.

I created an on the fly AIFunction that takes user input (message argument) and executed the agent within the AIFunction and it then returns the agent response.

Now instead of passing the agent as AIFunction (agent.AsAIFunction) to the MCPServerTool, I am passing an agentFunction to it

 var agentFunction = AIFunctionFactory.Create(

  async (string message) =>
  {
      var response = await agent.RunAsync(message);

      return response;
  },
  new AIFunctionFactoryOptions
  {
      Name = "WeatherAgent"
  });

    return McpServerTool.Create(agentFunction);

});

and now try the execution with the same prompt that I tried earlier

What is the temperature in Pune?

and this time the agent output format changes, which is lot more detailed

The reason for this behavior ? Honestly I don't know :).

I only found out this behavior by accident. I will have to put in some time to understand this behavior.

Lets now look into how to configure MCP to test the agent.

Once MCP inspector is installed and running, click the Add Server option on top right and select Add manually option

In the pop up that follows, select streamable-http

Select WithHttpTransport because we have used this option to set our MCP Server

In the next pop up, add the project endpoint

In this example its running on : http://localhost:5176

Under Servers option the registered MCP server should be visible.

If everything has been configured properly the server should display the Connected status which the indicates the client has successfully connected to the server.

Select the Tools option and it will list the Name of the AIFunction that was used to set the MCPServerTool.

Run the prompt and now you will have a more detailed output.

Execution

Final Take

Though this is an edge case there might be possibility that you might face such a situation where your agentic architecture revolves more around DI pattern.

Rather than introducing a completely separate approach for exposing the agent through MCP, you can leverage the existing DI-based approach that i have suggested in this article to integrate MCP with it. This allows the agent to remain consistent with the application's DI pattern while making it compatible with the MCP requirements.

Thanks for reading !!!

While a file-based approach is useful for understanding the underlying concepts it is definitely not an ideal choice for most real-world production set ups. As the number of users and conversations grows, storing chat history in file systems can be very challenging with added complexities.

In a production environment, chat history needs to be stored on a persistent data store so that it can be accessed across multiple instances of an application. This is where a distributed data stores such as Redis becomes useful. It provides a fast and scalable mechanism for storing messages and the maintain chat history.

But just simply storing the entire conversation indefinitely introduces another important challenge: the size of the conversation context. As a conversation becomes longer, sending the complete chat history to the underlying agents on every request increases token consumption, latency and cost. It can also eventually exceed the model's context window.

Though MAF provides ChatReducer to address this problem, one particularly useful implementation is SummarizingChatReducer that reduces growing conversation by summarizing older messages unlike ChatReducer that simply discards them. This helps to preserve important conversation context in place.

This article will demonstrate storing conversation to Redis and how to leverage SummarizingChatReducer to summarize and reduce long conversations while at the same time maintain the conversation context.

Custom Chat History Provider

In MAF, the most crucial component is the ProviderSessionState object wrt custom chat history implementation. It acts as the abstraction layer through which MAF manages and retrieves chat history through session StateBag.

In my previous article , I used IChatReducer to reduce chat size stored in ProviderSessionState . But drawback with this approach is that you lose the conversation context as the reduction is based on a fixed number (N) of messages. Because of this, important aspects of the conversation is discarded. The agent therefore has access only to the most recent N messages.

Given the drawback of the above approach a more feasible and practical approach is to leverage SummarizingChatReducer where values for targetCount and threshold properties define the number of messages that are summarized and stored so that correct conversational context is maintained.

Property targetCount is the used to specify the number of recent messages that should be retained post reduction while threshold is the number of messages allowed beyond targetCount before summarization.

When the conversation grows beyond targetCount + threshold values , older messages are summarized into a single message that persists the entire conversational context. This message replaces the old messages which are discarded and the most recent messages defined by targetCount stays.

For example : Lets assume that SummarizingChatReducer has targetCount of 1 and threshold of 5 and the no of prompts sent are 6.

Once the total number of chat messages recorded in ProviderSessionState is equal or greater than 6 (1+5), summarization kicks in. 1 recent message is retained post summarization in its original form and all messages are summarized.

There are two major approaches for storing and retrieving summarized conversational context.

• In the first approach , you store the entire conversation along with summarized messages in a persistent storage like Redis and retrieve only the summarized messages in the ProvideChatHistoryAsync method. The major advantage with this approach is that you have the true conversation history at your disposal but disadvantage being that the size of the persistent storage would grow and managing it can be challenging.

• In the second approach ,only the summarized messages are stored in a persistent storage like Redis along with all the messages above the limit set by the targetCount value. Major advantage with this approach is that you have less data to manage but disadvantage is that you lose all historical trails of the conversation as only the summarized conversational context is available and stored.

Redis

You can either use Redis on Azure or use a Redis image on Docker. I am using Docker. Spin up Redis on Docker through following command in the Docker terminal.

docker run -d --name local-redis -p 6379:6379 redis:latest

Redis is running on port number : 6379

Project SetUp

Create a new console application and add the following packages

dotnet add package Azure;
dotnet add package Azure.AI.OpenAI;
dotnet add package Microsoft.Agents.AI;
dotnet add package Microsoft.Extensions.AI;
dotnet add package StackExchange.Redis;
dotnet add package System.Text.Json.Serialization;
dotnet add package Microsoft.Extensions.Configuration;
dotnet add package Microsoft.Extensions.DependencyInjection;
dotnet add package Microsoft.Extensions.Logging;

Add appsetting.json to the project

"AppSettings": { 
    "Chat_DeploymentName": "Deployment Name",
    "EndPoint": "Azure OpenAI endpoint",
    "ApiKey": "Azure OpenAI API key"
}

Code

Once all the artifacts in place, add the following code to Program.cs

Program.cs >>

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Create a DI container

 ServiceCollection servicecollection = new ServiceCollection();

Read credentials and register Chatclient

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

servicecollection.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
   .AsIChatClient()
    )
);

Register ChatClientAgent in the DI container and build the Service Provider

servicecollection.AddSingleton<ChatClientAgent>();
ServiceProvider serviceprovider = servicecollection.BuildServiceProvider();

Fetch keyed IChatclient from the DI container

var _chatclient = new ChatClientAgent(serviceprovider.GetKeyedService<IChatClient>("ChatClient")).ChatClient;

Set SummarizingChatReducer properties

SummarizingChatReducer summaryReducer = new SummarizingChatReducer(
chatClient: _chatclient,
targetCount: 2,
threshold: 3);

Here, the targetCount is set to 2 and the threshold is set to 3. This means that the conversation can grow to 5 (2+3) messages before summarization is triggered. Once threshold reaches 5 (2+3), keep 2 (targetCount) most recent messages in its raw form and summarize all the messages.

ChatClientAgentOptions and ChatHistoryProvider

 var options = new ChatClientAgentOptions
 {
     ChatOptions = new ChatOptions
     {
         Instructions = "You are a helpful chat assistant."
     },
     ChatHistoryProvider = new RedisChatHistoryProvider(summarizingChatReducer: summaryReducer, targetCount: 2, threshold: 3)

 };

Why am I passing targetCount and threshold values to the constructor of CustomChatReducer(RedisChatHistoryProvider) when these values have been already configured for SummarizingChatReducer ?

This is because, SummarizingChatReducer does not expose targetCount and threshold as publicly accessible properties. Also I am passing summarizingChatReducer instance as constructor argument.

Agent and Session

 var agent = _chatclient.AsAIAgent(options);
 var agentsession = await agent!.CreateSessionAsync();

Define CustomChatHistoryProvider (RedisChatHistoryProvider)

RedisChatHistoryProvider.cs >>

Define properties of session state in a class called SessionState.

We have defined _targetCount , _threshold and _summarizingChatReducer because we want these properties to be part of InvokingContext through ProviderSessionState (explained later).These properties can be accessed through the ProvideChatHistoryAsync and StoreChatHistoryAsync methods.

   internal class SessionState
 {
     public int _targetCount { get; set; } = 0;

     public int _threshold { get; set; } = 0;

     public SummarizingChatReducer _summarizingChatReducer { get; set; } = null;

     [JsonPropertyName("Messages")]
     public List<ChatMessage> lstChatMessages { get; set; } = [];

     [JsonPropertyName("UserName")]
     public string UserName { get; set; } = "";
   
 }

Redis Connection >>

ConnectionMultiplexer redis = ConnectionMultiplexer.Connect("localhost:6379");
private IDatabase db;

RedisChatHistoryProvider Constructor >>

We create an instance of ProviderSessionState for storing and handling the SessionState.

private readonly Microsoft.Agents.AI.ProviderSessionState<SessionState> _sessionstate;

 public RedisChatHistoryProvider(Func<AgentSession, SessionState> initializer = null, string statekey = "", SummarizingChatReducer summarizingChatReducer = null, int targetCount = 0, int threshold = 0)
 {
     _sessionstate = new(initializer =>
     {
         db = redis.GetDatabase();        
         string messages = db.StringGet(statekey);

         return new SessionState
         {
             lstChatMessages = String.IsNullOrEmpty(messages) ? Enumerable.Empty<ChatMessage>().ToList() : JsonSerializer.Deserialize<List<ChatMessage>>(messages),
             _targetCount = targetCount,
             _threshold = threshold,
             _summarizingChatReducer = summarizingChatReducer,
             UserName = statekey

         };
     }
      , statekey = "Sachin"

    );
 }

I have hardcoded statekey value to "Sachin".You can use any other uniquely identifiable value for statekey.

In the above code, the constructor parameters targetCount, threshold ,summarizingChatReducer are respectively assigned to the Session state properties of _targetCount, _threshold and _summarizingChatReducer. This way these properties are now part of the InvokingContext of the overridden methods ProvideChatHistoryAsync and StoreChatHistoryAsync.

ProviderSessionState is used for initializing and persisting provider state in the session's StateBag. State(in our case it is SessionState object) is a inbuild session state management that maintains conversation history and is stored in the StateBag using the StateKey property as the key.

As mentioned earlier, we can use either of two approaches: store the entire conversation in Redis and retrieve only the relevant summarized/reduced messages when required or store only the summarized messages in Redis.

We will use the second approach, where we store only the summarized messages along with the number of messages specified by targetCount in Redis.

StoreChatHistoryAsync >>

  protected async override ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default)
  {
      var cntx = _sessionstate.GetOrInitializeState(context.Session);

      IEnumerable<ChatMessage> reducedMessages = new List<ChatMessage>();

      var allNewMessages = context.RequestMessages.Concat(context.ResponseMessages ?? []);
      cntx.lstChatMessages.AddRange(allNewMessages);
      
      var jsonSerializerOptions = new JsonSerializerOptions
      {
          WriteIndented = true,
          Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
      };

      if (cntx.lstChatMessages.Count >= cntx._targetCount + cntx._threshold)
      {
          
          reducedMessages = await cntx._summarizingChatReducer.ReduceAsync(cntx.lstChatMessages, cancellationToken);
          await db.StringSetAsync(cntx.UserName, System.Text.Json.JsonSerializer.Serialize(reducedMessages, jsonSerializerOptions));
      }
      else
      {
          await db.StringSetAsync(cntx.UserName, System.Text.Json.JsonSerializer.Serialize(cntx.lstChatMessages, jsonSerializerOptions));

      }

  }

In above code there are two lists : allNewMessages and reducedMessages

allNewMessages holds response and request messages which is then added to lstChatMessages of InvokedContext context declared as cntx.

var cntx = _sessionstate.GetOrInitializeState(context.Session);

IEnumerable<ChatMessage> reducedMessages = new List<ChatMessage>();

var allNewMessages = context.RequestMessages.Concat(context.ResponseMessages ?? []);

cntx.lstChatMessages.AddRange(allNewMessages); 

Recall that lstChatMessages is a property in the SessionState class

SerializationOption

   var jsonSerializerOptions = new JsonSerializerOptions
   {
       WriteIndented = true,
       Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
   };

Check if the conversation count is greatest than targetCount and threshold combined together, trigger the ReduceAsync method and save the reduced messages in Redis if not then save all the conversation messages to Redis

  if (cntx.lstChatMessages.Count >= cntx._targetCount + cntx._threshold)
  {
      reducedMessages = await cntx._summarizingChatReducer.ReduceAsync(cntx.lstChatMessages, cancellationToken);

      await db.StringSetAsync(cntx.UserName, System.Text.Json.JsonSerializer.Serialize(reducedMessages, jsonSerializerOptions));
  }
  else
  {
      await db.StringSetAsync(cntx.UserName, System.Text.Json.JsonSerializer.Serialize(cntx.lstChatMessages, jsonSerializerOptions));

  }

Prompts

I will first send the following five prompts together in a single session

Console.WriteLine(await agent.RunAsync(new ChatMessage(ChatRole.User, "My name is Sachin") { CreatedAt = DateTimeOffset.UtcNow, AuthorName = "Sachin" }, session: agentsession, new AgentRunOptions { AllowBackgroundResponses = true }) + "\n");//Prompt 1 

Console.WriteLine(await agent.RunAsync(new ChatMessage(ChatRole.User, "I live in India") { CreatedAt = DateTimeOffset.UtcNow, AuthorName = "Sachin" }, session: agentsession, new AgentRunOptions { AllowBackgroundResponses = true }) + "\n");//Prompt 2

Console.WriteLine(await agent.RunAsync(new ChatMessage(ChatRole.User, "I work in the IT industry") { CreatedAt = DateTimeOffset.UtcNow, AuthorName = "Sachin" }, session: agentsession, new AgentRunOptions { AllowBackgroundResponses = true }) + "\n"); //Prompt 3

Console.WriteLine(await agent.RunAsync(new ChatMessage(ChatRole.User, "I am a software developer") { CreatedAt = DateTimeOffset.UtcNow, AuthorName = "Sachin" }, session: agentsession, new AgentRunOptions { AllowBackgroundResponses = true }) + "\n");//Prompt 4 

Console.WriteLine(await agent.RunAsync(new ChatMessage(ChatRole.User, "I work mainly with C# and .NET") { CreatedAt = DateTimeOffset.UtcNow, AuthorName = "Sachin" }, session: agentsession, new AgentRunOptions { AllowBackgroundResponses = true }) + "\n"); //Prompt 5

Recall that we have set the values of targetCount and threshold to 2 and 3 respectively.

In the above case Prompt 5 and the agent response will be stored to Redis in its raw form while the rest of prompts are summarized.

In the image above 1 in red is the summarized text and 2 and 3 in red are the stored messages that are based on the targetCount value.

Execution

Conclusion

ChatSummarizer provides an effective way to manage conversation history by reducing a large number of messages into a concise summary while preserving the important and required context. This helps prevent conversation history from growing indefinitely and reduces the amount of data that needs to be stored and processed.This gives us a balance between retaining recent conversation details and maintaining a conversational context of older messages.

This helps improve memory efficiency, reduce token usage and there by maintain efficient and relevant context throughout longer conversations.

Thanks for reading !!!

You definitely wouldn't want an AIAgent to blindly invoke every available tool or function solely based on a user's prompt or simply because a user requested it. Instead there should be some solid guardrails in place to validate user permissions for invoking a given AIFunction. Before invoking a function, the agent should verify that the user has the required role or scope to perform the requested operation.

The conventional approach is to store user permissions in a database and retrieve them whenever a user logs in. While this works it would require maintaining a separate authorization store, keeping it synchronized with user identities on Entra and performing database lookups to determine user permissions.

But with Microsoft Entra ID , all the requisite roles and permissions are embedded directly into the access token as claims. Once the token has been validated the application can authorize tool calls based on these claims without querying an additional database.

This is more robust approach as the user details and permissions are already centralized in Entra and there is no need maintain custom permission tables or synchronization logic in a database.

UseCase

Lets use a hypothetical scenario. An AIAgent invokes two AIFunctions

• ReturnCountryCapital

• ReturnCityTemperature

There are two users

sachin.nandanwar @ azureguru.net and sachin_nandanwar @ azureguru.net

Though I am using Entra users in this example, the same approach can be extended to Entra groups. So instead of assigning roles to individual users you can assign them to groups allowing all group members to inherit the same permissions assigned to the Entra group that they are a member of.

sachin.nandanwar @ azureguru.net should have permissions to invoke both the AIFunctions (ReturnCountryCapital and ReturnCityTemperature) while sachin_nandanwar @ azureguru.net permissions should be limited to invoke only ReturnCountryCapital

SetUp

This article is heavily influenced by my article on Delegated Tokens and Application tokens wrt setting up role based access in Entra. You can refer to that article here.

But I would still cover the same steps from the above article in this article as well.

As mentioned earlier, there are two users

• (Sachin.Nand) sachin.nandanwar @ azureguru.net

• (Sachin Nandanwar) sachin_nandanwar @ azureguru.net

sachin.nandanwar @ azureguru.net will have full permissions to invoke both the AIFunctions (ReturnCountryCapital and ReturnCityTemperature) while sachin_nandanwar @ azureguru.net will have partial permissions limited to invoke only ReturnCountryCapital AIFunction

Ensure that Scalar set up is configured in your ASP.NET core project. For more details refer to my following article

https://www.azureguru.net/customize-scalar-UI-for-net-api

Also ensure that you have a thorough understanding of Minimal API's and implementation of ClaimPrincipal, Authentication and Authorization for Minimal API's. Please refer to my article below to have a better understanding of the topic.

https://www.azureguru.net/implementing-jwt-tokens-in-minimal-api-net-core

You can ignore the custom JWToken aspect from the above article as in that article the focus was on creating custom JWTokens.

The first step is to create a Service Principal. I created one called App Service Principal.

In the next step , click the Expose an API option. The format of the URI is api://{ApplicationId}.

ApplicationId is the Service Principal ClientId

Define a scope by clicking the Add a scope option.

I defined a scope with name temperature_capital.read and used that name across all other properties for the scope.

Scope temperature_capital.read will be referred in our code to generate access token for the service principal on behalf of the signed in user.

In the next step, click App roles >> Create app role

and define two app roles

• Temperature and Capital Read Role

• Capital Read Role

The Temperature and Capital Read role is assigned to users who require access to invoke both the ReturnCountryCapital and ReturnCityTemperature functions while the Capital Read role is assigned to users who only need access to invoke the ReturnCountryCapital function. Users with this role are denied permission to invoke the ReturnCityTemperature function.

Now that we have app roles and API's defined, in the next step , under API permissions , click Add a permission and select and add the API created in the previous step.

This might sound counterintuitive to see that we have to assign permissions for an API to the service principal that created that API in the first place. But that’s the way it is. Not doing so results in an Unauthorized access error.

The next step is to enable Assignment required property.

Browse to Entra ID >> Enterprise apps >> All applications

Select your application. In our case it is App Service Principal

Ensure that Assignment required? is set to Yes . By default it is No.

Navigate to Users and groups in the same page add click Add user/group

Click None Selected and search for the user/group to whom you want to grant Assignments.

I granted Temperature and Capital Read Role to the user Sachin Nand i.e. sachin.nandanwar @ azureguru.net

I then granted Capital Read Role to user sachin.nandanwar @ azureguru.net i.e. Sachin Nandanwar

Users assigned to a role is listed under Users and groups

Now that the set up and the required prerequisite is in place , lets move on to the code.

Code

Add the following references to your ASP.NET core project

dotnet add package Azure;
dotnet add package Azure.Core;
dotnet add package Microsoft.IdentityModel.Tokens;
dotnet add package Scalar.AspNetCore;
dotnet add package System.Security.Claims;
dotnet add package Microsoft.Agents.AI;
dotnet add package Azure.AI.OpenAI;
dotnet add package Microsoft.Extensions.AI;
dotnet add package System.Text.Json.Serialization;

Lets first set up the Scalar API interface.

Scalar.cs >>

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;

internal sealed class BearerSecuritySchemeTransformer : IOpenApiDocumentTransformer
{
    private readonly IAuthenticationSchemeProvider _authenticationSchemeProvider;

    public BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider)
    {
        _authenticationSchemeProvider = authenticationSchemeProvider;
    }

    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        var authenticationSchemes = await _authenticationSchemeProvider.GetAllSchemesAsync();

        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
        {
            document.Components ??= new OpenApiComponents();
            document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();
            document.Components.SecuritySchemes["Bearer"] = new OpenApiSecurityScheme
            {
                Type = SecuritySchemeType.Http,
                Scheme = "bearer",
                In = ParameterLocation.Header,
                BearerFormat = "JWT"
            };

            foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
            {
                if (operation.Value.Security == null)
                {
                    operation.Value.Security = new List<OpenApiSecurityRequirement>();
                }
                var securityRequirement = new OpenApiSecurityRequirement
                {
                    [new OpenApiSecuritySchemeReference("Bearer", document)] = []
                };

                operation.Value.Security ??= new List<OpenApiSecurityRequirement>();
                operation.Value.Security.Add(securityRequirement);
            }
        }
    }
}

Scalar UI >>

 builder.Services.AddOpenApi(
    options =>
    {
        options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
    }
);

WebApplication app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapScalarApiReference(
    options =>
    {
        options.Title = "Scalar API";
        options.DarkMode = true;
        options.Favicon = "path";
        options.DefaultHttpClient = new KeyValuePair<ScalarTarget, ScalarClient>(
            ScalarTarget.CSharp,
            ScalarClient.RestSharp
        );
        options.HideModels = false;
        options.Layout = ScalarLayout.Modern;
        options.ShowSidebar = true;
        options.Authentication = new ScalarAuthenticationOptions
        {
            PreferredSecuritySchemes = new List<string> { "Bearer" }
        };
    }
);

The above code customizes the Scalar UI to include the Bearer token section.

For more details refer to my article on the topic here.

Next , define an Authentication class that validates the user's sign-in and requested scopes with Microsoft Entra ID and then returns a JWT token.

Unlike implementing custom JWT tokens which I demonstrated in my earlier article here, with Microsoft Entra ID-issued tokens there is no need for generating, signing, rotating or validating JWTs ourselves. Microsoft Entra ID auto handles all these aspects at its end.

Authentication.cs >>

    using Microsoft.Identity.Client;
    using System.IdentityModel.Tokens.Jwt;

    namespace Security
    {
        internal class Authentication
        {
            public static string clientId = "Service Principal Client Id";
            private static string[] scopes = { $"api://{clientId}/.default" };
            private static string Authority = "https://login.microsoftonline.com/organizations";
            private static string RedirectURI = "http://localhost";

            public async static Task<JwtSecurityToken> ReturnAuthenticationResult()
            {
                string AccessToken;
                IPublicClientApplication PublicClientApplication = PublicClientApplicationBuilder
                    .Create(clientId)
                    .WithAuthority(Authority)
                    .WithCacheOptions(CacheOptions.EnableSharedCacheOptions)
                    .WithRedirectUri(RedirectURI)
                    .Build();

                var accounts = await PublicClientApplication.GetAccountsAsync();
                AuthenticationResult result;

                try
                {
                    result = await PublicClientApplication
                        .AcquireTokenSilent(scopes, accounts.First())
                        .ExecuteAsync()
                        .ConfigureAwait(false);
                }
                catch
                {
                    result = await PublicClientApplication
                        .AcquireTokenInteractive(scopes)
                        .ExecuteAsync()
                        .ConfigureAwait(false);
                }

                JwtSecurityToken token = new JwtSecurityToken(result.AccessToken);
                return token;
            }
        }
    }

For brevity, I have defined ClientId as a variable. Ideally it should be placed in a config file or as an Environment variable

Scope used is : api://{Service Principal ClientId}/.default for the claims token.

Next, add the following code in Program.cs to read settings from the config file appsettings.json

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Read credentials and register Chatclient and return a ChatClientAgent

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

servicecollection.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)
                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
   .AsIChatClient()
    )
);

builder.Services.AddSingleton<ChatClientAgent>(sp =>
{
    return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"));
});

Authentication >>

builder.Services.AddAuthentication().AddJwtBearer(options =>
       {
           options.Authority = $"https://login.microsoftonline.com/{TenantId}";
           options.Validate();
           options.MapInboundClaims = false;
           options.TokenValidationParameters = new TokenValidationParameters
           {
               ValidIssuer = $"https://sts.windows.net/{TenantId}/",
               ValidAudience = $"api://{ClientId}",
               ValidateIssuer = true,
               ValidateAudience = true
           };
       });

Authentication mechanism is used to validate the incoming tokens. It checks for two parameters, ValidIssuer and ValidAudience and ensures that the values for these parameters in the bearer token matches with

• https://sts.windows.net/{TenantId}/ and api://{ClientId}

• options.MapInboundClaims = false . This setting is very important wrt validating the claims . Check the following screenshot

  

The claims and the scope format above is a standard JWT format. If options.MapInboundClaims = true (which the default) , the claim check through will fail . For example something like

var roles = claims.FindFirst("roles")?.Value

roles will always be null as it checks for the keyword "roles"

But setting options.MapInboundClaims = false the format changes

Authorization >>

builder.Services.AddAuthorization(options =>
  {
      options.AddPolicy("CapitalTemperatureReadAccess", policy =>
      {
          policy.RequireAuthenticatedUser();
          policy.RequireClaim("aud", $"api://{ClientId}");
          policy.RequireClaim("iss", $"https://sts.windows.net/{TenantId}/");
          policy.RequireClaim("scp", "temperature_capital.read");             

      });
  });

Create an authorization policy but before that ensure that request contains authenticated users and then check if the claims contain "aud", "scp", "iss" and validate its values.

Next, define Request and Response objects for Temperature and Capital searches

CityTemperatureSearchRequest & CityTemperatureSearchResponse >>

 public class CityTemperatureSearchRequest
 {
     public string City { get; set; }
 }

 public class CityTemperatureSearchResponse
 {
     public string City { get; set; }
     public string Temperature { get; set; }
 }

CountryCapitalSearchRequest & CountryCapitalSearchResponse >>

 public class CountryCapitalSearchRequest
 {
     public string Country { get; set; }
 }

 public class CountryCapitalSearchResponse
 {
     public string Country { get; set; }
     public string Capital { get; set; }
 }

Next, create serialization metadata for both request and response types.

[JsonSerializable(typeof(CountryCapitalSearchRequest))]
[JsonSerializable(typeof(CountryCapitalSearchResponse))]
internal sealed partial class CountryCapitalSerializerContext : JsonSerializerContext;


[JsonSerializable(typeof(CityTemperatureSearchRequest))]
[JsonSerializable(typeof(CityTemperatureSearchResponse))]
internal sealed partial class CityTemperatureSerializerContext : JsonSerializerContext;

Define a delegate named ReturnCityTemperature that takes a search request CityTemperatureSearchRequest as input and returns a search response CityTemperatureSearchResponse.

   public static Func<CityTemperatureSearchRequest, CityTemperatureSearchResponse> ReturnCityTemperature = (CityTemperatureSearchRequest) =>

    {
        switch (CityTemperatureSearchRequest.City)
        {

            case "Mumbai":

                return new CityTemperatureSearchResponse
                {

                    City = "Mumbai",
                    Temperature = "40"
                };

                break;

            case "Pune":

                return new CityTemperatureSearchResponse
                {

                    City = "Pune",
                    Temperature = "41"
                };

                break;

            case "Delhi":

                return new CityTemperatureSearchResponse
                {

                    City = "Delhi",
                    Temperature = "42"
                };

                break;

            case "Chennai":

                return new CityTemperatureSearchResponse
                {

                    City = "Chennai",
                    Temperature = "43"
                };
                break;

        }

        return new CityTemperatureSearchResponse
        {

            City = CityTemperatureSearchRequest.City,
            Temperature = "Unknown"
        };

    };

Similarly, define a delegate named ReturnCountryCapital that takes a search request CountryCapitalSearchRequest as input and returns a search response CountryCapitalSearchResponse.

    public static Func<CountryCapitalSearchRequest, CountryCapitalSearchResponse> ReturnCountryCapital = (CountryCapitalSearchRequest) =>

       {
           switch (CountryCapitalSearchRequest.Country)
           {

               case "India":

                   return new CountryCapitalSearchResponse
                   {

                       Country = "India",
                       Capital = "New Delhi"
                   };
                   break;

               case "USA":

                   return new CountryCapitalSearchResponse
                   {

                       Country = "USA",
                       Capital = "Washington"
                   };
                   break;


               case "Germany":

                   return new CountryCapitalSearchResponse
                   {

                       Country = "Germany",
                       Capital = "Berlin"
                   };
                   break;

               case "Russia":

                   return new CountryCapitalSearchResponse
                   {

                       Country = "Russia",
                       Capital = "Moscow"
                   };
                   break;
           }

           return new CountryCapitalSearchResponse
           {

               Country = CountryCapitalSearchRequest.Country,
               Capital = "Unknown"
           };

       };
}

Register the above two delegates in the DI container as AIFunction with the corresponding SerializerOptions defined earlier.

  builder.Services.AddSingleton<AIFunction>(sp =>
     {
         return AIFunctionFactory.Create(ReturnCountryCapital, new AIFunctionFactoryOptions { Name = "ReturnCountryCapital", Description = "Gets the capital city for a specific country.", SerializerOptions = CountryCapitalSerializerContext.Default.Options });
     });


  builder.Services.AddSingleton<AIFunction>(sp =>
    {
        return AIFunctionFactory.Create(ReturnCityTemperature, new AIFunctionFactoryOptions { Name = "ReturnCityTemperature", Description = "Gets the temperature of a city", SerializerOptions = CityTemperatureSerializerContext.Default.Options });
    });

Login Endpoint >>

Here we fetch the access token issued by Entra ID which is part of the OIDC flow.

app.MapPost("/login", async() =>
{
tokens = await Security.Authentication.ReturnAuthenticationResult();
return Results.Ok(tokens);
}).WithOpenApi();

Chat Endpoint >>

app.MapGet("/chat", async (string request, ClaimsPrincipal claims) =>
 {
     var aud = claims.FindFirst("aud").Value;
     var issuer = claims.FindFirst("iss").Value;
     var roles = claims.FindFirst("roles").Value;
     var scp = claims.FindFirst("scp").Value;

     var chatclientlist = app.Services.GetRequiredKeyedService<IChatClient>("ChatClient");

     var aifunctions = app.Services.GetServices<AIFunction>();

     List<AITool> functions = new(aifunctions);

     if (aud == $"api://{ClientId}" && issuer == $"https://sts.windows.net/{TenantId}/")
     {
         var options = new ChatClientAgentOptions
         {
                 ChatOptions = new ChatOptions
                 {

                     Tools = functions
                 }
             };
         

         if (roles == "TemperatureCapital.Read" && scp == "temperature_capital.read")
         {
             options.ChatOptions.Instructions = "You return capital city of a country and you also provide temperature of a city.You will use only the data provided to you and not use any external data";

         }

         if (roles == "Capital.Read" && scp == "temperature_capital.read")
         {

             options.ChatOptions.Instructions = "You return ONLY the capital city of a country and if user asks for temperature you respond 'You are not are authorized to access temperature data'. You will use only the data provided to you and not use any external data";
         }

         var agent = chatclientlist.AsAIAgent(options);

         AgentResponse response = await agent.RunAsync(request);

         return Results.Ok(response.Text);
     }

     return Results.Unauthorized();

 }).RequireAuthorization("CapitalTemperatureReadAccess");

Let's break down the above code step by step.

Fetch audience, iss(issuer), scp(scopes) and roles values from claims.

var aud = claims.FindFirst("aud").Value;
var issuer = claims.FindFirst("iss").Value;
var roles = claims.FindFirst("roles").Value;
var scp = claims.FindFirst("scp").Value;

Retrieve IChatClient keyed service and AIFunction from the service collection and set it to the functions list variable of type List

var chatclientlist = app.Services.GetRequiredKeyedService<IChatClient>("ChatClient");

var aifunctions = app.Services.GetServices<AIFunction>();

List<AITool> functions = new(aifunctions);

Validate issuer and audience and if validated create ChatClientAgentOptions and set the Tools to the above functions list.

 if (aud == $"api://{ClientId}" && issuer == $"https://sts.windows.net/{TenantId}/")
 {
     var options = new ChatClientAgentOptions
     {
             ChatOptions = new ChatOptions
             {
                 Tools = functions
             }
         };     

     if (roles == "TemperatureCapital.Read" && scp == "temperature_capital.read")
     {
         options.ChatOptions.Instructions = "You return capital city of a country and you also provide temperature of a city.You will use only the data provided to you and not use any external data";

     }

     if (roles == "Capital.Read" && scp == "temperature_capital.read")
     {

         options.ChatOptions.Instructions = "You return ONLY the capital city of a country and if user asks for temperature you respond 'You are not are authorized to access temperature data'. You will use only the data provided to you and not use any external data";
     }

     var agent = chatclientlist.AsAIAgent(options);
     AgentResponse response = await agent.RunAsync(request);
     return Results.Ok(response.Text);
 }

 return Results.Unauthorized();

Then validate roles and scopes values . If roles is TemperatureCapital.Read then set ChatOptions instructions to return both capital of the country and temperature of the city and if the roles is Capital.Read then set ChatOptions instructions to return only the capital and deny any other requests with a custom message 'You are not are authorized to access temperature data'.

Assign ChatOptions to agent derived from IChatClient and send the prompt to the agent and return the response.

And if the validations fail, return an Unauthorized error.

Login as : sachin.nandanwar @ azureguru.net and send the following prompt

What is capital of India and whats the temperature in Mumbai ?

Login as : sachin.nandanwar @ azureguru.net and send the the same prompt

and the access to the temperature data is denied.

Execution

Closing Notes

Instead of building a separate security layer for your AIAgents to handle permissions for AIFunction invocation , leveraging user claims through Entra issued OAuth tokens can be more robust ,clean and maintainable architecture.

With this architecture you get a centralized control over permissions required for user driven agent function invocation which ensures that users can invoke only the functions they are permitted to access.

Thanks for reading !!!

In this example I am going to demonstrate how to leverage OpenID Connect (OIDC) to enable an AI agent to securely access Azure Storage through an ASP.NET Core Minimal API by validating the underlying OIDC claims and also enforcing permissions.

But why minimal API's ?

Honestly, I couldn't figure out a straightforward approach to leverage AG-UI protocol to pass OAuth 2.0 access token back to the server.

If you would like to know more about AG-UI protocol in Microsoft Agent Framework , then you can refer to my article on the topic here.

In this article, I will use Scalar UI as the API interface which I have done in most of my previous articles on Minimal API's. The article here is a deep dive on how to leverage it.

So the aim is to access list of directories in an Azure storage container based on the user identity and prompted through Microsoft Agent Framework (MAF) AI Agent provided the signed-in user user has the required RBAC role access to the Azure storage. The agent uses OAuth 2.0 access tokens issued on behalf of the signed-in user. The Azure storage is an ADLS GEN2 storage.

Flow

SetUp

To add more context to the above flow, the scope used is

https://storage.azure.com/

The ADLS GEN2 storage has the following structure

The expectation from the code is that it should be capable of recursively traversing all directories within a container prompted through the AI Agent. As shown in the screenshot above, the customers container contains directories that are nested up to three levels deep and this structure can be dynamic.

So, there are two users :

• sachin.nandanwar @ azureguru.net

• sachin_nandanwar @ azureguru.net

sachin.nandanwar@azureguru.net is assigned the necessary RBAC role accesses to the storage. Typically it has to be Storage Blob Data Owner role.

You could also grant Storage Blob Data Contributor role but the Storage Blob Data Owner role has POSIX access control (ACL access) that auto grants all the (r-w-x) privileges to the owner for all the underlying objects under the container.

For instance in the following screenshot we can see that the owner i.e. the Storage Blob Data Owner was auto assigned the (r-w-x) access .

sachin_nandanwar @ azureguru.net is not assigned any RBAC role.

Create a Service Principal and grant Azure Storage delegated permissions.

I created one named ADLS GEN2 Service Principal.

Ensure that you the Scalar set up is configured in your ASP.NET core project. For more details refer to my following article

https://www.azureguru.net/customize-scalar-UI-for-net-api

Also ensure that you have a thorough understanding of Minimal API's and implementation of ClaimPrincipal, Authentication and Authorization for Minimal API's. Please refer to my article to have a better understanding of the topic.

https://www.azureguru.net/implementing-jwt-tokens-in-minimal-api-net-core

You can ignore the custom JWToken aspect from the above article as in that article the focus was on creating custom JWTokens.

Code

Add the following references to your ASP.NET core project

dotnet add package Azure.Core;
dotnet add Azure.AI.OpenAI;
dotnet add package Azure.Storage.Files.DataLake;
dotnet add package Microsoft.IdentityModel.Tokens;
dotnet add package Scalar.AspNetCore;
dotnet add package System.Security.Claims;
dotnet add Microsoft.Extensions.AI;
dotnet add Microsoft.Extensions.Configuration;
dotnet add Microsoft.Extensions.DependencyInjection;
dotnet add Microsoft.Extensions.Hosting;

First, we define an Authentication class that validates the user's sign-in and requested scopes with Microsoft Entra ID and then returns a Entra JWT token .

Unlike implementing custom JWT tokens which I demonstrated in my earlier article here, with Microsoft Entra ID-issued tokens there is no need for generating, signing, rotating or validating JWTs ourselves. Microsoft Entra ID auto handles all these aspects at its end.

Authentication.cs >>

using Microsoft.Identity.Client;
using System.IdentityModel.Tokens.Jwt;

namespace Security
{
    internal class Authentication
    {
        public static string clientId = "Service Principal Client Id";
        private static string[] scopes = { "https://storage.azure.com/.default" };
        private static string Authority = "https://login.microsoftonline.com/organizations";
        private static string RedirectURI = "http://localhost";

        public async static Task<JwtSecurityToken> ReturnAuthenticationResult()
        {
            string AccessToken;
            IPublicClientApplication PublicClientApplication = PublicClientApplicationBuilder
                .Create(clientId)
                .WithAuthority(Authority)
                .WithCacheOptions(CacheOptions.EnableSharedCacheOptions)
                .WithRedirectUri(RedirectURI)
                .Build();

            var accounts = await PublicClientApplication.GetAccountsAsync();
            AuthenticationResult result;

            try
            {
                result = await PublicClientApplication
                    .AcquireTokenSilent(scopes, accounts.First())
                    .ExecuteAsync()
                    .ConfigureAwait(false);
            }
            catch
            {
                result = await PublicClientApplication
                    .AcquireTokenInteractive(scopes)
                    .ExecuteAsync()
                    .ConfigureAwait(false);
            }

            JwtSecurityToken token = new JwtSecurityToken(result.AccessToken);
            return token;
        }
    }
}

For brevity I have defined ClientId and other details in variables. Ideally they should be placed in a config file and their values fetched from there.

AccessTokenCredential.cs >>

using Azure.Core;
using System.IdentityModel.Tokens.Jwt;

namespace AccesTokenCredentials
{
    public class AccessTokenCredential : Azure.Identity.ClientSecretCredential
    {
        public AccessTokenCredential(string accessToken)
        {
            AccessToken = accessToken;
        }

        private string AccessToken;

        public AccessToken FetchAccessToken()
        {
            JwtSecurityToken token = new JwtSecurityToken(AccessToken);
            return new AccessToken(AccessToken, token.ValidTo);
        }

        public override ValueTask<AccessToken> GetTokenAsync(
            TokenRequestContext requestContext,
            CancellationToken cancellationToken
        )
        {
            return new ValueTask<AccessToken>(FetchAccessToken());
        }

        public override AccessToken GetToken(
            TokenRequestContext requestContext,
            CancellationToken cancellationToken
        )
        {
            JwtSecurityToken token = new JwtSecurityToken(AccessToken);
            return new AccessToken(AccessToken, token.ValidTo);
        }
    }
}

The above class converts bearer tokens to TokenCredentials. We will require TokenCredentials for authenticating DataLakeServiceclient and return the directory structure for the ADLS Gen2 storage.

For more information as to why this is required, please refer to the following article https://www.azureguru.net/customize-clientsecretcredential-class-for-onelake-authentication-in-microsoft-fabric

Add appsetting.json to the project

"AppSettings": { 
    "Chat_DeploymentName": "Deployment Name",
    "EndPoint": "Azure OpenAI endpoint",
    "ApiKey": "Azure OpenAI API key"
}

In launchSettings.json, configure the ports on which the server should listen.

{
    "$schema": "https://json.schemastore.org/launchsettings.json",
    "profiles": {       
        "https": {
            "commandName": "Project",
            "dotnetRunMessages": true,
            "launchBrowser": false,
            "applicationUrl": "https://localhost:7129;http://localhost:5176",
            "environmentVariables": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            }
        }
    }
}

In the above settings , the application is configured to listen on ports 7129 (HTTPS) and 5176 (HTTP). For this article, we will use 7129 on https.

Code

Now that we have all the underlying artifacts in place, add the following code to read the settings from appsettings.json in Program.cs

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Create a application builder

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

Create a IChatClient DI container

builder.Services.AddHttpClient().AddLogging();

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

builder.Services.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)
                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
                .AsIChatClient()
    )
);

builder.Services.AddSingleton<ChatClientAgent>(
    sp =>
    {
        return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"));
    }
);

AIFunction

Register an AIFunction with name ReturnDirectories in the DI container. I am using FunctionInvokingChatClient to pass the access token as the parameter to the AIFunction.

builder.Services.AddSingleton<AIFunction>(
    sp =>
    {
        return AIFunctionFactory.Create(
            async (string ContainerName) =>
                await ReturnContainerDirectories(
                    ContainerName,
                    FunctionInvokingChatClient.CurrentContext.Options.AdditionalProperties[
                        "AccessToken"
                    ].ToString()
                ),
            new AIFunctionFactoryOptions
            {
                Name = "ReturnDirectories",
                Description = "Returns a list of directories"
            }
        );
    }
);

For more details on FunctionInvokingChatClient you can refer to my article here.

Authentication

Authentication mechanism validates the incoming tokens. In this example it checks for two parameters, ValidIssuer and ValidAudience and ensures that the values for these parameters in the bearer token matches with

• https://sts.windows.net/{TenantId}/ and https://storage.azure.com

and if the claim does not match it rejects the token.

builder.Services.AddAuthentication().AddJwtBearer(options =>
{
    options.Authority = $"https://login.microsoftonline.com/{TenantId}";
    options.Validate();

    options.TokenValidationParameters = new TokenValidationParameters
    {
         ValidIssuer = "https://sts.windows.net/{TenantId}/",
         ValidAudience = "https://storage.azure.com",
         ValidateIssuer = true,
         ValidateAudience = true
    };
});

Authorization

Create an authorization policy but before that ensure that request contains authenticated users and then check if the claims contain "aud" and "iss" and then validate its values.

 builder.Services.AddAuthorization(options =>
 {
     options.AddPolicy("AzureStorageAccess", policy =>
     {
         policy.RequireAuthenticatedUser();
         policy.RequireClaim("aud", "https://storage.azure.com");
         policy.RequireClaim("iss", $"https://sts.windows.net/{TenantId}/");
     });
 });

Scalar.cs

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;

internal sealed class BearerSecuritySchemeTransformer : IOpenApiDocumentTransformer
{
    private readonly IAuthenticationSchemeProvider _authenticationSchemeProvider;

    public BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider)
    {
        _authenticationSchemeProvider = authenticationSchemeProvider;
    }

    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        var authenticationSchemes = await _authenticationSchemeProvider.GetAllSchemesAsync();

        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
        {
            document.Components ??= new OpenApiComponents();
            document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();
            document.Components.SecuritySchemes["Bearer"] = new OpenApiSecurityScheme
            {
                Type = SecuritySchemeType.Http,
                Scheme = "bearer",
                In = ParameterLocation.Header,
                BearerFormat = "JWT"
            };

            foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
            {
                if (operation.Value.Security == null)
                {
                    operation.Value.Security = new List<OpenApiSecurityRequirement>();
                }
                var securityRequirement = new OpenApiSecurityRequirement
                {
                    [new OpenApiSecuritySchemeReference("Bearer", document)] = []
                };

                operation.Value.Security ??= new List<OpenApiSecurityRequirement>();
                operation.Value.Security.Add(securityRequirement);
            }
        }
    }
}

Scalar UI

 builder.Services.AddOpenApi(
    options =>
    {
        options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
    }
);

WebApplication app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapScalarApiReference(
    options =>
    {
        options.Title = "Scalar API";
        options.DarkMode = true;
        options.Favicon = "path";
        options.DefaultHttpClient = new KeyValuePair<ScalarTarget, ScalarClient>(
            ScalarTarget.CSharp,
            ScalarClient.RestSharp
        );
        options.HideModels = false;
        options.Layout = ScalarLayout.Modern;
        options.ShowSidebar = true;
        options.Authentication = new ScalarAuthenticationOptions
        {
            PreferredSecuritySchemes = new List<string> { "Bearer" }
        };
    }
);

The above code customizes the Scalar UI to include the Bearer token section.

Register the OpenAPI service in the DI container add a Scalar document transformer.

builder.Services.AddOpenApi(options =>
 {     options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
 });

For more details refer to my article on the topic here.

ReturnContainerDirectories Function

This function contains arguments container name and token.The token value is passed to the TokenCredential object of the DatalakeServiceClient which then eventually returns the directory structure for the Azure container through the TraverseDirectory function.

public static Func<string, string, Task<List<string>>> ReturnContainerDirectories = async (
    ContainerName,
    token
) =>
{
    DataLakeServiceClient datalake_Service_Client;
    DataLakeFileSystemClient dataLake_FileSystem_Client;
    string dfsUri = $"https://adlsfilestore.dfs.core.windows.net";
    TokenCredential tokenCredential = new AccessTokenCredential(token.ToString());
    datalake_Service_Client = new DataLakeServiceClient(new Uri(dfsUri), tokenCredential);
    dataLake_FileSystem_Client = datalake_Service_Client.GetFileSystemClient(ContainerName);
    DataLakeDirectoryClient rootDirectory_ = dataLake_FileSystem_Client.GetDirectoryClient("");
    listoutput.Clear();

    return await TraverseDirectory(rootDirectory_);
};

TraverseDirectory

The function recursively traverses the directory structure of a given Azure container . For more in-depth details on the approach you can refer to my article

https://www.azureguru.net/retrieve-the-hierarchical-directory-structure-from-azure-adls-gen2-storage

public static async Task<List<string>> TraverseDirectory(DataLakeDirectoryClient directoryClient)
{

    await foreach (var item in directoryClient.GetPathsAsync())
    {
        if (item.IsDirectory == true)
        {
            listoutput.Add(item.Name);
            string[] split = item.Name.Split("/");
            var subDir = directoryClient.GetSubDirectoryClient(split.Length == 1 ? split[0] : split[split.Length - 1]);
            await TraverseDirectory(subDir);
        }
    }

    return listoutput;
}

Login Endpoint

The access token issued by Entra ID which is part of the OIDC flow and is passed to this endpoint.

app.MapPost("/login", () =>
{
return Results.Ok(new { token = Security.Authentication.ReturnAuthenticationResult() });
}).WithOpenApi();

Chat Endpoint

The chat endpoint is the most crucial piece of code.

app.MapGet("/chat", async (string request, HttpContext httpcontext, ClaimsPrincipal claims) =>
 {
     var aud = claims.FindFirst("aud").Value;
     var issuer = claims.FindFirst("iss").Value;
     var chatclientlist = app.Services.GetRequiredKeyedService<IChatClient>("ChatClient");

     var aifunctions = app.Services.GetServices<AIFunction>();

     List<AITool> functions = new(aifunctions);

     if (aud == "https://storage.azure.com" && issuer == $"https://sts.windows.net/{TenantId}/")
     {
         var agent = chatclientlist.AsAIAgent(new ChatClientAgentOptions
         {
             ChatOptions = new ChatOptions
             {
                 Tools = functions,
                 Instructions = "You return list of Azure directories for the given container",
                 AdditionalProperties = new AdditionalPropertiesDictionary {["AccessToken"] = httpcontext.Request.Headers["Authorization"].ToString().Replace("Bearer ", "") }
             }
         }
            );
         AgentResponse response = await agent.RunAsync(request);              

         return Results.Ok(response.Text);
     }

     return Results.Unauthorized();

 }).RequireAuthorization("AzureStorageAccess");

app.Run();

Let's break down the code step by step.

First, retrieve the audience and issuer values from JWT claims.

var aud = claims.FindFirst("aud").Value;
var issuer = claims.FindFirst("iss").Value;

Then, retrieve a service of type IChatClient from the DI container that was registered earlier.

var chatclientlist = app.Services.GetRequiredKeyedService<IChatClient>("ChatClient");

Get a list of all AIFunction from the DI container. In our case we only have one AIFunction i.e ReturnDirectories.

var aifunctions = app.Services.GetServices<AIFunction>();
List<AITool> functions = new(aifunctions);

Validate the aud and issuer(iss) values. Then create an AIAgent from the IChatClient instance chatclientlist declared earlier.

Next, configure ChatOptions with Tools and set AdditionalProperties AccessToken that is derived from HttpContext. AdditionalProperties values are accessed through FunctionInvokingChatClient in the AIFunction.

Pass the request to the agent and return the response.

if (aud == "https://storage.azure.com" && issuer == $"https://sts.windows.net/{TenantId}/")
{
    var agent = chatclientlist.AsAIAgent(
        new ChatClientAgentOptions
        {
            ChatOptions = new ChatOptions
            {
                Tools = functions,
                Instructions = "You return list of Azure directories for the given container",
                AdditionalProperties = new AdditionalPropertiesDictionary
                {
                    ["AccessToken"] = httpcontext.Request.Headers["Authorization"]
                        .ToString()
                        .Replace("Bearer ", "")
                }
            }
        }
    );
    AgentResponse response = await agent.RunAsync(request);

    return Results.Ok(response.Text);
}

I first logged in as sachin.nandanwar @ azureguru.net and passed the following prompt to the agent.

Give me list of directories from the container customers.

the agent returns the list of all the directories in the customers container.

But when I logged in as sachin_nandanwar @ azureguru.net as expected, the access to the directories was restricted.

Execution

Conclusion

By combining the Microsoft Agent Framework with Microsoft Entra ID, you can build AI agents that securely access Azure services.

The agent uses OAuth 2.0 access tokens issued on behalf of the signed-in user that ensures that every operation is performed within the user's identity and the user RBAC permissions.

Thanks for reading !!!

So how to access Azure services with federated credentials that are tied with User Managed Identities ? Even I was skeptical if it is even possible because its more common and widely known that federated identity credentials (OIDC federation) are tied with service principal and not managed identities.

In this article I am going to delve into details on how to achieve this. But before that I strongly recommend reading the following article

https://www.azureguru.net/configuring-federated-credentials-in-microsoft-azure-using-github-actions

that I published last year, which provides a detailed walkthrough of configuring federated credentials using GitHub actions as IdP (Identity Provider) through service principal.

Before we set up and test GitHub actions lets first ensure that a defined User Managed Identity can access the Azure ADLS GEN2 storage. For that lets create an Azure Function and use an user managed identity in the Azure Function to access Azure storage.

User Managed Identity

Create a new user managed identity or use an existing one. I created one with name Federated_Credentials_Function_Identity .

In the next step grant role access Storage Blob Data Owner to the created Managed Identity that needs access to the Azure storage.

You could also grant Storage Blob Data Contributor role but the Storage Blob Data Owner role has POSIX access control (ACL access) that auto grants all the (r-w-x) privileges to the owner for all the underlying objects under the container.

For instance in the following screenshot we can see that the owner i.e. the Storage Blob Data Owner was auto assigned the (r-w-x) access .

Note down the ClientID of the created User Managed Identity. We will need it to reference in our Azure Function.

Azure Function Code

Create a new Azure function and add the following code.

Before that ensure that you have added all the required project references.

using Azure.Identity;
using Azure.Storage.Files.DataLake;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace AzureFunction;

public class Function1
{
    private readonly ILogger<Function1> _logger;
    public static List<string> listoutput = new();

    public Function1(ILogger<Function1> logger)
    {
        _logger = logger;
    }

    [Function("Function1")]
    public async Task<OkObjectResult> Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req)
    {
        {
            string storageAccount = "Storage Account";
            string fileSystemName = "Storage Container";           
            string userAssignedClientId = "Managed Identity ClientID";
            DataLakeServiceClient datalake_Service_Client;
            DataLakeFileSystemClient dataLake_FileSystem_Client;
            try
            {
                string dfsUri = $"https://{storageAccount}.dfs.core.windows.net";

                var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions
                {
                    ManagedIdentityClientId = userAssignedClientId,
                    
                });

                datalake_Service_Client = new DataLakeServiceClient(new Uri(dfsUri), credential);
                dataLake_FileSystem_Client = datalake_Service_Client.GetFileSystemClient(fileSystemName);
                DataLakeDirectoryClient rootDirectory_ = dataLake_FileSystem_Client.GetDirectoryClient("");
                listoutput.Clear();

                return new OkObjectResult(new
                {
                    Output = TraverseDirectory(rootDirectory_)
                });
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error accessing ADLS Gen2");

            }

            return new OkObjectResult("");

        }

    }

    public static async Task<List<string>> TraverseDirectory(DataLakeDirectoryClient directoryClient)
    {

        await foreach (var item in directoryClient.GetPathsAsync())
        {
            if (item.IsDirectory == true)
            {
                listoutput.Add(item.Name);
                string[] split = item.Name.Split("/");
                var subDir = directoryClient.GetSubDirectoryClient(split.Length == 1 ? split[0] : split[split.Length - 1]);
                await TraverseDirectory(subDir);
            }
        }

        return listoutput;
    }
}

The above code returns only the top level directories of the given container. It is a simplified version of the code from the article here that recursively returns hierarchical directory structure for a given Azure storage container.

Deploy the above code to Azure, execute it and verify that it returns all the subdirectories within the specified container.

Following is the output from the execution of the Azure function.

Now that Federated_Credentials_Function_Identity which is an User Managed Identity can access the Azure storage , in the next step we can go ahead and create federated credentials tied to this specific User Managed Identity.

Go back to the created User Managed Identity on the Azure portal and click Federated Credentials option followed by Add Credentials .

In the next window, select GitHub Actions deploying Azure resources option under Federated credential scenarios.

In the next step, enter the following details on Edit Federated Credential page

• Organization is the username or organization name of the repo

• Repository is the name of the repository that you want to use. By default it also will be the name of the Federated Credentials.

• Entity is the type of entity. Following are the available options .

• Branch specifies the repo branch through which the request would be trusted by federated credentials.

• Audience keep it to default

Click Update and double check if the Federated Credential is created.

In this example the Federated Credentials is named GitHubActions

We now need to set the environment variables for the GitHub repository.

Go to the GitHub repository and under Secrets and variables

and under Actions declare the following Repository secrets that you see in the screenshot below and enter their corresponding values

Fetch the values for Azure_Client_ID and Azure_Subscription_ID from the User Managed Identity that was set for GitHub actions. The value for secret Azure_Tenant_Id will be the Azure Tenant Id.

The Azure_Storage_Account value should be the ADLS Gen2 storage account from which you want to retrieve the directory structure.

In next step , Go to the GitHub repo and under Actions select New WorkFlow

and then under Simple Workflow click Configure

and add the following code to the *. yml file. In this example the file is named Workflow.yml

name: GitHubActions Azure Federated Credentials Demo

on:
  push:
    branches:
      - main

jobs:
  auth-azure:
    runs-on: ubuntu-latest

    permissions:
      id-token: write    
      contents: read

    steps:
      - name: 'Login to Azure with OIDC federated credentials'
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Show success message
        run: echo "Successfully authenticated for Azure using federated credentials!"

      - name: Get List of Folders
        uses: azure/cli@v2
        with:
          azcliversion: latest
          inlineScript: |
            echo "Fetching all directories..."
            
              FOLDERS=$(az storage fs file list \
            --account-name "${{ secrets.AZURE_STORAGE_ACCOUNT }}" \
            --file-system customers \
            --auth-mode login \
            --query "[?isDirectory].name" \
            --output table)
              
            echo "Available folders:"
            echo "$FOLDERS"

The code above logins into the Azure tenant based on the Environment variables set for the repository and lists recursively outputs all the directories for the given container (customers container in this example).

Commit the changes

As expected, the output contains all the underlying directories of container customers.

Execution>>

Conclusion

In this article, we explored how to configure Federated Credentials for a User Managed Identity, enabling password less authentication to Azure services for external Identity providers. By leveraging workload identity federation, you can grant external workloads (like GitHub Actions, Kubernetes workloads) access to Azure resources using short-lived tokens through federated credentials.

I hope this guide helps you to get started on implementation of federated credentials with User Managed Identities in your Azure environments.

Thanks for reading !!!

But sometimes there can be scenarios where maintaining RBAC access cannot be feasible . Imagine managing an Azure tenant in an organization that has 1,000+ employees and hundreds of storage accounts and Azure services and where every user requires different access to these services. Though manageable through RBAC but managing and maintaining such a large number of roles can be challenging and cause operational overhead.

An alternative solution can be a claim based authorization through Microsoft Entra ID issued access tokens along with authorization policies.

Instead of assigning Azure RBAC roles to every user for every resource, Microsoft Entra ID can issue access tokens containing claims that describe the user's permissions. The application can then evaluate these claims through authorization policies and determine if the user is allowed to perform a particular operation.

In this article, we will build an ASP.NET Core Minimal API that authenticates users with Microsoft Entra ID. Once the claims are validated from the access token, the API will securely accesses Azure ADLS Gen2 Storage through DataLakeServiceClient (i.e. return a list of all the directories in a given Azure ADLS Gen2 storage container) on behalf of the user, based on access granted to him through App roles in Microsoft Entra.

A sample claim based access token might contain application-specific claims similar to the following:

{
  "sub": "1234567890",
  "name": "ABC",
   "roles": [
        "Storage.Access"
      ],
  "permissions": [
    "storage.read",
    "storage.write"
  ]
}

In the above example, the permissions claim is interpreted by the application to determine whether the user is authorized to perform read or write operations on the storage based on the roles .

Instead of granting RBAC role access to individual user, only the service principal is granted RBAC role on the Azure service, in our case the access is granted on Azure ADLS Gen2 storage to the service principal.

The application authenticates on the Azure Storage using a service principal (or managed identity) that already has the necessary Azure RBAC permissions.

In such a scenario we require two access tokens. The first token will contain the user claims and the second token will have the necessary scope permissions to perform the underlying actions on the Azure service (in this case Azure ADLS Gen2 storage) on behalf of the user.

The application first validates the claims in the user access token and once its validated it uses the service principal token to authenticate the Azure storage based on the audience value of the delegated scopes assigned to it in Microsoft Entra ID.

The initial steps to be performed are similar to the article below i.e. exposing a service principal API ,defining custom scopes and finally granting permissions to the exposed API.

https://www.azureguru.net/azure-services-authentication-through-microsoft-managed-identity

Flow

To add more context to the above flow, the scopes used will be

api://{ApplicationId} and https://storage.azure.com

created through the Expose API option and Delegated Permissions for the service principal.

SetUp

There are two users :

• (Sachin.Nand) sachin.nandanwar@azureguru.net

• (Sachin Nandanwar) sachin_nandanwar@azureguru.net

Only (Sachin.Nand) sachin.nandanwar@azureguru.net will be assigned the necessary App Role accesses for the service principal.

Ensure that you the Scalar set up is configured in your ASP.NET core project. For more details refer to my following article

https://www.azureguru.net/customize-scalar-UI-for-net-api

Also ensure that you have a thorough understanding of Minimal API's and implementation of ClaimPrincipal, Authentication and Authorization for Minimal API's. Please refer to my article below to have a better understanding of the topic.

https://www.azureguru.net/implementing-jwt-tokens-in-minimal-api-net-core

You can ignore the custom JWToken aspect from the above article as in that article the focus was on creating custom JWTokens.

Create a Service Principal and grant the Azure Storage delegated permissions. I created one called ADLS GEN2 Service Principal.

Grant Storage Blob Data Owner role access to the service principal for the storage service.

In the next step ,under the Expose an API option, click the Add button. By default the Application ID URI is the ClientID of the Service Principal.

The format is api://{ApplicationId}.

ApplicationID is the Service Principal ClientId

Cross check the Application ID URI with the Client ID of the service principal.

In the next step define a new scope.

Click “Add a scope” option and enter storage_read as the scope name.

Once added, the scope should be visible on the Expose an API page.

In the next step , under API permissions , click Add a permission and select the API that was created in the previous step.

This might sound counterintuitive to see that we have to assign permissions for an API to the service principal that created that API in the first place. But that’s the way it is. Not doing so results in an Unauthorized access error.

Please ensure that Azure Storage Delegated permission is also assigned to service principal.

In the next step, create an App Role.

App roles (Application Roles) is a feature of Role-Based Access Control (RBAC) that defines what actions a user, group or service is allowed to perform within a specific application at the apps identity level.

App role name is AzureStorage and value is AzureStorage.Read

The role AzureStorage created will be part of the access token. This is very crucial aspect to validate user permissions.

The next step is to enable Assignment required property.

Browse to Entra ID > Enterprise apps >> All applications

Select your application. In our case it is ADLS Gen2 Service Principal

Ensure that Assignment required? is set to Yes . By default it is No.

Navigate to Users and groups in the same page add click Add user/group

Click None Selected and Search for user to whom you want to grant the Assignements.

Grant assignment to the selected user . In this case I will assign it only to the user Sachin Nand

Now that the set up and the required prerequisite is in place , lets move on to the code.

Code

Add the following references to your ASP.NET core project

dotnet add package Azure.Core;
dotnet add package Azure.Storage.Files.DataLake;
dotnet add package Microsoft.IdentityModel.Tokens;
dotnet add package Scalar.AspNetCore;
dotnet add package System.Security.Claims;

We first define an Authentication class that validates the user's sign-in and requested scopes with Microsoft Entra ID and then returns a JWT token.

Unlike implementing custom JWT tokens which I demonstrated in my earlier article here, with Microsoft Entra ID-issued tokens there is no need for generating, signing, rotating or validating JWTs ourselves. Microsoft Entra ID auto handles all these aspects at its end.

Authentication.cs >>

using Microsoft.Identity.Client;
using System.IdentityModel.Tokens.Jwt;

namespace Security {
  internal class Authentication {  
  
    public static string TenantId = "Tenant Id";
    public static string ClientId = "Client Id of the Service Principal";
    public static string ClientSecret = "Client secret of the Service Principal"     

    private static IEnumerable < string > scopes = new List < string > {
      "https://storage.azure.com/.default",
      "api://{ApplicationID}/.default"
    };

    private static string Authority = $"https://login.microsoftonline.com/{TenantId}";
    private static string RedirectURI = "http://localhost";

    public async static Task < JwtSecurityToken[] > ReturnAuthenticationResult() {
      string AccessToken;
      IPublicClientApplication PublicClientApplication_claims =
        PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(Authority)
        .WithCacheOptions(CacheOptions.EnableSharedCacheOptions)
        .WithRedirectUri(RedirectURI).Build();

      var accounts_claims = await PublicClientApplication_claims.GetAccountsAsync();
      AuthenticationResult claims_result, storage_result;
      var scopeList = scopes.ToList();
      try {

        claims_result = await PublicClientApplication_claims.AcquireTokenSilent(new [] {
            scopeList.ElementAt(0)
          }, accounts_claims.First())
          .ExecuteAsync()
          .ConfigureAwait(false);

      } catch {
        claims_result = await PublicClientApplication_claims.AcquireTokenInteractive(new [] {
            scopeList.ElementAt(0)
          })
          .ExecuteAsync()
          .ConfigureAwait(false);

      }

      JwtSecurityToken claims_token = new JwtSecurityToken(claims_result.AccessToken);

      var app = ConfidentialClientApplicationBuilder
        .Create(ClientId)
        .WithClientSecret(ClientSecret)
        .WithAuthority(Authority)
        .Build();

      storage_result = await app
        .AcquireTokenForClient(new [] {
          scopeList.ElementAt(1)
        })
        .ExecuteAsync();

      JwtSecurityToken storage_token = new JwtSecurityToken(storage_result.AccessToken);

      return [claims_token, storage_token];

    }
  }
}

For brevity I have defined ClientId, ClientSecret and TenantId in variables. Ideally they should be placed in a config file and ClientSecret stored to a secured location like Environment variables or Key vault and their values fetched from there.

Few important aspects of the above code.

ReturnAuthenticationResult function returns two tokens (storage token and claim token) through array JwtSecurityToken[] .

 return [claims_token, storage_token];

The scopes used are : https://storage.azure.com/.default for the storage token and api://{ApplicationID}/.default for the claims token.

claims_token is a delegated user token (idtyp = user) and storage_token is a service principal token (idtyp = app)

Why two different token types (idtyp = user and idtyp = app) is required ?

Its because the user no longer has any RBAC role access to the storage but the service principal has (we had granted that earlier).So only service principal token will be authorized for any access to the storage.

AccessTokenCredential.cs >>

using Azure.Core;
using System.IdentityModel.Tokens.Jwt;

namespace AccesTokenCredentials
{
    public class AccessTokenCredential : Azure.Identity.ClientSecretCredential
    {
        public AccessTokenCredential(string accessToken)
        {
            AccessToken = accessToken;
        }

        private string AccessToken;

        public AccessToken FetchAccessToken()
        {
            JwtSecurityToken token = new JwtSecurityToken(AccessToken);
            return new AccessToken(AccessToken, token.ValidTo);
        }

        public override ValueTask<AccessToken> GetTokenAsync(
            TokenRequestContext requestContext,
            CancellationToken cancellationToken
        )
        {
            return new ValueTask<AccessToken>(FetchAccessToken());
        }

        public override AccessToken GetToken(
            TokenRequestContext requestContext,
            CancellationToken cancellationToken
        )
        {
            JwtSecurityToken token = new JwtSecurityToken(AccessToken);
            return new AccessToken(AccessToken, token.ValidTo);
        }
    }
}

The above class converts bearer tokens to TokenCredentials. We will require TokenCredentials for authenticating DataLakeServiceclient and return the directory structure for the ADLS Gen2 storage.

For more information as to why this is required, please refer to the following article https://www.azureguru.net/customize-clientsecretcredential-class-for-onelake-authentication-in-microsoft-fabric

Program.cs >>

using AccesTokenCredentials;
using Azure.Core;
using Azure.Storage.Files.DataLake;
using Microsoft.IdentityModel.Tokens;
using Scalar.AspNetCore;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;

public static class Program
{
     public static string TenantId = "Tenant Id";
     public static string ClientId = "Client Id of the Service Principal";
     public static string StorageAccount = "ADLS GEN2 Storage Account"; 
    public static List<string> listoutput = new();
    public static JwtSecurityToken[] tokens;
    private static async Task Main(string[] args)
    {
        WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
        builder.Services.AddAuthentication().AddJwtBearer(options =>
        {
            options.Authority = $"https://login.microsoftonline.com/{TenantId}";
            options.MapInboundClaims = false;
            options.Validate();
            options.TokenValidationParameters = new TokenValidationParameters
            {
                ValidIssuer = $"https://sts.windows.net/{TenantId}/",
                ValidAudience = $"api://{ClientId}",
                ValidateIssuer = true,
                ValidateAudience = true
            };
        });

        builder.Services.AddAuthorization(options =>
        {
            options.AddPolicy("AzureStorageAccess", policy =>
            {
                policy.RequireAuthenticatedUser();
                policy.RequireClaim("aud", $"api://{ClientId}");
                policy.RequireClaim("iss", $"https://sts.windows.net/{TenantId}/");
                policy.RequireClaim("scp", "storage.read");
                policy.RequireClaim("roles", "AzureStorage.Read");

            });

        });

        builder.Services.AddOpenApi(options =>
         {
             options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
         });

        WebApplication app = builder.Build();

        if (app.Environment.IsDevelopment())
        {
            app.MapOpenApi();
        }

        app.MapScalarApiReference(options =>
        {
            options.Title = "Scalar API";
            options.DarkMode = true;
            options.Favicon = "path";
            options.DefaultHttpClient = new KeyValuePair<ScalarTarget, ScalarClient>(ScalarTarget.CSharp, ScalarClient.RestSharp);
            options.HideModels = false;
            options.Layout = ScalarLayout.Modern;
            options.ShowSidebar = true;
            options.Authentication = new ScalarAuthenticationOptions
            {
                PreferredSecuritySchemes = new List<string> { "Bearer" }
            };
        });

        app.UseHttpsRedirection();


        app.MapPost("/login", async () =>
         {     
             tokens = await Security.Authentication.ReturnAuthenticationResult();
             return Results.Ok(tokens);
         });


        app.MapGet("/accessazurestorage", async (ClaimsPrincipal claims, HttpContext context) =>
        {
            var audience = claims.FindFirst("aud")?.Value;
            var issuer = claims.FindFirst("iss")?.Value;
            var scp = claims.FindFirst("scp")?.Value;
            var roles = claims.FindFirst("roles")?.Value;

            if (audience != $"api://{ClientId}")
            {
                throw new UnauthorizedAccessException("Unauthorized access !!!");
            }

            if (issuer != $"https://sts.windows.net/{TenantId}/")
            {
                throw new UnauthorizedAccessException("Unauthorized access !!!");
            }


            if (scp != "storage.read")
            {
                throw new UnauthorizedAccessException("Unauthorized access !!!");
            }

            var token = context.Request.Headers["Authorization"].ToString().Replace("Bearer ", "");

            DataLakeServiceClient datalake_Service_Client;
            DataLakeFileSystemClient dataLake_FileSystem_Client;
            string dfsUri = $"https://{StorageAccount}.dfs.core.windows.net";
            TokenCredential tokenCredential = new AccessTokenCredential(tokens[0].RawData.ToString());
            datalake_Service_Client = new DataLakeServiceClient(new Uri(dfsUri), tokenCredential);
            dataLake_FileSystem_Client = datalake_Service_Client.GetFileSystemClient("customers");
            DataLakeDirectoryClient rootDirectory_ = dataLake_FileSystem_Client.GetDirectoryClient("");
            listoutput.Clear();
            return Results.Ok(new
            {
                Output = TraverseDirectory(rootDirectory_) 

            });
        })
        .RequireAuthorization("AzureStorageAccess");

        app.MapGet("/fakeaccessazurestorage", () =>
        {
        }).RequireAuthorization("AzureStorageAccess");

        app.Run();
    }

    public static async Task<List<string>> TraverseDirectory(DataLakeDirectoryClient directoryClient)
    {

        await foreach (var item in directoryClient.GetPathsAsync())
        {
            if (item.IsDirectory == true)
            {
                listoutput.Add(item.Name);
                string[] split = item.Name.Split("/");
                var subDir = directoryClient.GetSubDirectoryClient(split.Length == 1 ? split[0] : split[split.Length - 1]);
                await TraverseDirectory(subDir);
            }
        }

        return listoutput;
    }
}

Lets dissect the major aspects of the above code

We declare an array of type JwtSecurityToken[] which is used to store the values for claims_token and storage_token returned by the Authentication class defined earlier.

 public static JwtSecurityToken[] tokens;

Authentication >>

builder.Services.AddAuthentication().AddJwtBearer(options =>
{
    options.Authority = $"https://login.microsoftonline.com/{TenantId}";
    options.MapInboundClaims = false;
    options.Validate();
    options.TokenValidationParameters = new TokenValidationParameters
    {
         ValidIssuer = "https://sts.windows.net/{TenantId}/",
         ValidAudience = "https://storage.azure.com",
         ValidateIssuer = true,
         ValidateAudience = true
    };
});

Authentication mechanism is used to validate the incoming tokens. It checks for two parameters, ValidIssuer and ValidAudience and ensures that the values for these parameters in the bearer token matches with

• https://sts.windows.net/{TenantId}/ and https://storage.azure.com

• options.MapInboundClaims = false . This setting is very important wrt validating the claims .Check the following screenshot

The claims and the scope format above is a standard JWT format . If options.MapInboundClaims = true (which the default) , the claim check through the HttpContext will fail . For example something like

var roles = claims.FindFirst("roles")?.Value

roles will always be null as it checks for the keyword "roles"

But setting options.MapInboundClaims = false the format changes

Authorization >>

   builder.Services.AddAuthorization(options =>
  {
      options.AddPolicy("AzureStorageAccess", policy =>
      {
          policy.RequireAuthenticatedUser();
          policy.RequireClaim("aud", $"api://{ClientId}");
          policy.RequireClaim("iss", $"https://sts.windows.net/{TenantId}/");
          policy.RequireClaim("scp", "storage.read");
          policy.RequireClaim("roles", "AzureStorage.Read");
      });
  });

Create an authorization policy but before that ensure that request contains authenticated users and then check if the claims contain "aud", "scp", "roles", "iss" and then validate its values.

Scalar.cs >>

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;

internal sealed class BearerSecuritySchemeTransformer : IOpenApiDocumentTransformer
{
    private readonly IAuthenticationSchemeProvider _authenticationSchemeProvider;

    public BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider)
    {
        _authenticationSchemeProvider = authenticationSchemeProvider;
    }

    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        var authenticationSchemes = await _authenticationSchemeProvider.GetAllSchemesAsync();

        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
        {
            document.Components ??= new OpenApiComponents();
            document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();
            document.Components.SecuritySchemes["Bearer"] = new OpenApiSecurityScheme
            {
                Type = SecuritySchemeType.Http,
                Scheme = "bearer",
                In = ParameterLocation.Header,
                BearerFormat = "JWT"
            };

            foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
            {
                if (operation.Value.Security == null)
                {
                    operation.Value.Security = new List<OpenApiSecurityRequirement>();
                }
                var securityRequirement = new OpenApiSecurityRequirement
                {
                    [new OpenApiSecuritySchemeReference("Bearer", document)] = []
                };

                operation.Value.Security ??= new List<OpenApiSecurityRequirement>();
                operation.Value.Security.Add(securityRequirement);
            }
        }
    }
}

Scalar UI >>

 builder.Services.AddOpenApi(
    options =>
    {
        options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
    }
);

WebApplication app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapScalarApiReference(
    options =>
    {
        options.Title = "Scalar API";
        options.DarkMode = true;
        options.Favicon = "path";
        options.DefaultHttpClient = new KeyValuePair<ScalarTarget, ScalarClient>(
            ScalarTarget.CSharp,
            ScalarClient.RestSharp
        );
        options.HideModels = false;
        options.Layout = ScalarLayout.Modern;
        options.ShowSidebar = true;
        options.Authentication = new ScalarAuthenticationOptions
        {
            PreferredSecuritySchemes = new List<string> { "Bearer" }
        };
    }
);

The above code customizes the Scalar UI to include the Bearer token section.

For more details refer to my article on the topic here.

Login Endpoint >>

app.MapPost("/login", async() =>
{
 tokens = await Security.Authentication.ReturnAuthenticationResult();
return Results.Ok(tokens);
}).WithOpenApi();

In Login endpoint, we fetch the access token issued by Entra ID that is part of the OIDC flow.

TraverseDirectory >>

public static async Task<List<string>> TraverseDirectory(DataLakeDirectoryClient directoryClient)
{

    await foreach (var item in directoryClient.GetPathsAsync())
    {
        if (item.IsDirectory == true)
        {
            listoutput.Add(item.Name);
            string[] split = item.Name.Split("/");
            var subDir = directoryClient.GetSubDirectoryClient(split.Length == 1 ? split[0] : split[split.Length - 1]);
            await TraverseDirectory(subDir);
        }
    }

    return listoutput;
}

The above code recursively traverses the directory structure of a given Azure container . For more in-depth details on the approach you can refer to my article

https://www.azureguru.net/retrieve-the-hierarchical-directory-structure-from-azure-adls-gen2-storage

Accessazurestorage Endpoint >>

        app.MapGet("/accessazurestorage", async (ClaimsPrincipal claims, HttpContext context) => {
        var audience = claims.FindFirst("aud")?.Value;
        var issuer = claims.FindFirst("iss")?.Value;
        var scp = claims.FindFirst("scp")?.Value;
        var roles = claims.FindFirst("roles")?.Value;

        if (audience != $ "api://{ClientId}") {
          throw new UnauthorizedAccessException("Unauthorized access !!!");
        }

        if (issuer != $ "https://sts.windows.net/{TenantId}/") {
          throw new UnauthorizedAccessException("Unauthorized access !!!");
        }

        if (scp != "storage.read") {
          throw new UnauthorizedAccessException("Unauthorized access !!!");
        }

        if (roles != "AzureStorage.Read") {
          throw new UnauthorizedAccessException("Unauthorized access !!!");
        }

        DataLakeServiceClient datalake_Service_Client;
        DataLakeFileSystemClient dataLake_FileSystem_Client;
        string dfsUri = $ "https://adlsfilestore.dfs.core.windows.net";

        TokenCredential tokenCredential = new AccessTokenCredential(tokens[0].RawData.ToString());

        datalake_Service_Client = new DataLakeServiceClient(new Uri(dfsUri), tokenCredential);

        dataLake_FileSystem_Client = datalake_Service_Client.GetFileSystemClient("customers");

        DataLakeDirectoryClient rootDirectory_ = dataLake_FileSystem_Client.GetDirectoryClient("");

        listoutput.Clear();

        return Results.Ok(new {
          Output = TraverseDirectory(rootDirectory_)

        });
      })
      .RequireAuthorization("AzureStorageAccess");

    app.Run();
    }

The code is pretty straightforward. Validate audience, issuer, scp and roles values from claims.

If all the above criteria are met , then fetch the storage_token from the tokens array of type JwtSecurityToken[] (declare earlier) and pass the value to TokenCredential for DatalakeServiceClient which then eventually returns the directory structure for the Azure container customers.

Login in with sachin.nandanwar @ azureguru.net

Login in with sachin_nandanwar @ azureguru.net

Execution >>

Conclusion >>

The two-token pattern keeps user authorization and resource authorization separate. Leveraging Claims-based authorization and Azure RBAC together results in a much cleaner security model. User are authorized to access the application through their claims while the service principal accesses Azure resources using its own identity. This removes the need to grant Azure RBAC permissions to every user across every Azure resource to which user needs access.

I hope this article helps you get started with claims-based authorization and the two-token pattern in Microsoft Entra ID.

Thanks for reading !!!

We'll explore how Microsoft Entra ID integrates with ASP.NET Core Minimal APIs, how access tokens are leveraged to authenticate requests and how Azure Storage authorizes those requests using Azure RBAC and Access Control Lists (ACLs).

As compared to other articles on the internet that only provide high-level overview on the topic, my article will focus on the actual implementation of authentication and authorization mechanisms involved for securing Azure services through Minimal API's by leveraging Microsoft Entra ID.

Unfortunately I wont go in-depth explaining all the underlying concepts involved. So before you begin please ensure that you should be familiar with the following concepts:

• ASP.NET Core Minimal APIs

• Microsoft Entra ID and OpenID Connect (OIDC)

• Azure Storage (Blob Storage or Data Lake Storage Gen2)

• Azure Role-Based Access Control (Azure RBAC)

• Azure Storage Access Control Lists (ACLs)

A basic understanding of these technologies will help you get the most out of this article and follow the implementation steps details more easily.

Basic OAUTH 2.0 and OIDC flow for Microsoft Entra ID tokens.

The implementation in this article is pretty straightforward.

We'll build an ASP.NET Core Minimal API that authenticates users with Microsoft Entra ID and once authenticated it will securely accesses Azure ADLS Gen2 Storage through DataLakeServiceClient (i.e. return a list of all the directories in a given Azure ADLS Gen2 storage container) on behalf of the user.

I will use the following references from my other articles

• Leverage MSAL for Microsoft Fabric >> https://www.azureguru.net/msal-for-microsoft-fabric

• Retrieve ADLS Gen 2 directory structure by DataLakeServiceClient >> https://www.azureguru.net/retrieve-the-hierarchical-directory-structure-from-azure-adls-gen2-storage

• Leverage Service Principal to fetch Microsoft Fabric Directory structure >> https://www.azureguru.net/service-principal-in-microsoft-fabric

• Creating a TokenCredential from a Bearer Token >> https://www.azureguru.net/customize-clientsecretcredential-class-for-onelake-authentication-in-microsoft-fabric

• Customizing Scalar UI for .NET API's >> https://www.azureguru.net/customize-scalar-UI-for-net-api

• JWT tokens in Minimal API's >> https://www.azureguru.net/implementing-jwt-tokens-in-minimal-api-net-core

The article JWT tokens in Minimal API's quoted above demonstrates how custom JWT tokens can be used to authorize access where requests were approved or denied based on defined authorization policies.

However, in this article we will leverage the access tokens generated by Microsoft Entra Id for a service principal and the delegated permissions granted to it . We then validate the token audience. Once the token is validated, the signed in user access is then checked for RBAC permissions granted for the given Azure ADLS Gen2 storage.

Flow

To add more context to the above flow, the scope used is

https://storage.azure.com/

SetUp

The ADLS storage has the following structure

The expectation from the code is that it should be capable of recursively traversing all directories within a given container. As shown in the screenshot above, the customers container contains directories that are nested up to three levels deep and this structure can be dynamic.

So , there are two users :

• sachin.nandanwar@azureguru.net

• sachin_nandanwar@azureguru.net

sachin.nandanwar@azureguru.net is assigned the necessary RBAC role accesses to the storage. Typically it has to be Storage Blob Data Owner role.

You could also grant Storage Blob Data Contributor role but the Storage Blob Data Owner role has POSIX access control (ACL access) that auto grants all the (r-w-x) privileges to the owner for all the underlying objects under the container.

For instance in the following screenshot we can see that the owner i.e. the Storage Blob Data Owner was auto assigned the (r-w-x) access .

sachin_nandanwar@azureguru.net is not assigned any RBAC role.

Create a Service Principal and grant the Azure Storage delegated permissions. I created one called ADLS GEN2 Service Principal.

Ensure that you the Scalar set up is configured in your ASP.NET core project. For more details refer to my following article

https://www.azureguru.net/customize-scalar-UI-for-net-api

Also ensure that you have a thorough understanding of Minimal API's and implementation of ClaimPrincipal, Authentication and Authorization for Minimal API's. Please refer to my article to have a better understanding of the topic.

https://www.azureguru.net/implementing-jwt-tokens-in-minimal-api-net-core

You can ignore the custom JWToken aspect from the above article as in that article the focus was on creating custom JWTokens.

Code

Add the following references to your ASP.NET core project

dotnet add package Azure.Core;
dotnet add package Azure.Storage.Files.DataLake;
dotnet add package Microsoft.IdentityModel.Tokens;
dotnet add package Scalar.AspNetCore;
dotnet add package System.Security.Claims;

First, we define an Authentication class that validates the user's sign-in and requested scopes with Microsoft Entra ID and then returns a JWT token.

Unlike implementing custom JWT tokens which I demonstrated in my earlier article here, with Microsoft Entra ID-issued tokens there is no need for generating, signing, rotating or validating JWTs ourselves. Microsoft Entra ID auto handles all these aspects at its end.

Authentication.cs >>

using Microsoft.Identity.Client;
using System.IdentityModel.Tokens.Jwt;

namespace Security
{
    internal class Authentication
    {
        public static string clientId = "Service Principal Client Id";
        private static string[] scopes = { "https://storage.azure.com/.default" };
        private static string Authority = "https://login.microsoftonline.com/organizations";
        private static string RedirectURI = "http://localhost";

        public async static Task<JwtSecurityToken> ReturnAuthenticationResult()
        {
            string AccessToken;
            IPublicClientApplication PublicClientApplication = PublicClientApplicationBuilder
                .Create(clientId)
                .WithAuthority(Authority)
                .WithCacheOptions(CacheOptions.EnableSharedCacheOptions)
                .WithRedirectUri(RedirectURI)
                .Build();

            var accounts = await PublicClientApplication.GetAccountsAsync();
            AuthenticationResult result;

            try
            {
                result = await PublicClientApplication
                    .AcquireTokenSilent(scopes, accounts.First())
                    .ExecuteAsync()
                    .ConfigureAwait(false);
            }
            catch
            {
                result = await PublicClientApplication
                    .AcquireTokenInteractive(scopes)
                    .ExecuteAsync()
                    .ConfigureAwait(false);
            }

            JwtSecurityToken token = new JwtSecurityToken(result.AccessToken);
            return token;
        }
    }
}

For brevity I have defined ClientId and other details in variables. Ideally they should be placed in a config file and their values fetched from there.

AccessTokenCredential.cs >>

using Azure.Core;
using System.IdentityModel.Tokens.Jwt;

namespace AccesTokenCredentials
{
    public class AccessTokenCredential : Azure.Identity.ClientSecretCredential
    {
        public AccessTokenCredential(string accessToken)
        {
            AccessToken = accessToken;
        }

        private string AccessToken;

        public AccessToken FetchAccessToken()
        {
            JwtSecurityToken token = new JwtSecurityToken(AccessToken);
            return new AccessToken(AccessToken, token.ValidTo);
        }

        public override ValueTask<AccessToken> GetTokenAsync(
            TokenRequestContext requestContext,
            CancellationToken cancellationToken
        )
        {
            return new ValueTask<AccessToken>(FetchAccessToken());
        }

        public override AccessToken GetToken(
            TokenRequestContext requestContext,
            CancellationToken cancellationToken
        )
        {
            JwtSecurityToken token = new JwtSecurityToken(AccessToken);
            return new AccessToken(AccessToken, token.ValidTo);
        }
    }
}

The above class converts bearer tokens to TokenCredentials. We will require TokenCredentials for authenticating DataLakeServiceclient and return the directory structure for the ADLS Gen2 storage.

For more information as to why this is required, please refer to the following article https://www.azureguru.net/customize-clientsecretcredential-class-for-onelake-authentication-in-microsoft-fabric

Program.cs >>

public static class Program {
  public static string TenantId = "Tenant Id";
  public static List < string > listoutput = new();

  private static async Task Main(string[] args) {
    WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

    builder.Services
      .AddAuthentication()
      .AddJwtBearer(
        options => {
          options.Authority = $ "https://login.microsoftonline.com/{TenantId}";
          options.Validate();
          options.TokenValidationParameters = new TokenValidationParameters {
            ValidIssuer = $ "https://sts.windows.net/{TenantId}/",
              ValidAudience = "https://storage.azure.com",
              ValidateIssuer = true,
              ValidateAudience = true
          };
        }
      );

    builder.Services.AddAuthorization(
      options => {
        options.AddPolicy(
          "AzureStorageAccess",
          policy => {
            policy.RequireAuthenticatedUser();
            policy.RequireClaim("aud", "https://storage.azure.com");
            policy.RequireClaim("iss", $ "https://sts.windows.net/{TenantId}/");
          }
        );
      }
    );

    builder.Services.AddOpenApi(
      options => {
        options.AddDocumentTransformer < BearerSecuritySchemeTransformer > ();
      }
    );

    WebApplication app = builder.Build();

    if (app.Environment.IsDevelopment()) {
      app.MapOpenApi();
    }

    app.MapScalarApiReference(
      options => {
        options.Title = "Scalar API";
        options.DarkMode = true;
        options.Favicon = "path";
        options.DefaultHttpClient = new KeyValuePair < ScalarTarget, ScalarClient > (
          ScalarTarget.CSharp,
          ScalarClient.RestSharp
        );
        options.HideModels = false;
        options.Layout = ScalarLayout.Modern;
        options.ShowSidebar = true;
        options.Authentication = new ScalarAuthenticationOptions {
          PreferredSecuritySchemes = new List < string > {
            "Bearer"
          }
        };
      }
    );

    app.UseHttpsRedirection();

    app.MapPost(
        "/login",
        () => {
          return Results.Ok(
            new {
              token = Security.Authentication.ReturnAuthenticationResult()
            }
          );
        }
      )
      .WithOpenApi();

    app.MapGet(
        "/accessazurestorage",
        async (ClaimsPrincipal claims, HttpContext context) => {
          var audience = claims.FindFirst("aud")?.Value;
          var issuer = claims.FindFirst("iss")?.Value;

          if (audience != "https://storage.azure.com") {
            throw new UnauthorizedAccessException("Unauthorized access !!!");
          }

          if (issuer != "$https://sts.windows.net/{TenantId}/") {
            throw new UnauthorizedAccessException("Unauthorized access !!!");
          }

          var token = context.Request.Headers["Authorization"]
            .ToString()
            .Replace("Bearer ", "");

          DataLakeServiceClient datalake_Service_Client;

          DataLakeFileSystemClient dataLake_FileSystem_Client;

          string dfsUri = $ "https://adlsfilestore.dfs.core.windows.net";

          TokenCredential tokenCredential = new AccessTokenCredential(token.ToString());

          datalake_Service_Client = new DataLakeServiceClient(
            new Uri(dfsUri),
            tokenCredential
          );

          dataLake_FileSystem_Client = datalake_Service_Client.GetFileSystemClient(
            "customers"
          );

          DataLakeDirectoryClient rootDirectory_ =
            dataLake_FileSystem_Client.GetDirectoryClient("");

          return Results.Ok(new {
            Output = TraverseDirectory(rootDirectory_)
          });
        }
      )
      .RequireAuthorization("AzureStorageAccess");

    app.MapGet("/fakeaccessazurestorage", () => {}).RequireAuthorization("AzureStorageAccess");

    app.Run();
  }

  public static async Task < List < string >> TraverseDirectory(
    DataLakeDirectoryClient directoryClient
  ) {
    await foreach(var item in directoryClient.GetPathsAsync()) {
      if (item.IsDirectory == true) {
        listoutput.Add(item.Name);
        string[] split = item.Name.Split("/");
        var subDir = directoryClient.GetSubDirectoryClient(
          split.Length == 1 ? split[0] : split[split.Length - 1]
        );
        await TraverseDirectory(subDir);
      }
    }

    return listoutput;
  }
}

Lets dissect the major aspects of the above code

Authentication >>

builder.Services.AddAuthentication().AddJwtBearer(options =>
{
    options.Authority = $"https://login.microsoftonline.com/{TenantId}";
    options.Validate();

    options.TokenValidationParameters = new TokenValidationParameters
    {
         ValidIssuer = "https://sts.windows.net/{TenantId}/",
         ValidAudience = "https://storage.azure.com",
         ValidateIssuer = true,
         ValidateAudience = true
    };
});

Authentication mechanism is used to validate the incoming tokens. It checks for two parameters, ValidIssuer and ValidAudience and ensures that the values for these parameters in the bearer token matches with

• https://sts.windows.net/{TenantId}/ and https://storage.azure.com

Authorization >>

 builder.Services.AddAuthorization(options =>
 {
     options.AddPolicy("AzureStorageAccess", policy =>
     {
         policy.RequireAuthenticatedUser();
         policy.RequireClaim("aud", "https://storage.azure.com");
         policy.RequireClaim("iss", $"https://sts.windows.net/{TenantId}/");
     });
 });

Create an authorization policy but before that ensure that request contains authenticated users and then check if the claims contain "aud" and "iss" and then validate its values.

Scalar.cs >>

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;

internal sealed class BearerSecuritySchemeTransformer : IOpenApiDocumentTransformer
{
    private readonly IAuthenticationSchemeProvider _authenticationSchemeProvider;

    public BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider)
    {
        _authenticationSchemeProvider = authenticationSchemeProvider;
    }

    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        var authenticationSchemes = await _authenticationSchemeProvider.GetAllSchemesAsync();

        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
        {
            document.Components ??= new OpenApiComponents();
            document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();
            document.Components.SecuritySchemes["Bearer"] = new OpenApiSecurityScheme
            {
                Type = SecuritySchemeType.Http,
                Scheme = "bearer",
                In = ParameterLocation.Header,
                BearerFormat = "JWT"
            };

            foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
            {
                if (operation.Value.Security == null)
                {
                    operation.Value.Security = new List<OpenApiSecurityRequirement>();
                }
                var securityRequirement = new OpenApiSecurityRequirement
                {
                    [new OpenApiSecuritySchemeReference("Bearer", document)] = []
                };

                operation.Value.Security ??= new List<OpenApiSecurityRequirement>();
                operation.Value.Security.Add(securityRequirement);
            }
        }
    }
}

Scalar UI >>

 builder.Services.AddOpenApi(
    options =>
    {
        options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
    }
);

WebApplication app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapScalarApiReference(
    options =>
    {
        options.Title = "Scalar API";
        options.DarkMode = true;
        options.Favicon = "path";
        options.DefaultHttpClient = new KeyValuePair<ScalarTarget, ScalarClient>(
            ScalarTarget.CSharp,
            ScalarClient.RestSharp
        );
        options.HideModels = false;
        options.Layout = ScalarLayout.Modern;
        options.ShowSidebar = true;
        options.Authentication = new ScalarAuthenticationOptions
        {
            PreferredSecuritySchemes = new List<string> { "Bearer" }
        };
    }
);

The above code customizes the Scalar UI to include the Bearer token section.

For more details refer to my article on the topic here.

Login >>

app.MapPost("/login", () =>
{
    return Results.Ok(new { token = Security.Authentication.ReturnAuthenticationResult() });
}).WithOpenApi();

Here we fetch the access token issued by Entra ID which is part of the OIDC flow.

TraverseDirectory >>

public static async Task<List<string>> TraverseDirectory(DataLakeDirectoryClient directoryClient)
{

    await foreach (var item in directoryClient.GetPathsAsync())
    {
        if (item.IsDirectory == true)
        {
            listoutput.Add(item.Name);
            string[] split = item.Name.Split("/");
            var subDir = directoryClient.GetSubDirectoryClient(split.Length == 1 ? split[0] : split[split.Length - 1]);
            await TraverseDirectory(subDir);
        }
    }

    return listoutput;
}

The above code recursively traverses the directory structure of a given Azure container . For more in-depth details on the approach you can refer to my article

https://www.azureguru.net/retrieve-the-hierarchical-directory-structure-from-azure-adls-gen2-storage

Accessazurestorage >>

app.MapGet(
    "/accessazurestorage",
    async (ClaimsPrincipal claims, HttpContext context) => {
      var audience = claims.FindFirst("aud")?.Value;
      var issuer = claims.FindFirst("iss")?.Value;

      if (audience != "https://storage.azure.com") {
        throw new UnauthorizedAccessException("Unauthorized access !!!");
      }

      if (issuer != $ "https://sts.windows.net/{TenantId}/") {
        throw new UnauthorizedAccessException("Unauthorized access !!!");
      }

      var token = context.Request.Headers["Authorization"].ToString().Replace("Bearer ", "");

      DataLakeServiceClient datalake_Service_Client;

      DataLakeFileSystemClient dataLake_FileSystem_Client;

      string dfsUri = $ "https://adlsfilestore.dfs.core.windows.net";

      TokenCredential tokenCredential = new AccessTokenCredential(token.ToString());

      datalake_Service_Client = new DataLakeServiceClient(new Uri(dfsUri), tokenCredential);

      dataLake_FileSystem_Client = datalake_Service_Client.GetFileSystemClient("customers");

      DataLakeDirectoryClient rootDirectory_ = dataLake_FileSystem_Client.GetDirectoryClient(
        ""
      );
      return Results.Ok(new {
        Output = TraverseDirectory(rootDirectory_)
      });
    }
  )
  .RequireAuthorization("AzureStorageAccess");

The code is pretty straightforward. Check the audience and issuer values from claims and and fetch the access token from HttpContext .

Then convert the access token to TokenCredentials and use it to authenticate DataLakeServiceClient and then recursively traverse across the directory structure for the container customers. Note that it uses AzureStorageAccess policy (defined earlier in the login code) for Authorizing the request.

Executing the code the directory structure for the Azure container customers is displayed in the output

Fakeaccessazurestorage >>

  app.MapGet("/fakeaccessazurestorage", () =>
  {
  }).RequireAuthorization("AzureStorageAccess");

Accessing fakeaccessazurestorage endpoint without required audience and issuer details in the access token results in 401 Unauthorized exception.

Execution >>

Conclusion

In this article, we explored how to secure an ASP.NET Core Minimal API using Microsoft Entra ID and leverage delegated user authentication to access Azure Storage (ADLS GEN2) securely. By combining OpenID Connect, JWT Bearer authentication and Azure SDK with TokenCredential we were able to established a secure end-to-end request flow from user sign-in to resource access.

I hope this article helps you get started with implementing delegated authentication and authorization using Microsoft Entra ID in ASP.NET Core applications. While we used Azure Storage as the primary example in the article the concepts covered here extend to many Azure services that support Microsoft Entra ID authentication.

Thanks for reading !!!

This is where Microsoft Purview provides a powerful platform for seamlessly securing and governing your data. Microsoft Purview helps reduce complexity and improve governance related to mitigating risks in the era of AI.

Microsoft Agent Framework supports seamless integration with Microsoft Purview to help implement governance and compliance for your AI agents.

If you aren't much aware of Microsoft Purview and its capabilities, I would highly recommend to get familiar with it . A good starting point can be Microsoft official documentation on Microsoft Purview here.

Prerequisites

• You will require Azure subscription with a M365 E5 license. This is a must. Any other license for example E3 or Business premium or Standard license unfortunately will not work.

• Also required is Microsoft 365 pay-as-you-go option enabled.

• A thorough understanding of Microsoft Entra and OIDC authentication through MSAL.NET and how they integrate in the overall Microsoft ecosystem. I have extensively used them across all of my blogs on Microsoft fabric and Microsoft Azure. I would like to highlight a couple of them to make understand on how to integrate them. You can find them here and here .Though the articles are specific for with Microsoft fabric and Azure , they will help you to get a general understanding of the concepts.

• Some conceptual understanding of Microsoft Purview like policy framework and how these policies are used to govern organizational data.

Below is a conceptual flow of MSAL.NET which is generic OAuth 2.0 and OIDC client.

SetUp

The very first step is to setup a Service Principal in Microsoft Entra that has the following Microsoft Graph permissions :

• ProtectionScopes.Compute.All

• ContentActivity.Write

• Content.Process.All

• Purview.DelegatedAccess

• ProtectionScopes.Compute.All

I created a one named Purview_Monitoring

Next , the following prerequisites has to be configured in Purview.

The "Configuration" names are little different in the new Purview UI

Microsoft Purview Audit >>

Its possible to turn it ON in two ways

Through the Purview portal or PowerShell

Purview Portal >>

Click "Start recording user and admin activity" to enable the Audit option.

PowerShell >>

To use PowerShell for Purview, you first have to use the following command

Connect-IPPSSession

to connect to Security & Compliance

Use PowerShell command line and not PowerShell ISE

Connect-IPPSSession will prompt you to authenticate your credentials

Once authenticated, load to ExchangeOnlineManagement cmdlet. If its not already installed, the cmdlet will auto install it for you.

Import-Module ExchangeOnlineManagement

Next, connect to Exchange Online PowerShell through your credentials. In my case it is sachin.nandanwar@azureguru.net

Connect-ExchangeOnline -UserPrincipalName sachin.nandanwar@azureguru.net

and then run the following command to enable Audit logs option.

Set-AdminAuditLogConfig -UnifiedAuditLogIngestionEnabled $true

It might take about 60 minutes for the Audit logs to be enabled

To check the status, under Solutions click the DSPM for AI (Classic) option

The above option is not available under new DSPM page

DSPM for AI >>

In the next step , enable the KYD Policy.

There is no option to set this up through the UI. You will have to set it up through PowerShell.

$locations = "[{`"Workload`":`"Applications`",`"Location`":`"$myEntraAppId`",`"LocationDisplayName`":`"$myEntraAppName`",`"LocationSource`":`"Entra`",`"LocationType`":`"Individual`",`"Inclusions`":[{`"Type`":`"Tenant`",`"Identity`":`"All`"}]}]"

New-FeatureConfiguration `
    -FeatureScenario KnowYourData `
    -Name "Secure interactions from enterprise apps (preview)" `
    -Mode Enable `
    -ScenarioConfig '{"Activities":["UploadText","DownloadText"],"EnforcementPlanes":["Application"],"SensitiveTypeIds":["All"],"IsIngestionEnabled":true}' `
    -Locations $locations

I have blurred the the $myEntraAppId value. This is the ClientID of the service principal that was set earlier. Note that "Secure interactions from enterprise apps (preview)" is a policy.

The PowerShell script above , ties up the service principal with the policy.

Once executed ,under DSPM for AI >>Policies option you should be able to see the created policy.

Communication Compliance >>

Under Solutions, click Communication Compliance

Select the "Detect unethical interactions for agents" option

There is an issue while setting up this policy. Its not possible to set it up for a specific Service Principal.

Check the screenshot below , where I tried to search for the service principal Purview_Monitoring that was configured earlier.

Its un available in the Select users option.

while the Entra users are visible

Anyways, setting it up for All users doesn't impact the flow.

The status is "Activating". It will take sometime for the status to change to "Ready".

Insider Risk Management >>

Under Insider Risk Management option select Quick Policy

and select "Risky AI Usage" policy

This is a standard general policy and is not tied to a specific user/s .

This is the last step and this basically completes all the underlying prerequisites.

Use Case

Now that all the prerequisites are in place, let's look through a use case in which we create a Microsoft Purview policy to block a specific prompt.

Prompts such as "Remember the credit card number..." are typically blocked by the AI model itself and there is no operational need for Microsoft Purview to validate and block the prompt. So the challenge is to create a policy that blocks a specific prompt only when it originates from our set up i.e. through an agent that runs the service principal.

As we saw earlier, the Microsoft Purview UI does not currently provide a way to scope policies to an individual Microsoft Entra service principal under which an Agent executes. This is where PowerShell comes to the rescue.

Lets create a policy that blocks a text say "oranges".

To get started, Run the following commands through PowerShell command line and NOT PowerShell ISE.

Also ensure that you are already connected through Connect-IPPSSession

Connect-IPPSSession

Import-Module ExchangeOnlineManagement

$myEntraAppId = "Service Principal ClientId"

$myEntraAppName = "Service Principal Name"

$locations = "[{`"Workload`":`"Applications`",`"Location`":`"$myEntraAppId`",`"LocationDisplayName`":`"$myEntraAppName`",`"LocationSource`":`"Entra`",`"LocationType`":`"Individual`",`"Inclusions`":[{`"Type`":`"Tenant`",`"Identity`":`"All`"}]}]"

New-DlpCompliancePolicy -Name "Test Oranges DLP" -Mode Enable -Locations $locations -EnforcementPlanes @("Application")

It takes some time for policy status to change from "Sync In Progress" to "Ready".

In the next step create a "Sensitive info types".

There are a lot of predefined "Sensitive info types" but we will create a custom one for our use case.

Name the sensitivity info type as "My Oranges Test SIT".

Next, create a pattern

and select "Add primary element" and under it select "Regular expression" option.

Add ID and keyword "oranges". The text "oranges" will be checked

If required, there is an option to use inbuilt regular expression by clicking the "Choose from existing regular expressions" in the screen above.

In the next screen, keep the Confidence level to High for highest accuracy.

Click Next

You can double check the sensitivity type through the following PowerShell command.

Get-DlpSensitiveInformationType 'My Oranges Test SIT'

In the next step, we will create a rule that is tied with the policy and leverages the sensitivity type that we created.

New-DlpComplianceRule -Name "Test Oranges Rule" -Policy "Test Oranges DLP" -ContentContainsSensitiveInformation @{Name = "My Oranges Test SIT"}  -GenerateAlert $true -GenerateIncidentReport @("siteadmin") -NotifyUser @("user@email.com") -RestrictAccess @(@{setting="UploadText";value="Block"})

That's all the settings required in Purview.

At this point, all the prerequisites, policies and sensitivity types in Purview are configured.

Code

In a console application install the following packages

dotnet add package Azure;
dotnet add package  Azure.AI.OpenAI;
dotnet add package  Microsoft.Agents.AI;
dotnet add package  Microsoft.Agents.AI.Purview;
dotnet add package  Microsoft.Extensions.AI;
dotnet add package  Microsoft.Extensions.Configuration;
dotnet add package  Microsoft.Extensions.DependencyInjection;

After the above artifacts are in place, add the following code to read the settings from appsettings.json in Program.cs of the project.

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Read the credentials and register a Chatclient

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

ServiceCollection servicecollection = new();

builder.Services.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)
                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
                .AsIChatClient()
    )
);

In the next step, register the following AIAgent in the hosted DI container.

PurviewAgent >>

  servicecollection.AddSingleton<ChatClientAgent>(sp =>

  {
      Func<ChatClientAgentOptions> func = () =>
     {
         return new ChatClientAgentOptions
         {
             ChatOptions = new ChatOptions
             {
                 Instructions ="You are a secure assistant.",

             },
             Name = "PurviewAgent",
             Id = "1"
         };
     };

      return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"), options: func());

  });

Build service and fetch agent through ServiceProvider as ChatClientAgent.

ServiceProvider serviceProvider = servicecollection.BuildServiceProvider();

var agent = serviceProvider.GetServices<ChatClientAgent>();

List<ChatClientAgents> chatclientagent = new(agent);

This is the most crucial part of the code. Here is where we leverage the Purview library

AIAgent agent_ = chatClientAgents[0].AsBuilder().WithPurview(await Security.Authentication.ReturnAuthenticationResult(), new PurviewSettings("Purview_Monitoring")
  {
      BlockedPromptMessage = "<<< BLOCKED BY PURVIEW PROMPT >>>",
      BlockedResponseMessage = "<<< BLOCKED BY PURVIEW RESPONSE >>>"
  }).Build();

We will have to pass TokenCredentials for the service principal authentication

To implement it, I have used the authentication method where the bearer token generated by MSAL is converted to TokenCredentials.

I have a blog on this topic where I used it for Fabric OneLake authentication for DataLakeServiceClient .

https://www.azureguru.net/customize-clientsecretcredential-class-for-onelake-authentication-in-microsoft-fabric

First, we'll need to create a Credentials class.

AccessTokenCredential.cs >>

using Azure.Core;
using Azure.Identity;
using System.IdentityModel.Tokens.Jwt;

public class AccessTokenCredential : ClientSecretCredential
    {

        public AccessTokenCredential(string accessToken)
        {
            AccessToken = accessToken;
        }

        private string AccessToken;

        public AccessToken FetchAccessToken()
        {
            JwtSecurityToken token = new JwtSecurityToken(AccessToken);
            return new AccessToken(AccessToken, token.ValidTo);
        }

        public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
        {
            return new ValueTask<AccessToken>(FetchAccessToken());
        }

         public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
         {
             JwtSecurityToken token = new JwtSecurityToken(AccessToken);
             return new AccessToken(AccessToken, token.ValidTo);
         }    

      }

and then create authentication class that returns the TokenCredentials

Authentication.cs >>

using Azure.Core;
using Microsoft.Identity.Client;
using System.IdentityModel.Tokens.Jwt;

namespace Security
{
    internal class Authentication
    {       
        public static string clientId = "Service Principal Client Id";
        private static string[] scopes = ["https://graph.microsoft.com/.default"];
        private static string Authority = "https://login.microsoftonline.com/organizations";
        private static string RedirectURI = "http://localhost";

        public async static Task<TokenCredential> ReturnAuthenticationResult()
        {
            string AccessToken;
            PublicClientApplicationBuilder PublicClientAppBuilder =
                PublicClientApplicationBuilder.Create(clientId)
                .WithAuthority(Authority)
                .WithCacheOptions(CacheOptions.EnableSharedCacheOptions)
                .WithRedirectUri(RedirectURI);

            IPublicClientApplication PublicClientApplication = PublicClientAppBuilder.Build();
            var accounts = await PublicClientApplication.GetAccountsAsync();
            AuthenticationResult result;

            try
            {

                result = await PublicClientApplication.AcquireTokenSilent(scopes, accounts.First())
                                 .ExecuteAsync()
                                 .ConfigureAwait(false);

            }
            catch
            {
                result = await PublicClientApplication.AcquireTokenInteractive(scopes)
                                 .ExecuteAsync()
                                 .ConfigureAwait(false);

            }
            
             JwtSecurityToken token = new JwtSecurityToken(result.AccessToken);
            AccessTokenCredential tokenCredential = new AccessTokenCredential(result.AccessToken);

            return tokenCredential;

        }

    }
}

Next, we send a prompt to the model asking about oranges

AgentResponse agentResponse = await agent_.RunAsync("What are oranges ?");
Console.WriteLine(agentResponse);

And the purview would block the response

If the prompt is about grapes the agent will return a relevant response.

AgentResponse agentResponse = await agent_.RunAsync("What are grapes ?");
Console.WriteLine(agentResponse);

Execution >>

Conclusion >>

To wrap it up , a good AI ecosystem success shouldn't be based only by what an AI agent can do, but also by what it should be allowed to do. Microsoft Purview helps bridge that gap by bringing governance directly into the AI application lifecycle.

Microsoft Purview and its seamless integration with the Microsoft Agent Framework, provides a powerful foundation for building AI agents that are not only intelligent but also secure, compliant, and enterprise-ready. Governance shouldn't be an afterthought it should be part of the architecture from day one.

Thanks for reading !!

I would strongly recommend to have a thorough understanding of the concepts and the examples covered in both these articles.

To be fair, implementation of Durable workflows is far straightforward and simple compared to implementation of Durable agents. With durable workflows each registered workflow automatically gets an HTTP trigger without the need for implementing any custom routing logic from your end.

For example, with Durable agents you have to wire your own custom routing logic which starts with the StartOrchestration method.

[Function(nameof(StartOrchestrationAsync))]
public static async Task<HttpResponseData> StartOrchestrationAsync([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = "youragent/run")] HttpRequestData req, [DurableClient] DurableTaskClient client)

To trigger the workflow execution you then require a RunOrchestrationAsync custom method.

[Function(nameof(RunOrchestrationAsync))]
 public static async Task<string> RunOrchestrationAsync([OrchestrationTrigger] TaskOrchestrationContext context)

Then invoke the workflow Orchestration

Invoke-RestMethod -Method Post -Uri http://localhost:7001/api/youragent/run

Refer to this article for step by step process that demonstrates Durable multi agent orchestration in MAF.

Implementation of HITL for Durable agents is even more complex.

You first have to define StartOrchestrationAsync and RunOrchestrationAsync methods and then under the RunOrchestrationAsync method, create an external event that waits for the user response.

[Function(nameof(RunOrchestrationAsync))]
public static async Task RunOrchestrationAsync([OrchestrationTrigger] TaskOrchestrationContext context)
{

HumanApproval humanResponse;

humanResponse = await context.WaitForExternalEvent<HumanApproval>(
eventName: "HumanApproval", timeout: TimeSpan.FromHours(1));      

}

Then implement a custom routing trigger to handle the user input.

[Function(nameof(HumanApprovalAsync))]
 public static async Task<HttpResponseData> HumanApprovalAsync(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "hitl/notification/{instanceId}")] HttpRequestData req, string instanceId,[DurableClient] DurableTaskClient client)
 {
     var humanapproval = await req.ReadFromJsonAsync<HumanApproval>();    
     await client.RaiseEventAsync(instanceId, "HumanApproval", humanapproval);
     HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
     return response;
 }

To trigger the workflow execution

$body = @{
    input = "Some Text"    
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
    -Uri http://localhost:{Port no set in your launchsettings.json file}/api/hitl/run `
    -ContentType application/json `
    -Body $body

and to invoke the approval process

$json = '{"IsApproved":"Yes"}'

Invoke-RestMethod `
-Uri "http://localhost:{Port no set in your launchsettings.json file}/api/hitl/notification/{InstanceId from StartOrchestrationAsync method}" `
-Method Post `
-ContentType "application/json" `
-Body $json

Refer to this article for detailed steps involved for HITL in MAF durable agents.

But with HITL (Human In The Loop) for Durable workflows , there is no need to maintain all these complexities. Durable workflows natively handles all of it.

Implementation

We will use the use case from my previous article on MAF durable workflows.

Only addition in this case would be the introduction of property IsApproved to the _Response object and introducing RequestPort to the workflow.

_Response* *Object Earlier Version >>

public sealed class _Response
{
    [JsonPropertyName("id")]
    public string Id { get; set; } = string.Empty;

    [JsonPropertyName("inputnumber")]
    public string InputNumber { get; set; } = string.Empty;

    [JsonPropertyName("squareroot")]
    public string SquareRoot { get; set; } = string.Empty;
}

_Response Object New Version >>

public sealed class _Response
{
    [JsonPropertyName("id")]
    public string Id { get; set; } = string.Empty;

    [JsonPropertyName("inputnumber")]
    public string InputNumber { get; set; } = string.Empty;

    [JsonPropertyName("squareroot")]
    public string SquareRoot { get; set; } = string.Empty;

    [JsonPropertyName("isapproved")]
    public Boolean IsApproved { get; set; }
}

RequestPort

RequestPort requestPort = RequestPort.Create<_Response, _Response>("NotificationApproval");

add the RequestPort as an Edge to the workflow.

RequestPort requestPort = RequestPort.Create<_Response, _Response>("NotificationApproval");

WorkflowBuilder builder = new(typeDetectionExecutor);

Workflow workflow = builder.AddEdge(typeDetectionExecutor, squareRootcalculatorExecutor)
.AddEdge(squareRootcalculatorExecutor, requestPort)
.AddEdge(requestPort, sendNumberNotificationExecutor)
.WithOutputFrom(sendNumberNotificationExecutor).WithName("NumberDetector").Build();

That's all.. No need for any complex custom routing logic and handling external events through the code.

Execute the Durable Function and it auto creates the underlying endpoints

To trigger the workflow just invoke the endpoints through PowerShell

$json = '{"inputnumber":"12"}'
Invoke-RestMethod -Uri "http://localhost:7001/api/workflows/NumberDetector/run" -Method POST -ContentType "application/json" -Body $json

It creates an Orchestration Id in the DTS

Above, an OrchestrationId 782ad04696204eaa8161c66c27b11a20 is created.

Now use the OrchestrationId to invoke HITL for the worklfow.

$json = '{
  "eventName": "NotificationApproval",
  "response": { "isapproved": true}
}'

Invoke-RestMethod `
-Uri "http://localhost:7001/api/workflows/NumberDetector/respond/782ad04696204eaa8161c66c27b11a20" `
-Method Post `
-ContentType "text/json" `
-Body $json

where isapproved is the new added property in the _Response object, NumberDetector is the name of the workflow and the eventName NotificationApproval used in the invocation above is the name of the RequestPort that we created earlier.

RequestPort requestPort = RequestPort.Create<_Response, _Response>("NotificationApproval");

In the DTS (Durable Task Scheduler) dashboard the orchestration status is Completed.

The workflow setup

Workflow workflow = builder.AddEdge(typeDetectionExecutor, squareRootcalculatorExecutor)
.AddEdge(squareRootcalculatorExecutor, requestPort)
.AddEdge(requestPort, sendNumberNotificationExecutor)
.WithOutputFrom(sendNumberNotificationExecutor).WithName("NumberDetector").Build();

The SendNumberNotificationExecutor Executor code

internal sealed class SendNumberNotificationExecutor() : Executor<_Response>("SendNumberNotificationExecutor")
{
    [YieldsOutput(typeof(string))]
    public override async ValueTask HandleAsync(_Response response, IWorkflowContext context, CancellationToken cancellationToken = default)
    {        
        if (response.IsApproved == true)
        {
            await context.YieldOutputAsync($"The approval is approved");
        }
        else
        {
            await context.YieldOutputAsync($"The approval is rejected");

        }
    }
}

One interesting aspect with Durable workflows is that, its possible to invoke the orchestration through your custom **runId .**In the below example , I used a custom runId = 123

$json = '{"inputnumber":"12"}'

Invoke-RestMethod `
-Uri "http://localhost:7001/api/workflows/NumberDetector/run?runid=123" `
-Method Post `
-ContentType "text/json" `
-Body $json

Invoking the approval process with runid =123

$json = '{
  "eventName": "NotificationApproval",
  "response": { "isapproved": true}
}'

Invoke-RestMethod `
-Uri "http://localhost:7001/api/workflows/NumberDetector/respond/123" `
-Method Post `
-ContentType "text/json" `
-Body $json

Execution >>

Conclusion

As mentioned earlier in the article, implementation of Human In The Loop (HITL) for Durable workflows is far less simpler and pretty straightforward compared to the Human In The Loop (HITL) implementation for Durable agents. This eases out lot of behind the scene complexities that is required to maintain the durable workflows in MAF.

I hope this article and the examples in it were detailed enough to get you started on Human In The Loop (HITL) process for Durable workflows.

Thanks for reading !!!

Another article focused on setting up Azure Durable agents with Docker Durable Task Scheduler (DTS) Emulator. In that article, we had to expose and manage custom API endpoints to trigger and control the agent orchestration process which requires additional implementation.

But with workflows running as durable workflows there is no need to define custom endpoints for workflow invocation. The durable workflow runtime automatically handles workflow execution , persistence, checkpointing and orchestration behind the scenes.

In this article we will see how Durable workflows can be implemented in MAF.

Use Case

The use case in this article is a more simplified version of the use case that I used in my article that was an introduction to the workflow execution. The reason I simplified the use case is for two reasons

• The use case was pretty complex and I received feedback from some readers suggesting that it made them quite confused.

• The use case extensively used switch/conditions to set up conditional executors which unfortunately does not work in Durable workflows at the time of this writing. I have reported the issue on MAF GitHub.

Link : https://github.com/microsoft/agent-framework/issues/6722

A simplified use case in this article

PrimeNumberDetector >> SquareRootCalculator >> NotificationSender

PrimeNumberDetector : Detects if a given number is a prime number.

SquareRootCalculator : Calculates the square root of the given number.

NotificationSender : Sends the findings of the above two executors.

Think of it as a serial workflow execution.

SetUp

Ensure that you have DTS running. You can refer to this article on how to setup Durable Task Scheduler (DTS) on Docker .

Create a new Azure Function project and add the following references.

dotnet add package Azure;
dotnet add package Azure.AI.OpenAI;
dotnet add package Microsoft.Agents.AI;
dotnet add package Microsoft.Extensions.AI;
dotnet add package Microsoft.Extensions.Configuration;
dotnet add package Microsoft.Extensions.DependencyInjection;
dotnet add package Microsoft.Extensions.Hosting;
dotnet add package Microsoft.Agents.AI.Hosting.AzureFunctions--prerelase;
dotnet add package Microsoft.Azure.Functions.Worker.Builder;
dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore;
dotnet add package Microsoft.Azure.Functions.Worker.Extensions.DurableTask;
dotnet add package  Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged;

Of the above ,ensure that you don't miss to reference the following two libraries in the project.

Microsoft.Azure.Functions.Worker.Extensions.DurableTask;
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged;

Otherwise you will face issue that is highlighted in the following GitHub post.

https://github.com/microsoft/agent-framework/issues/5927

Not referencing the above two libraries, will result in you having to declare a dummy orchestrator.

public static class MyDummyOrchestrator
{
    [Function(nameof(MyDummyOrchestrator))]
    public static Task RunOrchestrator(
        [OrchestrationTrigger] TaskOrchestrationContext context)
    {
        return Task.CompletedTask;
    }
}

This is because the function worker fails to find an entry point of execution.

These are the major packages and version numbers that I have referenced in the project.

Code

Implementation is pretty straightforward.

After the above artifacts in place, add the following code to read the settings from appsettings.json in Program.cs of the project.

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Read the credentials and register a Chatclient as a keyedservice.

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

ServiceCollection servicecollection = new();

builder.Services.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)
                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
                .AsIChatClient()
    )
);

In the next step, register the ChatClientAgent in the hosted DI container to identify if the given number is a Prime number or a Non Prime number.

servicecollection.AddSingleton<ChatClientAgent>(sp =>
{
    Func<ChatClientAgentOptions> func = () =>
    {
        return new ChatClientAgentOptions
        {
            ChatOptions = new ChatOptions
            {
                Instructions = "You are a helpful agent. You check if a given number is a prime number or a non prime number",
                ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<DetectionResult>()
            },
            Name = "Number Detector",
            Id = "1"
        };
    };

    return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"), options: func());

});

Register another ChatClientAgent in the hosted DI container that calculates the square root of the provided number.

servicecollection.AddSingleton<ChatClientAgent>(sp =>
{
    Func<ChatClientAgentOptions> func = () =>
    {

        return new ChatClientAgentOptions
        {

            ChatOptions = new ChatOptions
            {
                Instructions = "You are a helpful assistant.You calculate the square root of the provided number",
                ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<_Response>()
            },
            Name = "SquareRootCalculator",
            Id = "2"

        };

    };

return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"), options: func());
});

For the ResponseFormat for the above two agents create the underlying class structure.

public sealed class DetectionResult
{
    [JsonPropertyName("numberType")]
    [JsonConverter(typeof(JsonStringEnumConverter))]
    public NumberType numberType { get; set; }

    [JsonPropertyName("reason")]
    public string Reason { get; set; } = string.Empty;

    [JsonPropertyName("id")]
    public string Id { get; set; } = string.Empty;

    [JsonPropertyName("inputnumber")]
    public string InputNumber { get; set; } = string.Empty;

}

public sealed class _Response
{
    [JsonPropertyName("id")]
    public string Id { get; set; } = string.Empty;

    [JsonPropertyName("inputnumber")]
    public string InputNumber { get; set; } = string.Empty;

    [JsonPropertyName("squareroot")]
    public string SquareRoot { get; set; } = string.Empty;
}

The NumberType property in the DetectionResult class is an Enum type.

public enum NumberType
{
    PrimeNumber,
    NotPrimeNumber,
    UnSure
}

The Input object maps to the user input.

internal sealed class Input
{
    [JsonPropertyName("id")]
    public string Id { get; set; } = String.Empty;

    [JsonPropertyName("inputnumber")]
    public string InputNumber { get; set; } = String.Empty;
}

Scopes to be used for shared states

internal static class NumbervalueConstants
{
    public const string NumbervalueScope = "Numbervalue";
    public const string NumberTypeScope = "Numbertype";
}

TypeDetectionExecutor >>

The TypeDetectionExecutor identifies if given number is a Prime number or a Non Prime number through the first agent Number Detector declared earlier.

Input to the executor is the Input object and output is the _Response object.

internal sealed class TypeDetectionExecutor : Executor<Input, DetectionResult>
{
    private readonly AIAgent _typeDetectionAgent;

    public TypeDetectionExecutor(AIAgent typeDetectionAgent) : base("TypeDetectionExecutor")
    {
        this._typeDetectionAgent = typeDetectionAgent;
    }

    [MessageHandler]
    public override async ValueTask<DetectionResult> HandleAsync(Input input, IWorkflowContext context, CancellationToken cancellationToken = default)
    {
        var Input = new Input { Id = Guid.NewGuid().ToString(), InputNumber = (input.InputNumber) };
        await context.QueueStateUpdateAsync(Input.Id, Input, scopeName: NumbervalueConstants.NumbervalueScope);
        var output = await _typeDetectionAgent.RunAsync(input.InputNumber);
        var detectionResult = JsonSerializer.Deserialize<DetectionResult>(output.Text);
        detectionResult.Id = Input.Id;
        return detectionResult;
    }
}

We store the Input object as value with Input.Id being the key to the shared state through the NumbervalueScope.

await context.QueueStateUpdateAsync(Input.Id,Input, scopeName: NumbervalueConstants.NumbervalueScope);

SquareRootCalculatorExecutor >>

This executor calculates the square root of the given value through the second agent SquareRootCalculator declared earlier.

Input to executor is DetectionResult object and output is _Response object.

internal sealed class SquareRootCalculatorExecutor : Executor<DetectionResult, _Response>
{
    public readonly AIAgent _squarerootagent;

    public SquareRootCalculatorExecutor(AIAgent squarerootagent) : base("SquareRootCalculatorExecutor")
    {
        this._squarerootagent = squarerootagent;
    }

    [MessageHandler]
    public override async ValueTask<_Response> HandleAsync(DetectionResult detectionResult, IWorkflowContext context, CancellationToken cancellationToken = default)
    {

        var input = await context.ReadStateAsync<Input>(detectionResult.Id, scopeName: NumbervalueConstants.NumbervalueScope);
        var output = await this._squarerootagent.RunAsync(input.InputNumber);
        var response = JsonSerializer.Deserialize<_Response>(output.Text);
        response.InputNumber = input.InputNumber;
        response.Id = input.Id;
        await context.QueueStateUpdateAsync(input.Id, detectionResult, scopeName: NumbervalueConstants.NumberTypeScope);
        return response;
    }
}

In the above code, we read input through the shared state NumbervalueScope

var input = await context.ReadStateAsync<Input>(detectionResult.Id, scopeName: NumbervalueConstants.NumbervalueScope);

which then acts as the input to the agent as follows

var output = await this._squarerootagent.RunAsync(input.InputNumber);

Store detectionResult to the shared state through scope NumberTypeScope

await context.QueueStateUpdateAsync(input.Id, detectionResult, scopeName: NumbervalueConstants.NumberTypeScope);

SendNumberNotificationExecutor >>

The Input to the executor is _Response object. The executor YieldsOutput of type string.

internal sealed class SendNumberNotificationExecutor() : Executor<_Response>("SendNumberNotificationExecutor")
{
    [YieldsOutput(typeof(string))]
    public override async ValueTask HandleAsync(_Response response, IWorkflowContext context, CancellationToken cancellationToken = default)
    {
        var numbertype = await context.ReadStateAsync<DetectionResult>(response.Id, scopeName: NumbervalueConstants.NumberTypeScope);
        await context.YieldOutputAsync($"The value {response.InputNumber} is a {numbertype.numberType} and its square root is {response.SquareRoot}");
    }
}

Now that we have all the underlying structure and objects ready, time to piece them together.

Build service and fetch the agent from ServiceProvider as a ChatClientAgent.

ServiceProvider serviceProvider = servicecollection.BuildServiceProvider();
var agent = serviceProvider.GetServices<ChatClientAgent>();
List<ChatClientAgent> chatclientagent = new(agent);

Assign the chatclientagents to the executors.

var typeDetectionExecutor = new TypeDetectionExecutor(chatclientagent[0]);
var squareRootcalculatorExecutor = new SquareRootCalculatorExecutor(chatclientagent[1]);

Output of the workflow will be through the SendNumberNotificationExecutor

SendNumberNotificationExecutor sendNumberNotificationExecutor = new();

Build the workflow and assign the Edges

WorkflowBuilder builder = new(typeDetectionExecutor);

Workflow workflow = builder.AddEdge(typeDetectionExecutor, squareRootcalculatorExecutor)
.AddEdge(squareRootcalculatorExecutor, sendNumberNotificationExecutor)
.WithOutputFrom(sendNumberNotificationExecutor).WithName("NumberDetector").Build();

NumberDetector is the workflow name and acts as the endpoint to be invoked through http invoke method.

Set the host and assign the workflow to it.

sing IHost app = FunctionsApplication
.CreateBuilder(args)
.ConfigureFunctionsWebApplication()
.ConfigureDurableWorkflows(options => options.AddWorkflow(workflow))
Build();
app.Run();

That's all.. Go ahead and test it through PowerShell or Curl.

I tested it through PowerShell using the following script.

$json = '{"inputnumber":"13"}'

Invoke-RestMethod `
-Uri "http://localhost:7001/api/workflows/NumberDetector/run" `
-Method Post `
-ContentType "text/json" `
-Body $json

Timeline >>

History >>

Flow >>

You might wonder how does workflow know about property inputnumber sent through the request .

Basically the workflow auto identifies the property of the input object to the first executor in the workflow.

In this case the first executor to the workflow is TypeDetectionExecutor that has Input object which is the input to the executor which in turn has a property named InputNumber(JsonPropertyName("inputnumber")).

This is how the workflow identifies the property. Following is the code snippet for the clarification.

TypeDetectionExecutor :

internal sealed class TypeDetectionExecutor : Executor<Input, DetectionResult>

Input :

internal sealed class Input
{
    [JsonPropertyName("id")]
    public string Id { get; set; } = String.Empty;

    [JsonPropertyName("inputnumber")]
    public string InputNumber { get; set; } = String.Empty;
}

Execution >>

Conclusion

Durable Functions are a great way to build reliable, long-running and stateful workflows without having to manage the complexity of checkpoints or recovery mechanisms manually.

Through this article I tried to showcase how to design and develop Durable workflows for seamless process execution. I hope this article was helpful enough to get you started on Durable Workflows.

Thanks for reading !!!

• Which agent handled the request?

• Which tool was invoked?

• How long did each step take?

• Where did the failure occur?

• Why is the workflow slower than expected?

Without proper observability, answering these questions is very difficult.

This is where Open Telemetry, Azure Application Insights and .NET Aspire come together. They provide a powerful way to gain visibility into what's happening inside your Microsoft Agent Framework applications. Instead of relying on console logs and guesswork, you can trace requests end-to-end, monitor agent interactions, measure performance and quickly identify bottlenecks.

In this article, we'll build a Microsoft Agent Framework application running in Docker, integrate it with Azure Application Insights and use Aspires dashboard to visualize telemetry in real time.

UseCase

We will use an use case from this post where an agent runs as a background service and the input to the agent is pushed from Azure Service Bus.

SetUp

Before we move to the OpenTelemetry implementation, we will have to set up Aspire service in Docker and the Log Analytics workspace on Azure.

Pull up the Docker desktop and run the following command in the Docker terminal.

docker run --rm -it  -p 18888:18888  -p 4317:18889  -p 4318:18890  -d --name aspire-dashboard  mcr.microsoft.com/dotnet/aspire-dashboard:latest

Once installed , navigate to http://localhost:18888/login . The login page would prompt for a token value

Navigate to the Containers tab and under Logs you will find Aspire Dashboard details. We get Dashboard URL, Login URL with the embedded token and the corresponding gRPC and HTTP URLs.

or run the following command in the Docker terminal.

docker ps

Enter the token value and you will land up on the Aspire Dashboard

Set up Log Analytics workspace and Application Insights resource, search for Log Analytics workspace and Application Insights in Azure Marketplace.

While setting up Application Insights you will have to select an option to select the Log Analytics workspace.

The overall setup for these two resources is pretty straightforward.

If required, you can also change the Log Analytics Workspace for the Application Insights.

In the next step, add the following resources to the project

dotnet add package Azure.Monitor.OpenTelemetry.Exporter
dotnet add package OpenTelemetry.Logs
dotnet add package OpenTelemetry.Metrics
dotnet add package OpenTelemetry.Resources
dotnet add package OpenTelemetry.Trace
dotnet add package OpenTelemetry.Instrumentation.Http
dotnet add package System.Diagnostics

Then add the following telemetry services

 builder.Services.AddOpenTelemetry()
.WithTracing(tracing =>
{
    tracing
        .SetSampler(new AlwaysOnSampler())
        .SetResourceBuilder(
        ResourceBuilder.CreateDefault()
        .AddService("MyApp"))   
        .AddSource("MyApp.Source")                      
        .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))
        .AddHttpClientInstrumentation()
        .AddConsoleExporter()
        .AddAzureMonitorTraceExporter(options =>
        {
         options.ConnectionString = "AppLicationInsights Connection String"
                ;
        });
});

 builder.Logging.ClearProviders();
 builder.Logging.AddConsole();
 builder.Logging.SetMinimumLevel(LogLevel.Trace);

Lets break down the major aspects of the above code :

The following code sets the service name that appears in the telemetry. Without a service name the app traces appears under a generic or auto-generated name.

.AddService("MyApp"))

Define a source MyApp.Source for the service MyApp that listens to the activities created in it.

.AddSource("MyApp.Source")

Now configure OpenTelemetry to to export traces, metrics, and logs to an OTLP collector. In our case the OTLP collector is an Aspire service running on Docker.

.AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))

You might wonder where did port 4317 come from.

Recall that we had configured 4317 while setting up the Aspire Docker container. So 4317 is the host port and 18889/18890 is the container port.

The next part of the code adds enrichment to logs when one service is calling another service using HTTP. This basically means that OpenTelemetry automatically adds extra context (metadata) to the logs, traces and spans about the outgoing HTTP request.

.AddHttpClientInstrumentation()

The next piece of code displays the trace to the console window during execution. This part can be optional as I don't feel it does provides much of an value addition. It simply makes the traces visible during execution.

 .AddConsoleExporter()

The following piece of code exports the logs to the Azure Applications Insight resource that we created earlier.

.AddAzureMonitorTraceExporter(options =>
{
options.ConnectionString = "AppLicationInsights Connection String";
}     

The connection string is available through the Applications Insight dashboard.

In the following code , we first clear all the default loggers that ASP.NET adds. If required we add the logging info to the console and then set the minimum logging level to Trace which implies that all the details Debug, Info, Warning etc should be logged.

builder.Logging.ClearProviders();
builder.Logging.AddConsole();
builder.Logging.SetMinimumLevel(LogLevel.Trace);

In the Background Service, which in our case is named Worker we set different levels of span/traces.

First, define an ActivitySource called MyApp.Worker under the StartAsync operation.

private static readonly ActivitySource Activity = new("MyApp.Worker");

Next, define an Activity called Worker.Start and trace/spans under it

using var activity_start = Activity.StartActivity("Worker.Start", ActivityKind.Server);

activity_start.SetTag("worker.name", "Worker_1");
activity_start.SetTag("Activity Name", activity_start.DisplayName);
activity_start.SetTag("Source Name", activity_start.Source.Name);

and then under RunAsync event which is a method that runs as a Background service.

Note that we have a different Activity called Worker.Run where different sets of trace/spans are registered.

using var activity = Activity.StartActivity("Worker.Run", ActivityKind.Server);

 activity?.SetTag("receiver.name", "promptqueue");           
 activity?.SetTag("receiver.activity", "servicebusdata");
 activity?.SetTag("operation.type", "background-job");
 activity?.SetTag("operationstatus", "start");
 activity?.SetTag("servicebus.ingestion.start", "promptqueue");

Trace the token usage by the agent

AgentResponse response = await agent.RunAsync(message.Body.ToString(), session);     
Console.WriteLine(response.Text);
activity?.SetTag("InputTokeCount", response.Usage.InputTokenCount);
activity?.SetTag("OutputTokeCount", response.Usage.OutputTokenCount);
activity?.SetTag("TotalTokenCount", response.Usage.TotalTokenCount);

Complete Code

Program.cs >>

using Azure;
using Azure.AI.OpenAI;
using Azure.Messaging.ServiceBus;
using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using System.Diagnostics;

internal class Program

{
    private async static Task Main(string[] args)

    {
        HostApplicationBuilder builder = Host.CreateApplicationBuilder();
        var configuration = new ConfigurationBuilder()
      .SetBasePath(Directory.GetCurrentDirectory())
      .AddJsonFile("appsettings.json", optional: false)
      .Build();

        var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

        builder.Services.AddKeyedChatClient("ChatClient", (sp => new AzureOpenAIClient(
                 new Uri(configuration["AppSettings:EndPoint"]), credential)
                     .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
   .AsIChatClient()));

        builder.Services.AddSingleton<AIAgent>(sp =>
        {
            Func<ChatClientAgentOptions> func = () =>
            {
                return new ChatClientAgentOptions
                {
                    ChatOptions = new ChatOptions
                    {

                        Instructions = "You are a helpful stock market analysis assistant"
                    }
                };

            };

            return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"), options: func());
        }

       );

        builder.Services.AddSingleton(sp =>
        {
            return new ServiceBusClient(configuration["AppSettings:AzureQueue"], new ServiceBusClientOptions
            {
                TransportType = ServiceBusTransportType.AmqpTcp
            });
       });
        
        builder.Services.AddOpenTelemetry()
      .WithTracing(tracing =>
      {
          tracing
              .SetSampler(new AlwaysOnSampler())
              .SetResourceBuilder(
              ResourceBuilder.CreateDefault()
              .AddService("MyApp")) 
              .AddSource("MyApp.Worker")                
              .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))                                                                                              
              .AddHttpClientInstrumentation() 
              .AddConsoleExporter()
              .AddAzureMonitorTraceExporter(options =>
              {
                  options.ConnectionString = "Application Insight Connection String";
              });
      });
        //docker ps
        builder.Logging.ClearProviders();
        builder.Logging.AddConsole();
        builder.Logging.SetMinimumLevel(LogLevel.Trace);
        builder.Services.AddHostedService<Worker>();
        using IHost host = builder.Build();
        await host.RunAsync().ConfigureAwait(false);
    }

    internal sealed class Worker(AIAgent agent, ServiceBusClient servicebusClient,IHostApplicationLifetime appLifetime, ILogger<Worker> logger, IHost host) : IHostedService
    {
        private AgentSession? session;
        private Task? backgroundTask;
        private static readonly ActivitySource Activity = new("MyApp.Worker");

        public async Task StartAsync(CancellationToken cancellationToken)
        {

            using var activity_start = Activity.StartActivity("Worker.Start", ActivityKind.Server);

           
                activity_start.SetTag("worker.name", "Worker_1");
                activity_start.SetTag("Activity Name", activity_start.DisplayName);
                activity_start.SetTag("Source Name", activity_start.Source.Name);
           

            session = await agent.CreateSessionAsync(cancellationToken);
            backgroundTask = RunAsync(appLifetime.ApplicationStopping);
        }


        public async Task RunAsync(CancellationToken cancellationToken)
        {
            await Task.Delay(1000, cancellationToken);

            var receiver = servicebusClient!.CreateReceiver("promptqueue");

            while (!cancellationToken.IsCancellationRequested)
            {
                using var activity = Activity.StartActivity("Worker.Run", ActivityKind.Server);
                activity?.SetTag("receiver.name", "promptqueue");           
                activity?.SetTag("receiver.activity", "servicebusdata");
                activity?.SetTag("operation.type", "background-job");
                activity?.SetTag("operationstatus", "start");
                activity?.SetTag("servicebus.ingestion.start", "promptqueue");

                ServiceBusReceivedMessage message = await receiver.ReceiveMessageAsync(cancellationToken: cancellationToken);

                activity?.SetTag("servicebus.ingestion.end", "promptqueue");

                if (message == null)
                {
                    continue;
                }
                Console.WriteLine("----------------------------------------------------------------------------------------------------------------------------");
                Console.WriteLine("");
                activity?.SetTag("AgentInput", message.Body.ToString());
                activity?.SetTag("SessionId", session.ToString());
                AgentResponse response = await agent.RunAsync(message.Body.ToString(), session);              
                Console.WriteLine(response.Text);
                activity?.SetTag("InputTokeCount", response.Usage.InputTokenCount);
                activity?.SetTag("OutputTokeCount", response.Usage.OutputTokenCount);
                activity?.SetTag("TotalTokenCount", response.Usage.TotalTokenCount);
                Console.WriteLine("");
                Console.WriteLine("----------------------------------------------------------------------------------------------------------------------------");
                await receiver.CompleteMessageAsync(message);
                activity?.SetTag("operationstatus", "end");
            }

        }

        public async Task StopAsync(CancellationToken cancellationToken)
        {
            if (backgroundTask != null)
            {
                await backgroundTask;

            }
        }
    }

}

Run the app and check the Logs options in Application Insights and you will see the traces.

KQL Queries

We can leverage KQL queries to query and fetch detailed insights from these trace logs.

union traces, requests, dependencies
| order by timestamp desc

Expanding customDimensions gets the token usage details

requests
| where name == "Worker.Start"
| order by timestamp desc

Gets the the traces for event the Worker.Start

requests
| where customDimensions["worker.name"] == "Worker_1"
| order by timestamp desc

Trace details for worker Worker_1

requests
| project timestamp,name,duration,success
| order by duration desc

Duration and success status

requests
| where customDimensions["TotalTokenCount"] >100
| order by timestamp desc

Details of requests that costs more than 100 tokens.

requests
| where duration >60000
| order by duration 

Gets the details of requests having a duration >60000

Aspire Dashboard

Navigate to the Apsire dashboard thorough http://localhost:18888/traces that was configured earlier

Execution >>

Conclusion

Through this article, I demonstrated the most viable options by which Observability in Microsoft Agent Framework through Open Telemetry in Azure Application Insights and Aspire can be implemented.

I would personally prefer Observability implementation in MAF through Azure Application Insights because of strong KQL support with the flexibility of leveraging KQL queries which Aspire lacks. Added to that, Azure Application Insights also seamlessly integrates with Grafana to implement rich dashboard experience which I would possibly cover in another article.

I hope this article helps you get started with OpenTelemetry implementation for Microsoft Agent Framework.

Thanks for reading !!!

Think of AG-UI as HTTP protocol for AI Agents. With AG-UI its now possible to call and render tools through agents invoked from your frontends. Before AG-UI all frontend calls to AI agents required custom integration but AG-UI has made it the integration pretty straightforward.

Most people get confused between AG-UI, MCP and A2A. The following table from https://docs.ag-ui.com/introduction clears the distinction between all the three protocols.

In this article, I will not delve into the in-depth details of AG-UI. Instead, I will focus on its implementation. You can refer to the AG-UI documentation here and here.

There are two approaches through which AG-UI Integration with Microsoft Agent Framework can be implemented.

• Backend Tool Rendering

• Frontend Tool Rendering

In Backend Tool Rendering , the function tools are defined on the server and the tools are executed on the server through client calls. The client receives updates about tool execution progress and the results are streamed to the client in real time.

In Frontend Tool Rendering , the function tools are registered and defined on the client and the tools get executed in the client environment . The results are sent back to the server to be incorporate into the server responses.

In this article I will demonstrate implementation of server side tool rendering.

We will have two functions :

• ReturnCityTemperature >> Returns temperature of a given city

• ReturnCountryCapital >> Returns capital city of a given country

We will use a single agent to handle requests for both the methods.

SetUp

AG-UI Server >>

The first step is to create an AG-UI server.

Create a new ASP.NET core application and add the following packages

dotnet add package Azure
dotnet add package Azure.AI.OpenAI
dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.DependencyInjection
dotnet add package Microsoft.Extensions.Logging
dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore

Add appsetting.json to the project

"AppSettings": { 
    "Chat_DeploymentName": "Deployment Name",
    "EndPoint": "Azure OpenAI endpoint",
    "ApiKey": "Azure OpenAI API key"
}

In launchSettings.json, configure the ports on which the server should listen.

{
  "profiles": {
    "AGUIServer": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "https://localhost:49408;http://localhost:49409"
    }
  }
}

In the above settings , the application is configured to listen on ports 49408 (HTTPS) and 49409 (HTTP). For this article, we will use 49408 on https.

Code

Now that we have all the underlying artifacts in place, add the following code to read the settings from appsettings.json

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Create a DI container

 ServiceCollection servicecollection = new ServiceCollection();

Read the credentials and register Chatclient

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

servicecollection.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)
                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
   .AsIChatClient()
    )
);

Register an AI Agent in the DI container

servicecollection.AddScoped<AIAgent>(sp =>
       {
           Func<ChatClientAgentOptions> func = () =>

           {
               return new ChatClientAgentOptions
               {

                   ChatOptions = new ChatOptions
                   {
                      Instructions = "You are a helpful assistant.",
                   },
                    Id = "1",
                    Name = "HelpfulAgent"                  
               };

           };
           return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"), options: func());
       });

We define the required request and response objects for CityTemperature and CountryCapital.

CityTemperatureSearchRequest & CityTemperatureSearchResponse >>

 public class CityTemperatureSearchRequest
 {
     public string City { get; set; }
 }

 public class CityTemperatureSearchResponse
 {
     public string City { get; set; }
     public string Temperature { get; set; }
 }

CountryCapitalSearchRequest & CountryCapitalSearchResponse >>

 public class CountryCapitalSearchRequest
 {
     public string Country { get; set; }
 }

 public class CountryCapitalSearchResponse
 {
     public string Country { get; set; }
     public string Capital { get; set; }
 }

Next, create serialization metadata for both request and response types.

[JsonSerializable(typeof(CountryCapitalSearchRequest))]
[JsonSerializable(typeof(CountryCapitalSearchResponse))]
internal sealed partial class CountryCapitalSerializerContext : JsonSerializerContext;


[JsonSerializable(typeof(CityTemperatureSearchRequest))]
[JsonSerializable(typeof(CityTemperatureSearchResponse))]
internal sealed partial class CityTemperatureSerializerContext : JsonSerializerContext;

Register the above two serialization options and add the AIAgent support via AG-UI to the app.

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
        builder.Services.AddHttpClient().AddLogging();
        builder.Services.ConfigureHttpJsonOptions(options => options.SerializerOptions.TypeInfoResolverChain.Add(CountryCapitalSerializerContext.Default));
        builder.Services.ConfigureHttpJsonOptions(options => options.SerializerOptions.TypeInfoResolverChain.Add(CityTemperatureSerializerContext.Default));
        builder.Services.AddAGUI();

Following delegates return the underlying data

ReturnCountryCapital>>

 public static Func<CountryCapitalSearchRequest, CountryCapitalSearchResponse> ReturnCountryCapital = (CountryCapitalSearchRequest) =>

{
    switch (CountryCapitalSearchRequest.Country)
    {

        case "India":

            return new CountryCapitalSearchResponse
            {

                Country = "India",
                Capital = "New Delhi"
            };
            break;

        case "USA":

            return new CountryCapitalSearchResponse
            {

                Country = "USA",
                Capital = "Washington"
            };
            break;


        case "Germany":

            return new CountryCapitalSearchResponse
            {

                Country = "Germany",
                Capital = "Berlin"
            };
            break;

        case "Russia":

            return new CountryCapitalSearchResponse
            {

                Country = "Russia",
                Capital = "Moscow"
            };
            break;
    }

    return new CountryCapitalSearchResponse
    {

        Country = CountryCapitalSearchRequest.Country,
        Capital = "Unknown"
    };

};

ReturnCityTemperature >>

public static Func<CityTemperatureSearchRequest, CityTemperatureSearchResponse> ReturnCityTemperature = (CityTemperatureSearchRequest) =>

{
    switch (CityTemperatureSearchRequest.City)
    {

        case "Mumbai":

            return new CityTemperatureSearchResponse
            {

                City = "Mumbai",
                Temperature = "40"
            };

            break;

        case "Pune":

            return new CityTemperatureSearchResponse
            {

                City = "Pune",
                Temperature = "41"
            };

            break;

        case "Delhi":

            return new CityTemperatureSearchResponse
            {

                City = "Delhi",
                Temperature = "42"
            };

            break;

        case "Chennai":

            return new CityTemperatureSearchResponse
            {

                City = "Chennai",
                Temperature = "43"
            };
            break;
    }

    return new CityTemperatureSearchResponse
    {

        City = CityTemperatureSearchRequest.City,
        Temperature = "Unknown"
    };

};

Register the above two delegates in the DI container as AIFunction with the corresponding SerializerOptions defined earlier.

  servicecollection.AddSingleton<AIFunction>(sp =>
      {
          return AIFunctionFactory.Create(ReturnCityTemperature, new AIFunctionFactoryOptions { Name = "ReturnCityTemperature", Description = "Gets the current weather for a specific city", SerializerOptions = CityTemperatureSerializerContext.Default.Options });
      }

  );

  servicecollection.AddSingleton<AIFunction>(sp =>
    {
        return AIFunctionFactory.Create(ReturnCountryCapital, new AIFunctionFactoryOptions { Name = "ReturnCountryCapital", Description = "Gets the capital city for a specific country.", SerializerOptions = CountryCapitalSerializerContext.Default.Options });
    }
);

Now create a DI container and fetch list of all AIFunction and ChatClientAgent

ServiceProvider serviceprovider = servicecollection.BuildServiceProvider();

var chatlient = serviceprovider.GetServices<ChatClientAgent>();

var aifunctions = serviceprovider.GetServices<AIFunction>();

List<ChatClientAgent> lstchatclient = new(chatlient);

List<AITool> functions = new(aifunctions);

Create an agent from the chatclient and register the ToolFunctions.

 var agent = lstchatclient[0].ChatClient.AsAIAgent(

     new ChatClientAgentOptions
     {
         ChatOptions = new ChatOptions
         {
             Tools = functions,
             Instructions = "You return capital city of a country and you also provide temperature of a city.You will use only the data provided to you and not use any external data"
         }
     }
  );

Expose the above MAF agent through an AG-UI endpoint.

WebApplication app = builder.Build();      
app.MapAGUI("/", agent);
await app.RunAsync();

Run the server and verify that it is listening on https://localhost:{port number}.

In our case it will be https://localhost:49408

Now that the server is up and running the next step is to configure a client that can invoke server side function tools.

AG-UI Client >>

Create a new console application project and add the following packages

dotnet add package Microsoft.Agents.AI;
dotnet add package Microsoft.Agents.AI.AGUI;
dotnet add package Microsoft.Extensions.AI;

In the Main method of Program.cs, create a AGUIChatClient through an HTTP client that references to the agent on the AGUI server at https://localhost:49408

 string serverUrl = "https://localhost:49408";

 using HttpClient httpClient = new()
 {
     Timeout = TimeSpan.FromSeconds(60)
 };

 AGUIChatClient chatClient = new(httpClient, serverUrl);

 AIAgent agent = chatClient.AsAIAgent(
     name: "HelpfulAgent",
     description: "AG-UI Client Agent");

 AgentSession session = await agent.CreateSessionAsync();

Create a conversation history and send messages to the agent on the server.

  List<ChatMessage> messages =
  [
      new(ChatRole.System, "You are a helpful assistant.")
  ];

messages.Add(new ChatMessage(ChatRole.User, "What is temperature in Mumbai and what is capital of USA ?"));

With AG-UI in MAF, we can extend the client streaming to expose the following content types.

FunctionCallContent >> It contains details of the invoked function including the function name and arguments used if any.

FunctionResultContent >> It contains results of the function invocation and the results are exposed in json format.

TextContent >> Contains the textual response generated by the agent.

ErrorContent >> Contains errors if any.

await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(messages, session))
   {

       foreach (var content in update.Contents)
       {
           if (content is Microsoft.Extensions.AI.FunctionCallContent functioncallcontent)
           {
               Console.ForegroundColor = ConsoleColor.DarkCyan;
               Console.WriteLine($"\n[Function Call - Name: {functioncallcontent.Name}]");
               Console.ResetColor();

               foreach (var args in functioncallcontent.Arguments)
               {
                   Console.ForegroundColor = ConsoleColor.Cyan;
                   Console.WriteLine($"\n[Function Arguments - Argument Name : {args.Key} - Argument Value : {args.Value}");

                   Console.ResetColor();
               }
           }

           if (content is Microsoft.Extensions.AI.FunctionResultContent functionresultcontent)
           {
               Console.ForegroundColor = ConsoleColor.Red;
               Console.Write(($"\n[Function raw output : {functionresultcontent.Result}]"));
               Console.WriteLine();
               Console.ResetColor();
           }

           if (content is Microsoft.Extensions.AI.TextContent textContent)
           {                   
               Console.ForegroundColor = ConsoleColor.Green;
               Console.Write(textContent.Text);
               Console.ResetColor();
           }

           if (content is Microsoft.Extensions.AI.ErrorContent errorContent)
           {
               Console.ForegroundColor = ConsoleColor.Red;
               Console.WriteLine($"Error : {errorContent.Message}");
               Console.ResetColor();

           }
       }
   }

That's all. Test the client execution with a prompt .

What is the temperature in Delhi and capital of USA ?

Ensure that the server is up and running.

Execution >>

Conclusion

In conclusion, AG-UI is a great step forward for front end tool interactions with agents deployed on server. It reduces the complexity of implementing custom integration for client interaction with agents running on server.

I hope this article helped you understand the caveats of implement AG-UI solution for Microsoft Agent Framework.

Thanks for reading !!!

The use case used in the article was pretty straightforward wherein there were two agents .

• Content generating agent

• Content review agent

Content generated by the first agent is reviewed, modified and pushed forward for further processing by the second agent.

But such an straightforward approach might carry potential risks and might not be feasible in real life scenarios particularly for crucial business processes that adhere to strict compliances.

We wouldn't want agents to work autonomously and take decisions without proper human reviews . This is where Human In The Loop (HITL) plays an important role.

This article focusses on introducing Human In The Loop (HITL) concept for Azure Durable functions in MAF.

Also in the previous article, the user input was embedded in the code and there wasn't a mechanism to make the input dynamic . This article covers that aspect as well where the user input is dynamic and is sent while REST API invocation.

If you would like to skip the writeup you can view the flow walkthrough here

Flow >>

The flow is pretty straightforward.

The entry point is an HTTP Trigger that accepts the input as HttpRequestData and creates an orchestration instance that invokes an Orchestration method called RunOrchestrationAsync.

In RunOrchestrationAsync method, the agent creates the content on the topic provided and a notification is sent to the user(human) to approve or reject it. In the meantime the flow pauses for the human response.

Once the RunOrchestrationAsync receives the response from the user(human), the method invokes the PublishContent activity if approved else invokes the NotifyUseForRejection activity if rejected . This concludes the orchestration execution.

SetUp

To get started, create a new Azure Function project and apply settings covered in my previous article including setting up of the Docker DTS Emulator.

Ensure Docker DTS Emulator is up and navigate to http://localhost:8082/ to ensure that it is running.

Code

After the above artifacts are in place, add the following code to read the settings from appsettings.json in Program.cs of the project.

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Read the credentials and register a Chatclient

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

ServiceCollection servicecollection = new();

builder.Services.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)
                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
                .AsIChatClient()
    )
);

In the next step, register the following agent in the hosted DI container.

FootballContentCreatorAgent >>

servicecollection.AddSingleton<ChatClientAgent>(sp =>

{
    Func<ChatClientAgentOptions> func = () =>
   {
       return new ChatClientAgentOptions
       {
           ChatOptions = new ChatOptions
           {
                Instructions = "You are a content creator.You are good at writing reviews for football club.Be concise and please stick to the topic.",
           },
           Name = "FootballContentCreatorAgent",
           Id = "1"
       };
   };

    return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"), options: func());

});

Build the service and fetch agents from the ServiceProvider as ChatClientAgent.

ServiceProvider serviceProvider = servicecollection.BuildServiceProvider();

var agent = serviceProvider.GetServices<ChatClientAgent>();

List<ChatClientAgents> chatclientagent = new(agent);

Then add these agents as DurableAgent to the Azure Function worker.

using IHost app = FunctionsApplication
.CreateBuilder(args)
.ConfigureFunctionsWebApplication()
.ConfigureDurableAgents(options => options.AddAIAgent(chatclientagent[0], timeToLive: TimeSpan.FromHours(1)))
.Build();

app.Run();

Create a new class file called FunctionTigger.cs and add two classes Input and HumanApproval.

Input >>

public class Input
 {
   [JsonPropertyName("input")]
   public string input { get; set; }
 }

HumanApproval>>

 public class HumanApproval
 {
     [JsonPropertyName("IsApproved")]
     public string IsApproved { get; set; }
 }

Note : I have kept the structure pretty simple. You can add additional properties based on your use case. For ex , a Feedback property in the HumanApproval
class that accepts feedback from the human(user) prior to an approval/rejection.

Also add a Record object called TextResponse that accepts AgentResponses as input.

 public record TextResponse(string Response);

StartOrchestrationAsync >>

As shown in the flowchart, StartOrchestrationAsync will be the method that acts as an entry point when the AzureFunction is triggered through an POST request to the HTTP endpoint.

 [Function(nameof(StartOrchestrationAsync))]
 public static async Task<HttpResponseData> StartOrchestrationAsync(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "hitl/run")] HttpRequestData req,
    [DurableClient] DurableTaskClient client)
 {
     var input = await req.ReadFromJsonAsync<Input>();
     string instanceid = await client.ScheduleNewOrchestrationInstanceAsync(orchestratorName: nameof(RunOrchestrationAsync), input: input);

   var response = req.CreateResponse(System.Net.HttpStatusCode.Accepted);
    
   return response;
 }

The endpoint for the orchestration in the above example is "hitl/run".

A new orchestration instance is created in this method and which in turn invokes the RunOrchestrationAsync method.

RunOrchestrationAsync >>

 [Function(nameof(RunOrchestrationAsync))]
public static async Task RunOrchestrationAsync([OrchestrationTrigger] TaskOrchestrationContext context)
{
    DurableAIAgent FootballContentCreatorAgent = context.GetAgent("FootballContentCreatorAgent");

    var input = context.GetInput<Input>();

    AgentSession Session = await FootballContentCreatorAgent.CreateSessionAsync();

    AgentResponse<TextResponse> content = await FootballContentCreatorAgent.RunAsync<TextResponse>(
        message: input.input,
        session: Session);

    TextResponse agentresponse = content.Result;

    await context.CallActivityAsync(nameof(NotifyUserForApproval), agentresponse);


    HumanApproval humanResponse;

    humanResponse = await context.WaitForExternalEvent<HumanApproval>(
          eventName: "HumanApproval",
          timeout: TimeSpan.FromHours(1));

    if (humanResponse.IsApproved == "Yes")
    {
        await context.CallActivityAsync(nameof(PublishContent), agentresponse);       
        context.SetCustomStatus($"Content published successfully at {context.CurrentUtcDateTime.ToLongTimeString}");            

    }
    else
    {
        await context.CallActivityAsync(nameof(NotifyUserForRejection), agentresponse);
        context.SetCustomStatus("Content is rejected by human reviewer. Publishing content...");

    }
  
}

RunOrchestrationAsync is method is the most important method that processes the user input.

Lets breakdown the above method :

We first create a new instance of DurableAIAgent from the context . The user input from the http endpoint is stored in the input variable of type T declared earlier.

DurableAIAgent FootballContentCreatorAgent = context.GetAgent("FootballContentCreatorAgent");
var input = context.GetInput<Input>();

Create a new AgentSession. Executing the agent returns an output of type AgentResponse.

Then retrieve the underlying TextResponse from the Result property into the variable agentresponse.

AgentSession Session = await FootballContentCreatorAgent.CreateSessionAsync();

AgentResponse<TextResponse> content = await FootballContentCreatorAgent.RunAsync<TextResponse>(
                message: input.input,
                session: Session);

TextResponse agentresponse = content.Result;

Execute CallActivityAsync that invokes a method named NotifyUserForApproval with agentresponse created above as the parameter to the method.

await context.CallActivityAsync(nameof(NotifyUserForApproval), agentresponse);

Next, the method waits for humanapproval event through WaitForExternalEvent for a timespan of one hour.

HumanApproval humanResponse = await context.WaitForExternalEvent<HumanApproval>(
eventName: "HumanApproval",
timeout: TimeSpan.FromHours(1));

Once the approval is approved/rejected the underlying methods are invoked through CallActivityAsync based on the type of input received.

 if (humanResponse.IsApproved == "Yes")
 {
     await context.CallActivityAsync(nameof(PublishContent), agentresponse);    
     context.SetCustomStatus($"Content published successfully at {context.CurrentUtcDateTime.ToLongTimeString}");
 }
 else
 {
     await context.CallActivityAsync(nameof(NotifyUserForRejection), agentresponse);
     context.SetCustomStatus("Content is rejected by human reviewer. Publishing content...");
 }

NotifyUserForApproval >>

In real life use case an email or other forms of notifications with an link to the endpoint should be sent to for approval or rejections. This link is generated from the HumanApprovalAsync method explained later in the execution flow.

 [Function(nameof(NotifyUserForApproval))]
 public async static Task<string> NotifyUserForApproval(
   [ActivityTrigger] TextResponse content,
   FunctionContext functionContext)
 {
     return $"Please review the following generated content{content}";
 }

PublishContent >>

 [Function(nameof(PublishContent))]
 public async static Task<string> PublishContent(
[ActivityTrigger] TextResponse content,
FunctionContext functionContext)
 {
     return $"The following content {content} is approved and is published";
 }

NotifyUserForRejection>>

 [Function(nameof(NotifyUserForRejection))]
 public async static Task<string> NotifyUserForRejection(
[ActivityTrigger] TextResponse content,
FunctionContext functionContext)
 {
     return $"The following content {content} is rejected ";
 }

HumanApprovalAsync>>

The approval/rejection endpoint with hitl/notification/{instanceId} is created in HumanApprovalAsync method and a response is returned with IsApproved value set based on the user input.

 [Function(nameof(HumanApprovalAsync))]
 public static async Task<HttpResponseData> HumanApprovalAsync(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "hitl/notification/{instanceId}")] HttpRequestData req, string instanceId,
    [DurableClient] DurableTaskClient client)
 {
     var humanapproval = await req.ReadFromJsonAsync<HumanApproval>();
    
     await client.RaiseEventAsync(instanceId, "HumanApproval", humanapproval);

     HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);

     return response;
 }

You might ask how would the user approve/reject the request.

This can be done through the HTTPost that invokes the notification endpoints created in the HumanApprovalAsync method. Below is the PowerShell call to the endpoints.

HTTP POST request to the StartOrchestrationAsync method >>

$body = @{
    input = "Write a review for the football club FC Barcelona"    
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
    -Uri http://localhost:{Port no set in your launchsettings.json file}/api/hitl/run `
    -ContentType application/json `
    -Body $body

HTTP POST request to the HumanApprovalAsync method >>

$json = '{"IsApproved":"Yes"}'

Invoke-RestMethod `
-Uri "http://localhost:{Port no set in your launchsettings.json file}/api/hitl/notification/{InstanceId from StartOrchestrationAsync method}" `
-Method Post `
-ContentType "application/json" `
-Body $json

DTS Dashboard for User Approval >>

DTS Dashboard for User Rejection >>

Execution

https://youtu.be/dK2j7v-Is7Y

Conclusion

Through this article, I tried to explore a simple implementation of Human-in-the-Loop (HITL) for Azure Durable Functions.

Although the sample focuses on a basic approval workflow it highlights the core concepts required to pause an orchestration, wait for human input, and resume execution based on the outcome.

I hope this article helps you understand the fundamentals and sets the required foundation for building more business centric HITL solutions in your applications.

Thanks for reading !!!

This article will be a step ahead and is focused on setting up a Multi Agent Orchestration based on the similar principal.

The use case in this article is a multi-agent workflow involving two agents.

The first agent, the Football Content Creator Agent is responsible for generating a review of a football club. The second agent, the Football Content Reviewer Agent evaluates and reviews the generated content and produces a more refined version of the original review generated by Content Creator Agent.

I had used a similar use case in one of my earlier article that deep dived into workflow orchestration pattern.

https://www.azureguru.net/workflow-orchestration-patterns-in-microsoft-agent-framework#group-chat-orchestration-pattern

In this example, you could use the same agent for content creation and review but I used two separate agents just to give an idea on how execution of durable multi agents can be orchestrated .

SetUp

To get started, create a new Azure Function project and apply settings covered in my previous article including setting up of the Docker DTS Emulator.

Ensure Docker DTS Emulator is up and navigate to http://localhost:8082/ to ensure that it is running.

Code

After the above artifacts are in place, add the following code to read the settings from appsettings.json in Program.cs of the project.

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Read the credentials and register a Chatclient

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

ServiceCollection servicecollection = new();

builder.Services.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)
                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
                .AsIChatClient()
    )
);

In the next step, register the following two AIAgents in the hosted DI container.

FootballContentCreatorAgent >>

servicecollection.AddSingleton<ChatClientAgent>(sp =>

{
    Func<ChatClientAgentOptions> func = () =>
   {
       return new ChatClientAgentOptions
       {
           ChatOptions = new ChatOptions
           {
                Instructions = "You are a content creator. You create content for football teams. Be concise and please stick to the topic.",
           },
           Name = "FootballContentCreatorAgent",
           Id = "1"
       };
   };

    return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"), options: func());

});

FootballContentReviewerAgent >>

servicecollection.AddSingleton<ChatClientAgent>(sp =>

{
    Func<ChatClientAgentOptions> func = () =>
   {
       return new ChatClientAgentOptions
       {
           ChatOptions = new ChatOptions
           {
               Instructions = "You are a content reviewer.You review created content for football teams and make necessary changes to it.Be concise and please stick to the topic.",
           },
           Name = "FootballContentReviewerAgent",
           Id = "2"
       };
   };
    return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"), options: func());

});

Build the service and fetch agents from the ServiceProvider as ChatClientAgent.

ServiceProvider serviceProvider = servicecollection.BuildServiceProvider();

var agents = serviceProvider.GetServices<ChatClientAgent>();

List<ChatClientAgents> chatclientagent = new(agents);

Then add these agents as DurableAgent to the Azure Function worker.

using IHost app = FunctionsApplication
.CreateBuilder(args)
.ConfigureFunctionsWebApplication()
.ConfigureDurableAgents(options => { options.AddAIAgents(chatclientagent).DefaultTimeToLive = TimeSpan.FromHours(1); })
.Build();

app.Run();

The time to live for the agents is configured to an hour.

Orchestration

Define a type record that holds the AgentResponse in a new class file called FunctionTrigger.cs

public record TextResponse(string Response);

The orchestration occurs in two steps Start and Run.

Start is the trigger point that defines the route , creates an orchestration instance for an DurableTaskClient and returns a response of type HttpResponseData.

StartOrchestrationAsync >>

 [Function(nameof(StartOrchestrationAsync))]

public static async Task<HttpResponseData> StartOrchestrationAsync([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = "footballagent/run")] HttpRequestData req, [DurableClient] DurableTaskClient client)

 {

var instanceId = await client.ScheduleNewOrchestrationInstanceAsync(orchestratorName: nameof(RunOrchestrationAsync));

     var response = req.CreateResponse(HttpStatusCode.Accepted);
         await response.WriteAsJsonAsync(new
         {
             message = "Orchestration started.",
             InstanceId = instanceId
         }
      );
     return response;
 }

Run is where an agent orchestration pipeline is triggered post creation of an orchestration instance through StartOrchestrationAsync

RunOrchestrationAsync >>

 [Function(nameof(RunOrchestrationAsync))]
 public static async Task<string> RunOrchestrationAsync([OrchestrationTrigger] TaskOrchestrationContext context)
 {
     DurableAIAgent FootballContentCreatorAgent = context.GetAgent("FootballContentCreatorAgent");
     DurableAIAgent FootballContentReviewerAgent = context.GetAgent("FootballContentReviewerAgent");

     AgentSession Session = await FootballContentCreatorAgent.CreateSessionAsync();

     AgentResponse<TextResponse> initial = await FootballContentCreatorAgent.RunAsync<TextResponse>(
         message: "Summarize the glory of football club FC Barcelona",
         session: Session);

     AgentResponse<TextResponse> refined = await FootballContentReviewerAgent.RunAsync<TextResponse>(
      message: $"Improve and expand the review further while keeping it under 1000 words: {initial.Result.Response}",
      session: Session);

     return refined.Result.Response;
 }

In the code above through **TaskOrchestrationContext ,**we get a list of available agents from the context.

The AgentResponse output generated by FootballContentCreatorAgent acts as input to the FootballContentReviewerAgent. The input is reviewed and post modification the modified reviewed is returned as the final output.

Add the above two functions to the FunctionTrigger.cs file created earlier.

Our endpoint is "footballagent/run". Invoke it through Powershell.

Invoke-RestMethod -Method Post -Uri http://localhost:7001/api/footballagent/run

Post invocation , underlying artifacts are visible on the Durable Task Scheduler Dashboard.

Orchestration >>

Entities >>

Agents >>

Execution >>

Conclusion

In this article, I tried to explore how Azure Durable Functions can be used to orchestrate a multi-agent execution within the Microsoft Agent Framework. I hope this article helps you understand how durable orchestrations can be leveraged to coordinate multi agent execution effectively.

Thanks for reading !!!

Instead of managing state, retries, checkpoints and recovery custom built logic, Azure Durable Functions automatically handles them behind the scenes.

You can think of it as a workflow coordinator that orchestrates multiple tasks, waits for external events, schedules timers, and resumes execution even after application restarts or failures. Such implementation make it ideal for business processes that requires Human-in-the-loop (HITL) that may run for minutes, hours, or even days.

Azure Durable Functions uses an event-sourcing model where every action is recorded as an event. When the workflow needs to resume, the orchestrator rebuilds its state by replaying these events without requiring developers to manage state and infrastructure concerns.

In this article I will demonstrate a very basic setup of an Azure Durable Agent in MAF through Docker Emulator for Durable Task Scheduler (DTS) that can run durable and stateful agents.

SetUp

Create a new Azure Function project and add the following references.

dotnet add package Azure;
dotnet add package Azure.AI.OpenAI;
dotnet add package Microsoft.Agents.AI;
dotnet add package Microsoft.Extensions.AI;
dotnet add package Microsoft.Extensions.Configuration;
dotnet add package Microsoft.Extensions.DependencyInjection;
dotnet add package Microsoft.Extensions.Hosting;
dotnet add package Microsoft.Agents.AI.Hosting.AzureFunctions--prerelase;
dotnet add package Microsoft.Azure.Functions.Worker.Builder;
dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore;
dotnet add package Microsoft.Azure.Functions.Worker.Extensions.DurableTask;
dotnet add package  Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged;

Of the above ,ensure that you don't miss to reference the following two libraries in the project.

Microsoft.Azure.Functions.Worker.Extensions.DurableTask;
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged;

Otherwise you will face issue that is highlighted in the following GitHub post.

https://github.com/microsoft/agent-framework/issues/5927

Not referencing the above two libraries, will result in you having to declare a dummy orchestrator.

public static class MyDummyOrchestrator
{
    [Function(nameof(MyDummyOrchestrator))]
    public static Task RunOrchestrator(
        [OrchestrationTrigger] TaskOrchestrationContext context)
    {
        return Task.CompletedTask;
    }
}

This is because the function worker fails to find an entry point of execution.

These are the major packages and version numbers that I have referenced in the project

Docker DTS Emulator >>

Install Docker Desktop if you don't have on your system and then pull the Docker image containing the DTS emulator

docker pull mcr.microsoft.com/dts/dts-emulator:latest

Now run the emulator in the Docker desktop terminal

docker run -d -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest

You can change the port numbers if you want to.

Ensure that the Emulator is up and running.

Navigate to http://localhost:8082/ and you should see the DTS endpoints running on port number 8082.

Add appsetting.json to the project

"AppSettings": 
{ 
    "Chat_DeploymentName": "Deployment Name",
    "EndPoint": "Azure OpenAI endpoint",
    "ApiKey": "Azure OpenAI API key"
}

local.settings.json

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
        "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None",
        "AZURE_OPENAI_ENDPOINT": "Azure OpenAI endpoint",
        "AZURE_OPENAI_DEPLOYMENT_NAME": "Deployment Name"
    }
}

In DURABLE_TASK_SCHEDULER_CONNECTION_STRING settings above, the Endpoint value should match the Endpoint that was set while configuring the Docker DTS Emulator.

launchSettings.json

{
  "profiles": {
    "Azure_Durable_SingleAgent": {
      "commandName": "Project",
      "commandLineArgs": "--port 7001",
      "launchBrowser": false
    }
  }
}

--port 7001 value will be used to send HttpRequest to the running Agent.

host.json

{
    "version": "2.0",
    "logging": {
        "logLevel": {
            "Microsoft.Agents.AI.DurableTask": "Information",
            "Microsoft.Agents.AI.Hosting.AzureFunctions": "Information",
            "DurableTask": "Information",
            "Microsoft.DurableTask": "Information"
        }
    },
    "extensions": {
        "durableTask": {
            "hubName": "default",
            "storageProvider": {
                "type": "AzureManaged",
                "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
            }
        }
    }
}

"DURABLE_TASK_SCHEDULER_CONNECTION_STRING" is the keyword above.

If you are using Azure storage, then there is no need for connectionStringName and type settings but in case you are using Durable Task Scheduler (DTS) which is the recommended approach , then setting type and connectionStringName property is required.

serviceDependencies.json

{
  "dependencies": {
    "appInsights1": {
      "type": "appInsights"
    },
    "storage1": {
      "type": "storage",
      "connectionId": "AzureWebJobsStorage"
    }
  }
}

Code

Implementation is pretty straightforward.

After the above artifacts in place, add the following code to read the settings from appsettings.json in Program.cs of the project.

var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: false)
.Build();

Read the credentials and register a Chatclient

var credential = new AzureKeyCredential(configuration["AppSettings:ApiKey"]);

ServiceCollection servicecollection = new();

builder.Services.AddKeyedChatClient(
    "ChatClient",
    (
        sp =>
            new AzureOpenAIClient(new Uri(configuration["AppSettings:EndPoint"]), credential)
                .GetChatClient(configuration["AppSettings:Chat_DeploymentName"])
                .AsIChatClient()
    )
);

In the next step, register the AIAgent in the hosted DI container.

servicecollection.AddSingleton<ChatClientAgent>(sp =>

{
    Func<ChatClientAgentOptions> func = () =>
   {
       return new ChatClientAgentOptions
       {
           ChatOptions = new ChatOptions
           {
               Instructions = "You are good at explaining topics on history",
           },
           Name = "History",
           Id = "1"

       };
   };

    return new ChatClientAgent(sp.GetKeyedService<IChatClient>("ChatClient"), options: func());

});

Build the service and get the agent from the ServiceProvider as ChatClientAgent.

ServiceProvider serviceProvider = servicecollection.BuildServiceProvider();

var agent = serviceProvider.GetServices<ChatClientAgent>();

List<ChatClientAgent> chatclientagent = new(agent);

Then add this agent as DurableAgent to the Azure Function worker.

 using IHost app = FunctionsApplication
 .CreateBuilder(args)
 .ConfigureFunctionsWebApplication()
 .ConfigureDurableAgents(options => options.AddAIAgent(chatclientagent[0], timeToLive: TimeSpan.FromHours(1)))
 .Build();

 app.Run();

The time to live of agent is configured to to an hour.

The agent name History set during defining the agent will act as the Durable Agent endpoint.

In our example the HttpRequest endpoint and the call will be as follows

Invoke-RestMethod -Method Post `
    -Uri  http://localhost:7001/api/agents/History/run `
    -ContentType text/plain `
    -Body "Tell me more about World war 2"

Port number 7001 comes from the set value in launchSettings.json.

That's all. Go ahead and invoke the call.

I invoked it through PowerShell

You should see the Agent chat history and other details in the DTS Emulator Dashboard.

Execution >>

Conclusion

Leveraging Azure Durable Function for state management of Agents is the most optimal approach and effective approach to build reliable long running workflows that can recover through restarts and process failures without the over head of implementation and maintaining custom processes.

Though the above set up is an example for a very simple use case, in a few upcoming articles I will touch base on more advance use cases.

Till then stay tuned !!!

But for MAF workflows it is possible to achieve HITL without the need for wrapping your AIFunction with ApprovalRequiredAIFunction.

In this article we will be exploring the alternate approach

If you would like to know more about HITL through ApprovalRequiredAIFunction, for Agents, then you can refer to my article on the topic here .

We will use the same use case that I used in my article on MAF Workflows to demonstrate how HITL can be leveraged without ApprovalRequiredAIFunction.

Use Case

This was the flow for the use case used in my previous article on HITL

So, we had an input number N that requires to be identified as a Prime or a non Prime number. If its a Prime number then compute its square root and send the value through Route A .

If its not a Prime number then send it through Route B without its square root.

Now , lets make some changes to the flow to accommodate HITL .

How about we add HITL approval before the value of √N is dispatched to Route A ?

So the flow would be as follows :

                          typeDetectionExecutor
                                   |
           -----------------------------------------------
           |                       |                     |
           v                       v                     v
     PrimeNumber               NotPrimeNumber          Default
           |                       |                     |
           v                       v                     v
PrimeNo_SquareRootExecutor   Executor_RouteB    Unsure_Executor 
           |
           |
           v
      HITL Approval
           |
           |
           v
  -----------------
  |               |
Rejected       Approved
  |               |
  |               |
  v               v
Log Rejection Executor_RouteA

To achieve this we will use a combination of RequestPort and RequestInfoEvent .

RequestPort & RequestInfoEvent >>

RequestPort can be defined as a channel through which executors can send and receive responses. But you might ask that it is already possible to do that through SendMessages or YieldsOutput .

The drawback with both SendMessages or YieldsOutput is that they cant emit responses as Events.

Recall that SendMessages sends messages to all the connected executors while YieldsOutput sends the output to the caller and both do not emit responses.

When an executor sends a message to RequestPort, it emits a RequestInfoEvent and then external inputs can listen to those RequestInfoEvent and then RequestInfoEvent sends it responses back to the workflow through RequestPort .

This is similar to ToolApprovalRequestContent but it requires an AIFunction wrapped in ApprovalRequiredAIFunction and AIFunction to be invoked through an agent.

With RequestPort, AIFunction invocation is not required as the workflow can read the input and receive output through RequestPort which is then emitted in form of RequestInfoEvent.

To implement this we will have to go back and make some changes to workflow edges and the PrimeNo_SendDetails_RouteA_Executor that routes the square root value to RouteA.

Refer above flowchart and code for PrimeNo_SendDetails_RouteA_Executor in my earlier article here.

Code

First, add a new property named IsApproved to the _Response object of the workflow.

_Response >>

Earlier version :

public sealed class _Response
{
    [JsonPropertyName("decision")]
    public string Decision { get; set; } = string.Empty;

    [JsonPropertyName("reason")]
    public string Reason { get; set; } = string.Empty;

    [JsonPropertyName("id")]
    public string Id { get; set; } = string.Empty;

    [JsonPropertyName("squareroot")]
    public double squareroot { get; set; } = 0.00;
}

Changed version :

public sealed class _Response
{
    [JsonPropertyName("decision")]
    public string Decision { get; set; } = string.Empty;

    [JsonPropertyName("reason")]
    public string Reason { get; set; } = string.Empty;

    [JsonPropertyName("id")]
    public string Id { get; set; } = string.Empty;   
   
    [JsonPropertyName("squareroot")]
     public double squareroot { get; set; } = 0.00;
    
    [JsonPropertyName("approved")]
    public string IsApproved { get; set; } = string.Empty; 
}

RequestPort >>

 RequestPort humanApprovalPort = RequestPort.Create<_Response, _Response>("Approval");

RequestPort instance is of type T<TRequest,TResponse>.

Output of PrimeNo_SquareRootExecutor which is of type _Response acts as TRequest for RequestPort and the output from RequestPort which is also of type _Response acts as an input to SendDetails_Executor_RouteA.

SendDetails_Executor_RouteA >>

Earlier version :

internal sealed class PrimeNo_SendDetails_RouteA_Executor() : Executor<_Response>("PrimeNo_SendDetails_RouteA_Executor")
{
    [YieldsOutput(typeof(string))]
    public override async ValueTask HandleAsync(_Response result, IWorkflowContext context, CancellationToken cancellationToken = default)
    {
        var number = await context.ReadStateAsync<InputNumber>(result.Id, scopeName: NumbervalueConstants.NumbervalueScope);
        await context.YieldOutputAsync($"Details for {number.Value} sent to Route A: {result.squareroot}", cancellationToken);

    }
}

Changed version :

 internal sealed class PrimeNo_SendDetails_RouteA_Executor() : Executor<_Response>("PrimeNo_SendDetails_RouteA_Executor")
 {
     [YieldsOutput(typeof(string))]

     public override async ValueTask HandleAsync(_Response result, IWorkflowContext context, CancellationToken cancellationToken = default)
     {
         var number = await context.ReadStateAsync<InputNumber>(result.Id, scopeName: NumbervalueConstants.NumbervalueScope);

         if (result.IsApproved == "Yes")
         {
             await context.YieldOutputAsync($"Request is approved !!! Details for {number.Value} sent to Route A with square root value of: {result.squareroot}", cancellationToken);
         }
         else
         {
             await context.YieldOutputAsync($"Request is rejected !!! Details of rejection for {number.Value} will be logged ", cancellationToken);
         }
         
     }
 }

The change above, is that in the changed version , we are reading the IsApproved property value which was set through RequestPort and based on the output from approval/rejection , a decision is made to route the square root value or log the rejection.

But, how to set the value for IsApproved property ?

This is done through ExternalResponse process where the executor pauses its execution awaiting an input from external system. But then you might wonder how to invoke the ExternalResponse process.This is done by adding the RequestPort as part of the workflow Edge.

A method named HandleExternalRequest is defined later in the article to that handles ExternalResponse.

Recall that earlier we declared RequestPort with name humanApprovalPort.

Edges >>

Earlier version :

.AddEdge(PrimeNo_SquareRootExecutor,SendDetails_Executor_RouteA)
.WithOutputFrom(SendDetails_Executor_RouteA, SendDetails_Executor_RouteB, SendEmail_Executor_Unsure);

Changed version :

.AddEdge(PrimeNo_SquareRootExecutor, humanApprovalPort)
.AddEdge(humanApprovalPort, SendDetails_Executor_RouteA)
.WithOutputFrom(SendDetails_Executor_RouteA, SendDetails_Executor_RouteB, SendEmail_Executor_Unsure);

In the workflow event we then invoke ExternalResponse that returns a response object which is then sent to the Executor.

WorkflowEvent>>

Earlier version :

var workflow = builder.Build();

string input = "Your Input Number/Letter";

await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, new ChatMessage(ChatRole.User, input));

  await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
  await foreach (WorkflowEvent evt in run.WatchStreamAsync().ConfigureAwait(false))
  {
    if (evt is WorkflowOutputEvent outputEvent)
    {
     Console.WriteLine($"{outputEvent}");
    }
  }

Changed version :

var workflow = builder.Build();

string input = "Your Input Number/Letter";

await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, new ChatMessage(ChatRole.User, input));

  await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
  await foreach (WorkflowEvent evt in run.WatchStreamAsync().ConfigureAwait(false))
  {
    if (evt is WorkflowOutputEvent outputEvent)
    {
     Console.WriteLine($"{outputEvent}");
    }    
    
    if (evt is RequestInfoEvent requestInputEvt)
    {
     ExternalResponse response =  HandleExternalRequest(requestInputEvt.Request);
   await run.SendResponseAsync(response);
   }
 
  }

HandleExternalRequest >>

 private static ExternalResponse HandleExternalRequest(ExternalRequest request)
 {
     if (request.TryGetDataAs<_Response>(out var response))
     {

         Console.WriteLine($"Would you like to approve/reject ? please reply Y to approve and N to reject");

         response.IsApproved = Convert.ToString(Console.ReadLine()?.Equals("Y", StringComparison.OrdinalIgnoreCase) == true ? "Yes" : "No");

         return request.CreateResponse(response);
     }

     throw new NotSupportedException($"Request {request.PortInfo.RequestType} is not supported");
 }

As the output from PrimeNo_SquareRootExecutor is of type _Response, the _Response object becomes a part of ExternalRequest which in turn exposes the IsApproved property through the out variable response and post human interaction , the modified request is sent back as a response.

Execution >>

Conclusion

Through this article I tried to explore a more unique approach where HITL does not necessarily had to be dependent on AIFunction invocation through an AIAgent.

Instead, we saw how human approval can be introduced at different stages of an workflow through simple call mechanism through RequestPort and the responses can be handled through ExternalResponse object.

Go ahead and give it a try.

Thanks for reading !!!