Lucy Muturi for Syncfusion, Inc.

Posted on Jan 28 • Originally published at syncfusion.com on Jan 28

Microsoft Agent Framework (Preview): Build AI Agents in .NET

#net #netframework #ai #aiintegration

TL;DR: What if your .NET app didn’t just run code but could reason, collaborate, and make decisions on its own? With the Microsoft Agent Framework preview, that ‘what if’ becomes real, unifying agent intelligence, workflows, and LLM power into one elegant, ready‑to‑build package.

In today’s rapidly evolving AI landscape, developers increasingly rely on intelligent agents to tackle complex, dynamic tasks. The Microsoft Agent Framework (MAF) empowers .NET developers by simplifying the creation, orchestration, and deployment of AI agents. Built on proven technologies, this preview release delivers a unified, production‑ready foundation for agent development.

In this blog, we’ll explore what MAF is, its core components, and how you can start building agents right away.

Let’s begin by clarifying the concept of an AI agent before diving into MAF’s capabilities.

What is an AI agent?

An AI agent is a system that combines reasoning and decision-making capabilities, often powered by Large Language Models (LLMs) with context awareness and tool usage. Agents process user inputs, maintain awareness of conversation history or external data, make decisions, and take actions by invoking functions, APIs, or services. They excel in autonomous, adaptive behaviors such as planning, exploration, and interaction in unstructured environments.

When to use an AI agent?

AI agents are best suited for apps that demand autonomous decision‑making, adaptive planning, trial‑and‑error exploration, or conversation‑driven interactions. Common scenarios include:

Customer support
Education and tutoring
Code generation
Research assistance
Dynamic problem‑solving in unstructured contexts

Note: Avoid using AI agents for highly structured tasks with fixed rules, predictable outcomes, or workflows that require many tools and lack dynamic reasoning.

Agents and workflows: The two core building blocks of Agent systems

Agents and workflows form the foundation of the Microsoft Agent Framework (MAF). They enable developers to build scalable, intelligent systems with both dynamic reasoning and structured orchestration.

Agents

These are individual entities that use LLMs for reasoning, incorporate context (e.g., from knowledge bases or history), and access tools to perform actions. They can be specialized for tasks like analysis or synthesis.

Workflows

Workflows structure complex objectives into sequences or graphs of steps, coordinating agents, tools, or sub-workflows. They add explicit control, enabling non‑linear progress, subtasks, and human‑in‑the‑loop interactions. Together, they create composable, scalable systems where agents provide dynamic intelligence to structured workflows.

The following diagram illustrates a workflow connecting two AI agents and a function.

What is MAF?

Microsoft Agent Framework (MAF) is an open-source .NET library for building AI agents and multi-agent workflows. It simplifies development by providing abstractions, orchestration patterns, and integrations for hosting, monitoring, and evaluation. MAF unifies concepts from the Semantic Kernel (for orchestration) and AutoGen (for multi-agent collaboration), while adding new features such as graph-based workflows and robust state management. It supports multiple AI providers, including OpenAI, Azure OpenAI, and Ollama.

Advantages of MAF over Semantic Kernel and AutoGen

MAF represents an evolution of Semantic Kernel and AutoGen, combining their strengths into a unified framework. MAF stands out for its focus on simplicity, scalability, and production readiness. It eliminates common pain points such as complex model integration and orchestration logic, enabling developers to build agents as easily as a console app. With built-in support for observability, evaluation, and deployment, MAF ensures agents are reliable and maintainable in real-world apps. For developers in the .NET ecosystem seeking adaptive AI solutions, MAF provides a future-proof foundation.

Advantages include:

Unified API: A consistent interface for single and multi-agent systems, reducing complexity.
Simplified orchestration: Easier workflow building and hosting with minimal boilerplate.
Enhanced features: Adds explicit workflows, checkpointing, and better state management, not fully present in predecessors.
Migration support: Guides for transitioning from Semantic Kernel or AutoGen, making it ideal for new projects or upgrades.
Developer-friendly: Focuses on .NET patterns like dependency injection and Minimal APIs for seamless integration.

