Meet Microsoft Agent Framework — Your .NET Agent Toolkit

This article is part of C# Advent Calendar 2025 initiative by Matthew D. Groves. You'll find other helpful articles and tutorials published daily by community members and experts there, so make sure to check it out every day.

Microsoft recently released the Microsoft Agent Framework (MAF), a new open-source SDK for building AI agents and multi-agent workflows, with full support for .NET and Python.

At its core, Microsoft Agent Framework brings together the best of two earlier approaches:

• The enterprise-ready orchestration of Semantic Kernel
• The flexible multi-agent patterns of AutoGen

But unified in a single, modern, .NET-friendly framework.

With Microsoft Agent Framework you can:

• Create simple agents that are powered by LLMs.
• Build complex multi-agent workflows, orchestration pipelines, tool integrations, multi-step reasoning, and more.
• Use standardized abstractions, such as AIAgent, ChatClientAgent, chat clients, etc. which makes swapping LLM providers like OpenAI, Azure OpenAI, Foundry, and others, easy.
• Scale from quick prototypes to production-grade agents and workflows, with support for: monitoring, telemetry, error handling, human-in-the-loop, persistent context, external tool calls, etc.

What is an agent in Microsoft Agent Framework?

An agent is typically an instance of AIAgent or a derived class, which can:

• Hold conversation context (memory), manage state, maintain history.
• Use any compatible LLM (via standard chat-client interfaces) to generate responses.
• Optionally call external tools, such as APIs, code executors, or custom logic, via a protocol, for example the Model Context Protocol (MCP), enabling integration with outside data or services.

For simple use-cases you don’t need a complex setup, just a few lines of code. For more advanced needs, like in multi-agent workflows, orchestration, branching logic, or tool integrations, you can build full-featured agent systems.

Demo:

Let's build an agent that uses tools with Microsoft Agent Framework in .NET.

Step 1. Create a .NET project
Create a .NET Console application. In the Terminal, enter the following code if you want to use Visual Studio Code:

dotnet new console -o ChristmasApp
cd ChristmasApp
code .

Step 2. Authenticate to Azure
Back in your main terminal, authenticate to Azure by requesting a token from the **Azure CLI. You need to install the Azure CLI first. Then, execute the following command:

az login

Then follow the flow (enter credentials or select the account

By the way, we are doing this authentication to Azure to avoid using a key in our code later in order to access Azure OpenAI.

Step 3. Setup the project
Open a new Terminal in Visual Studio Code and install the following NuGet package:

dotnet add package Microsoft.Agents.AI --prerelease

This is the main NuGet package for Microsoft Agent Framework (currently in preview version). Additionally, let's install other support packages for authentication and the base model that will be used:

dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

Step 4. Create a tool
Create a new folder (Tools) and a new file in that folder (ChristmasTools.cs) and add the following code:

using System.ComponentModel;

namespace ChristmasApp.Tools;

public static class ChristmasTools
{
    [Description("Suggest a Christmas gift based on the budget in USD.")]
    public static string SuggestGift([Description("Budget in USD")] decimal budget)
    {
        if (budget < 20) return "A festive mug + hot cocoa mix";
        if (budget < 50) return "A cozy scarf and gloves set";
        if (budget < 100) return "A good hardcover book and holiday candle";
        return "A premium smartwatch or a luxury gift box";
    }
}

Step 5. Declare the agent
Create and use the agent in Program.cs with the following code:

using Azure.Identity;
using Azure.AI.OpenAI;
using OpenAI;

using Microsoft.Extensions.AI;

using ChristmasApp.Tools;

var endpoint = new Uri("https://ai-madrid.openai.azure.com/");
var credential = new AzureCliCredential();
var chatClient = new AzureOpenAIClient(endpoint, credential).GetChatClient("gpt-4o");

var agent = chatClient.CreateAIAgent(
    name: "Christmas Helper",
    instructions: "You are a helpful assistant that suggests Christmas gifts based on a budget.",
    tools: [AIFunctionFactory.Create(ChristmasTools.SuggestGift)]
);

var prompt = "I want to buy a Christmas gift for a friend. My budget is $35. What do you suggest?";
Console.WriteLine("User: " + prompt);

var response = await agent.RunAsync(prompt);
Console.WriteLine("Agent Suggestion: " + response.Text);

• First we define the namespaces we need.
• Then we create an AzureOpenAIClient from our endpoint and deployed model (replace the placeholders).
• Then we create the agent. The most important method is CreateAIAgent. You define the name and instructions, while for tools we include the method that we defined in the previous step.
• Finally, we engage in a conversation with the agent by using the RunAsync method with a prompt. The Text property of the response shows the output generated by the agent.

Step 6. Test and run the project
Use dotnet run command in the terminal to see the agent giving you recommendations about gift suggestion based on your current budget.

** Why Tools Matter**
We mentioned tools, but we didn't defined them yet. Tools let your agent perform deterministic logic (calculations, data lookups, business logic), not just LLM-generated text. They are useful for concrete tasks like fetching data, computations, etc.

Because tools are explicit functions, you avoid depending solely on what the LLM remembers or imagines. Instead, the output is reliable and consistent.

You can combine multiple tools to build more robust agents.

---

I hope that this entry was interesting and useful for you.

Thanks for your time, and enjoy the rest of the C# Advent Calendar 2025 publications!

See you next time,
Luis