For developers starting fresh, MAF offers a more comprehensive, production-oriented experience than using Semantic Kernel or AutoGen independently.

Build your first .NET Agent in minutes with MAF

Getting started with MAF is straightforward. Let’s create a simple joke-telling agent using Azure OpenAI.

Prerequisites

.NET 8.0 SDK or later.
Azure OpenAI service endpoint and deployment configured (e.g., with a “gpt-4o-mini” deployment).
The user should have the Cognitive Services OpenAI User or Cognitive Services OpenAI Contributor roles for the Azure OpenAI resource.

Now that our environment is ready, let’s build our first .NET agent with MAF.

Step 1: Create a console app

Set up a new .NET console project that will serve as the starting point for our agent.

dotnet new console -o HelloWorldAgent
cd HelloWorldAgent

Step 2: Install the required packages

Add the following libraries that allow your app to communicate with Azure OpenAI and use the Model‑As‑Agent Framework.

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

Step 3: Update the Program.cs file

Let’s update the Program.cs file. Add the required namespaces, configure the Azure OpenAI client, create the agent with simple instructions, and run it with a prompt.

using Azure;
using Azure.AI.OpenAI;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://your-resource.openai.azure.com/"),
    new AzureKeyCredential("your-api-key")
.GetChatClient("gpt-4o-mini")
.CreateAIAgent(instructions: "You are good at telling jokes.");

// Running the agent
Console.WriteLine(await agent.RunAsync("What do you call a pirate mutiny?"));

Note: We can authenticate using the Azure CLI, but in this example, we use an API key directly.

Step 4: Run the app

Execute the project to verify the connection and see your agent respond in the console using the following command:

dotnet run

Now, you can see the following output in the console.

Console output from a simple .NET agent built with MAF

AI agent abstraction in MAF

The AI Agent abstraction is central to MAF’s power, providing a unified interface for all agent types. It decouples agent logic from specific AI providers, enabling seamless switching between models such as OpenAI or Azure AI. The ChatClientAgent implements an AI Agent and integrates with any IChatClient, supporting tools, instructions, and middleware. This abstraction enables composability: agents can encapsulate workflows or tools, making systems flexible, extensible, and provider-agnostic.

Orchestrate multiple agents with MAF

MAF excels at orchestrating multiple agents to tackle collaborative tasks. Developers can define specialized agents (e.g., writer and editor) and coordinate them using workflow patterns. This enables dynamic handoffs, parallel execution, or group discussions, while supporting complex scenarios such as iterative refinement or ensemble analysis.

Building workflows

Workflows in MAF are graph-based structures that connect agents and functions for multi-step tasks. We can use AgentWorkflowBuilder to define sequences, nesting, or routing. Workflows support checkpointing for resumption and request/response patterns for human intervention, ensuring robust execution.

Types of workflows

MAF supports several orchestration patterns:

Sequential: Chains agents in order (e.g., writer → editor).
Concurrent: Runs agents in parallel and aggregates results.
Handoff: Dynamically transfers control based on context.
GroupChat: Facilitates collaborative conversations with a manager.
Magentic: Enables generalist multi-agent collaboration.

These types allow tailored workflows for diverse use cases.

Concepts in workflow

Executors: Autonomous processing units that receive messages, perform operations, and produce outputs.
Direct Edges: Simple, unconditional connections that route messages directly from one executor to another in the workflow graph.
Workflow Builder: A fluent API tool for constructing workflows by defining executors, edges, and orchestration logic.
Events: Built-in or custom signals that provide observability into workflow execution, such as start, completion, errors, and executor status.

The following code example creates a workflow with two executors. The Uppercase Executor converts input text to uppercase, while the Reverse Text Executor reverses the text and outputs the final result.

using Microsoft.Agents.AI.Workflows;

/// <summary>
/// First executor: converts input text to uppercase.
/// </summary>
Func<string, string> uppercaseFunc = s => s.ToUpperInvariant();
var uppercase = uppercaseFunc.BindAsExecutor("UppercaseExecutor");

ReverseTextExecutor reverse = new();

// Build the workflow by connecting executors sequentially
WorkflowBuilder builder = new(uppercase);
builder.AddEdge(uppercase, reverse)
       .WithOutputFrom(reverse);
var workflow = builder.Build();

// Execute the workflow with input data
await using Run run = await InProcessExecution.RunAsync(workflow, "Hello, World!");
foreach (WorkflowEvent evt in run.NewEvents)
{
    switch (evt)
    {
        case ExecutorCompletedEvent executorComplete:
            Console.WriteLine($"{executorComplete.ExecutorId}: {executorComplete.Data}");
            break;
    }
}

/// <summary>
/// Second executor: reverses the input text and completes the workflow.
/// </summary>
internal sealed class ReverseTextExecutor() : Executor<string, string>("ReverseTextExecutor")
{
    public override ValueTask<string> HandleAsync(string input, IWorkflowContext context, CancellationToken cancellationToken = default)
    {
        // Reverse the input text
        return ValueTask.FromResult(new string(input.Reverse().ToArray()));
    }
}

Refer to the following outputs.

Workflow run output after uppercase and reverse steps

Graph‑based workflow connecting executors for multi‑step tasks

Tips: We can integrate AI agents into workflows using the Agent Framework.

Agents with tools

Agents gain action capabilities through tools, which are external functions, APIs, or services. Tools are registered as AIFunction instances, allowing agents to invoke them automatically when needed. This extends agent functionality beyond mere reasoning, enabling real-world interactions such as data queries and computations.

Here’s a code example to add a weather tool to an agent.

[Description("Get the weather for a given location.")] static string GetWeather(
    [Description("The location to get the weather for.")] string location)
    => $"The weather in {location} is cloudy with a high of 15°C.";

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://your-resource.openai.azure.com/"),
    new AzureKeyCredential("your-api-key"
)
.GetChatClient("gpt-4o-mini")
.CreateAIAgent(
    instructions: "You are a helpful assistant",
    tools: [AIFunctionFactory.Create(GetWeather)]
);
Console.WriteLine(await agent.RunAsync("What is the weather like in Seattle?"));

After executing the code example above, we’ll get the following output.

Agents using tools to perform real‑world actions

Tips: You can add human approval in the loop while using function tools. In MAF, connect to MCP servers as tools for capabilities like database access or web search. Hosted tools, such as Code Interpreter (for code execution) or Bing Grounding (for search), are integrated similarly.

Production and deployment

MAF supports dependency injection, middleware (e.g., authentication, rate limiting), and familiar .NET hosting. We can deploy via containers, Azure, or Aspire for cloud-native setups. Features like checkpointing ensure reliability in long-running workflows.

Built-in monitoring

MAF includes OpenTelemetry for tracing conversations, model usage, performance, and errors. We can enable this feature using the agent.WithOpenTelemetry() method. It easily integrates with Azure Monitor, Grafana, and Aspire dashboards for visualization. Middleware intercepts runs for custom logging or validation, supporting sensitive telemetry when configured.

Evaluation and testing

We can use the Microsoft.Extensions.AI.Evaluation libraries for rigorous testing. Integrate with MSTest or xUnit for automated CI/CD tests. Quality metrics (relevance, coherence, groundedness) use LLM evaluators; safety metrics detect harmful content. Cache responses for regression detection via consistent scoring. We can also enable A/B testing through telemetry to compare variants. CLI tool (dotnet aieval) generates reports.

Conclusion

Thanks for reading! The Microsoft Agent Framework (MAF) in preview represents a significant leap forward for .NET developers building intelligent, autonomous AI systems. By unifying the best of Semantic Kernel and AutoGen into a single, production-focused framework with native graph-based workflows, powerful abstractions, multi-provider support, and built-in observability and evaluation,

Whether you’re adding adaptive intelligence to existing .NET apps or building single agents or complex workflows, MAF empowers .NET developers to create intelligent apps efficiently. Get started with the preview packages now and join the future of agent development on .NET.

If you have any questions, contact us through our support forum, support portal, or feedback portal. We are always happy to assist you!

Related Blogs

This article was originally published at Syncfusion.com

DEV Community