Building AI agents shouldn’t be rocket science. Yet many developers find themselves wrestling with complex orchestration logic, struggling to connect multiple AI models, or spending weeks building hosting infrastructure just to get a simple agent into production.

What if building an AI agent could be as straightforward as creating a web API or console application?

Agents and Workflows

Before we dive deeper, let’s define the two core building blocks of agent systems: agents and workflows. We’ll start by looking at their core components and how they relate to one another

Agents

Across the web, you’ll find many definitions of agents. Some conflicting, some overlapping.

For this post, we’ll keep it simple:

Agents are systems that combine reasoning, context, and tools to pursue objectives.

Let’s break down each of those components:

• Reasoning and decision-making: Agents need reasoning capabilities to decide which actions to take toward their objectives. Today, this is often powered by large language models (LLMs). However, other techniques such as search algorithms, planning systems, or classical AI approaches can also be used.
• Context awareness: Context is the external data or state that informs decision-making. Because models don’t have built-in access to real-time or system-specific information, additional inputs like conversation history, knowledge bases, or enterprise data are required to make informed decisions.
• Tool usage: Tools are discrete, callable capabilities such as APIs, Model Context Protocol (MCP) tools, code execution, or data queries. They typically extend what a system can do but do not make decisions themselves. For example, a weather API provides data, but it does not decide how that data is used. Tools can be used to carry out actions or to gather additional context that informs future decisions.

Agents bring these components together to maintain awareness, make decisions, and act dynamically in pursuit of their goals.

Workflows

As objectives grow in complexity, they need to be broken down into manageable steps. That’s where workflows come in.

Workflows structure complex objectives into sequences of steps, coordinating tasks across people or systems to reach a goal efficiently.

Imagine you’re launching a new feature on your business website. If it’s a simple update, you might go from idea to production in a few hours. But for more complex initiatives, the process might include:

• Requirement gathering
• Design and architecture
• Implementation
• Testing
• Deployment

A few important observations:

• Each step may contain subtasks.
• Different specialists may own different phases.
• Progress isn’t always linear. Bugs found during testing may send you back to implementation.

Success relies on planning, orchestration, and communication across stakeholders.

Agents + Workflows

While workflows can function purely as predetermined sequences, integrating agents adds dynamic decision-making and adaptability, enabling more intelligent and autonomous process management.

Agents, workflows, and their underlying components are all highly composable:

• Agents can call multiple tools
• Tools may encapsulate agent-like behaviors in narrow scopes
• Workflows can sequence agents, tools, and other workflows
• Agents themselves may internally run workflows

Together, this layered architecture supports building flexible, intelligent, and scalable systems.

Meet Microsoft Agent Framework

Microsoft Agent Framework is a comprehensive set of .NET libraries that reduces the complexity of agent development. Whether you’re building a simple chatbot or orchestrating multiple AI agents in complex workflows, Microsoft Agent Framework provides the tools you need to:

• Build agents with minimal boilerplate code
• Orchestrate multi-agent workflows with ease
• Host and deploy agents using familiar .NET patterns
• Monitor and observe agent behavior in production

For more details, see the Introducing Microsoft Agent Framework post in the Foundry blog.

Built on Proven Foundations

Microsoft Agent Framework leverages established technologies to simplify agent development for .NET developers:

• Semantic Kernel – Provides robust orchestration
• AutoGen – Enables advanced multi-agent collaboration and cutting-edge research-driven techniques
• Microsoft.Extensions.AI – Delivers standardized AI building blocks for .NET.

By combining these technologies, Agent Framework offers reliability, flexibility, and a developer-friendly API. This allows you to build and deploy powerful AI agents quickly and efficiently.

Start Simple: Build Your First Agent in Minutes

Getting started with Microsoft Agent Framework is simple. In the following example, you’ll build a creative writing agent that generates engaging short stories.

The fastest way to try it out is to open the Hello World Agents sample in GitHub Codespaces:

If you prefer, you can follow the step-by-step instructions below to set up the project on your own machine.

Step 0: Configure prerequisites

To get started, you’ll need the following:

• .NET 9 SDK or greater
• A GitHub Personal Access Token (PAT) with models scope. You can create one in you can create in your GitHub settings. For more details, see the GitHub documentation

This project can use GitHub-hosted models so you’ll need to provide the GitHub Personal Access Token (PAT) to your application using the GITHUB_TOKEN environment variable.

Windows

setx GITHUB_TOKEN "YOUR-GITHUB-TOKEN"
# Restart your shell to pick up the value

Linux / Mac

export GITHUB_TOKEN="YOUR-GITHUB-TOKEN"

Step 1: Set Up Your Project

1. Create a new C# console application and install the Agent Framework packages:

   dotnet new console -o HelloWorldAgents
   cd HelloWorldAgents
   dotnet add package Microsoft.Agents.AI --prerelease

2. You’ll also need to install the following packages to use the models from GitHub models.

   dotnet add package OpenAI
   dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
   dotnet add package Microsoft.Extensions.AI

Step 2: Write Your Agent

1. Add this code to your Program.cs file to create a story-writing agent:

   using Microsoft.Extensions.AI;
   using Microsoft.Agents.AI;
   using OpenAI;
   using OpenAI.Chat;
   using System.ClientModel;
   
   IChatClient chatClient =
       new ChatClient(
               "gpt-4o-mini",
               new ApiKeyCredential(Environment.GetEnvironmentVariable("GITHUB_TOKEN")!),
               new OpenAIClientOptions { Endpoint = new Uri("https://models.github.ai/inference") })
           .AsIChatClient();
   
   AIAgent writer = new ChatClientAgent(
       chatClient,
       new ChatClientAgentOptions
       {
           Name = "Writer",
           Instructions = "Write stories that are engaging and creative."
       });
   
   AgentRunResponse response = await writer.RunAsync("Write a short story about a haunted house.");
   
   Console.WriteLine(response.Text);

2. Run your application

That’s it! In just a few lines of code, you have a fully functional AI agent.

The Power of Abstraction

Microsoft Agent Framework is designed around powerful abstractions that simplify agent development.

At its core is the AIAgent abstraction, which provides a unified interface for building agents. The flexibility to use any compatible AI model provider comes from Microsoft.Extensions.AI, which standardizes model access through the IChatClient interface.

The ChatClientAgent implementation of AIAgent accepts any IChatClient, allowing you to easily choose between providers such as:

• OpenAI
• Azure OpenAI
• Foundry Local
• Ollama
• GitHub Models
• Many others

This means you can swap providers or integrate new ones without changing your agent code. The same AIAgent interface works seamlessly with:

• Azure Foundry Agents
• OpenAI Assistants
• Copilot Studio
• Many others

If you’ve built agents using different SDKs or platforms, using Microsoft Agent Framework is straightforward. You get a consistent developer experience and can leverage orchestration, hosting, and monitoring features.

Scale Up: Orchestrate Multiple Agents

Single agents are powerful, but real-world scenarios often require multiple specialized agents working together. Maybe your writing agent creates great content, but you also need an editor to polish it, or a fact-checker to verify details.

Agent Framework makes multi-agent orchestration as simple as connecting building blocks.

Adding Specialized Agents

Let’s enhance our story example by adding an editor agent to review and improve the writer’s output:

// Create a specialized editor agent
AIAgent editor = new ChatClientAgent(
    chatClient,
    new ChatClientAgentOptions
    {
        Name = "Editor",
        Instructions = "Make the story more engaging, fix grammar, and enhance the plot."
    });

Building Workflows

Now comes the magic – connecting these agents in a workflow.

1. Install the Microsoft.Agents.Workflows NuGet package:

   dotnet add package Microsoft.Agents.AI.Workflows --prerelease

2. Create a workflow to orchestrates your agents:

   // Create a workflow that connects writer to editor
   Workflow workflow =
       AgentWorkflowBuilder
           .BuildSequential(writer, editor);
   
   AIAgent workflowAgent = await workflow.AsAgentAsync();
   
   AgentRunResponse workflowResponse =
       await workflowAgent.RunAsync("Write a short story about a haunted house.");
   
   Console.WriteLine(workflowResponse.Text);

The Result

Now when you run your application, the writer creates the initial story, and the editor automatically reviews and improves it. The entire workflow appears to the outside world as a single, more capable agent.

This pattern scales to any complexity:

• Research workflows: Researcher → Fact-checker → Summarizer
• Content pipelines: Writer → Editor → SEO Optimizer → Publisher
• Customer service: Intent Triage → Customer Specialist Agent → Quality Reviewer

The key takeaway here is, complex agent systems are compositions of simple, focused agents.

All Types of Workflows

The example above uses a sequential workflow, where agents process tasks one after another, each building on the previous agent’s output. However, Microsoft Agent Framework supports a variety of workflow patterns to fit different requirements:

• Sequential: Agents execute in order, passing results along the chain.
• Concurrent: Multiple agents work in parallel, addressing different aspects of a task simultaneously.
• Handoff: Responsibility shifts between agents based on context or outcomes.
• GroupChat: Agents collaborate in a shared, real-time conversational space.

These flexible workflow types enable orchestration for everything from simple pipelines to dynamic, multi-agent collaboration.

Empower Agents with Tools

Microsoft Agent Framework makes it incredibly easy to give your agents access to external functions, APIs, and services so your agents can take action.

Creating Agent Tools

Let’s enhance our writing agent with some useful tools. In our story example, we might want agents that can do the following:

[Description("Gets the author of the story.")]
string GetAuthor() => "Jack Torrance";

[Description("Formats the story for display.")]
string FormatStory(string title, string author, string story) =>
    $"Title: {title}\nAuthor: {author}\n\n{story}";

Connecting Tools to Agents

Adding these tools to your agent is straightforward. Here’s a modified version of our writer agent configured to use the tools defined earlier.

AIAgent writer = new ChatClientAgent(
    chatClient,
    new ChatClientAgentOptions
    {
        Name = "Writer",
        Instructions = "Write stories that are engaging and creative.",
        ChatOptions = new ChatOptions
        {
            Tools = [
                AIFunctionFactory.Create(GetAuthor),
                AIFunctionFactory.Create(FormatStory)
            ],
        }
    });

Running the application again would result in a formatted story per the template you provided in FormatStory.

**Title: The Haunting of Blackwood Manor**
**Author: Jack Torrance**

On the outskirts of a quaint village, a grand but crumbling mansion, known as Blackwood Manor, loomed against the twilight sky. Locals spoke in hushed tones about the house, claiming it was haunted by the spirits of its former inhabitants, who had mysteriously vanished decades ago. Tales of flickering lanterns, echoing whispers, and the ghostly figure of a woman in white gliding through the halls filled the village’s atmosphere with a sense of dread
//...

Beyond Simple Functions

Because Microsoft Agent Framework builds on Microsoft.Extensions.AI, your agents can use more robust tools including:

• Model Context Protocol (MCP) servers – Connect to external services like databases, APIs, and third-party tools
• Hosted tools – Access server-side tools like Code Interpreter, Bing Grounding, and many more

For example, you could connect to an MCP server that provides database access, web search, or even hardware control. Learn more about building MCP integrations in our MCP client quickstart.

Deploy with Confidence: Hosting Made Simple

Getting agents into production shouldn’t mean learning a new deployment model. Microsoft Agent Framework integrates seamlessly with the .NET hosting patterns you already use.

Minimal Web API Integration

Using your agent in a REST API is a few lines of code.

The code sample below makes use of the Aspire OpenAI client integration with GitHub Models.

1. Install the package

   dotnet add package Aspire.OpenAI --prerelease

2. Configure your connection string in your Web API project user secrets.

   dotnet user-secrets init
   dotnet user-secrets set ConnectionStrings:chat "Endpoint=https://models.github.ai/inference;Key=YOUR-GITHUB-TOKEN"

   Alternatively, you can use the appsettings as shown on the Aspire OpenAI client integration documentation.

3. Once configured, in an ASP.NET Minimal Web API, register your IChatClient:

   builder.AddOpenAIClient("chat")
       .AddChatClient(Environment.GetEnvironmentVariable("MODEL_NAME") ?? "gpt-4o-mini");

4. Install the Microsoft.Agents.AI.Hosting NuGet package

   dotnet add package Microsoft.Agents.AI.Hosting --prerelease

5. Register your agents

   builder.AddAIAgent("Writer", (sp, key) =>
   {
       var chatClient = sp.GetRequiredService<IChatClient>();
   
       return new ChatClientAgent(
           chatClient,
           name: key,
           instructions:
               """
               You are a creative writing assistant who crafts vivid, 
               well-structured stories with compelling characters based on user prompts, 
               and formats them after writing.
               """,
           tools: [
               AIFunctionFactory.Create(GetAuthor),
               AIFunctionFactory.Create(FormatStory)
           ]
       );
   });
   
   builder.AddAIAgent(
       name: "Editor",
       instructions:
           """
           You are an editor who improves a writer’s draft by providing 4–8 concise recommendations and 
           a fully revised Markdown document, focusing on clarity, coherence, accuracy, and alignment.
           """);

6. Once registered, your agents are available anywhere in your app:

   app.MapGet("/agent/chat", async (
       [FromKeyedServices("Writer")] AIAgent writer,
       [FromKeyedServices("Editor")] AIAgent editor,
       HttpContext context,
       string prompt) =>
   {
       Workflow workflow =
           AgentWorkflowBuilder
               .CreateGroupChatBuilderWith(agents =>
                   new AgentWorkflowBuilder.RoundRobinGroupChatManager(agents)
                   {
                       MaximumIterationCount = 2
                   })
               .AddParticipants(writer, editor)
               .Build();
   
       AIAgent workflowAgent = await workflow.AsAgentAsync();
   
       AgentRunResponse response = await workflowAgent.RunAsync(prompt);
       return Results.Ok(response);
   });

Production-Ready Features

Microsoft Agent Framework hosting includes everything you need for production:

• Configuration – Manage agent settings through standard .NET configuration
• Dependency injection – Integrate with your existing DI containers and practices
• Middleware support – Add authentication, rate limiting, or custom logic

Deploy

Microsoft Agent Framework doesn’t reinvent deployment. If you know how to ship a .NET app, you already know how to ship agents.

No new tooling. No special hosting model. Just add agents and deploy wherever .NET runs.

Observe and Improve: Built-in Monitoring

Production agents need observability. Microsoft Agent Framework provides comprehensive monitoring that integrates with your existing observability stack.

OpenTelemetry Integration

Enable detailed telemetry with a single line:

// Enhanced telemetry for all your agents
writer.WithOpenTelemetry();
editor.WithOpenTelemetry();

This captures:

• Conversation flows – Visualize how messages move between agents
• Model usage – Track token consumption, model selection, and costs
• Performance metrics – Monitor response times and throughput
• Error tracking – Identify and debug issues quickly

Rich Dashboards

When connected to your existing observability platforms like:

• Aspire
• Azure Monitor
• Grafana
• Many others

You get detailed insights into agent behavior, helping you optimize performance and identify issues before they affect users.

OpenTelemetry with Aspire

To send agent telemetry to the Aspire dashboard, enable OpenTelemetry and allow sensitive data for richer insights.

Set EnableSensitiveTelemetryData to true when configuring your client:

builder
    .AddAzureChatCompletionsClient("chat", settings =>
    {
        settings.EnableSensitiveTelemetryData = true;
    })
    .AddChatClient(Environment.GetEnvironmentVariable("MODEL_NAME")!);

Then, configure Aspire to recognize telemetry sources:

public static TBuilder ConfigureOpenTelemetry<TBuilder>(this TBuilder builder) where TBuilder : IHostApplicationBuilder
{
    builder.Logging.AddOpenTelemetry(logging =>
    {
      //...
    })
    .AddTraceSource("Experimental.Microsoft.Extensions.AI.*");

    builder.Services.AddOpenTelemetry()
        .WithMetrics(metrics =>
        {
            metrics.AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation()
                .AddRuntimeInstrumentation()
                .AddMeter("Experimental.Microsoft.Extensions.AI.*");
        })
        .WithTracing(tracing =>
        {
            tracing.AddSource(builder.Environment.ApplicationName)
                .AddSource("Experimental.Microsoft.Extensions.AI.*")
                .AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation();
        });
        //...
}

With this setup, Aspire dashboards show detailed telemetry including conversation flows, model usage, performance metrics, and error tracking.

Ensure Quality: Evaluation and Testing

Trust in AI systems comes from rigorous evaluation. Microsoft Agent Framework can easily integrate with Microsoft.Extensions.AI.Evaluations to help you build reliable, trustworthy agent systems.

This enables:

• Automated testing – Run evaluation suites as part of your CI/CD pipeline
• Quality metrics – Measure relevance, coherence, and safety
• Regression detection – Catch quality degradation before deployment
• A/B testing – Compare different configurations

See how to get started with evaluations using Microsoft.Extensions.AI.Evaluations.

Start Building Agents Today

Microsoft Agent Framework transforms agent development from a complex, specialized skill into something every .NET developer can master. Whether you’re building a chatbot or orchestrating multiple AI agents in complex workflows, Microsoft Agent Framework provides a clear path forward.

Key Takeaways

• Simple by Design: Get started with just a few lines of code. Create your first agent in minutes, not days.
• Scales with You: Start with a single agent, then easily add workflows, tools, hosting, and monitoring as your needs grow.
• Built on Proven Technology: Microsoft Agent Framework brings together the best from AutoGen and Semantic Kernel. It builds on Microsoft.Extensions.AI, a unified foundation for modern AI development, to deliver a robust and cohesive experience for .NET developers.
• Production Ready: Deploy using familiar .NET patterns with built-in observability, evaluation, and hosting capabilities.

What’s Next?

Ready to start building?

Run the Hello World agent sample.

Then, head over to the Microsoft Agent Framework documentation to continue learning.

The future of software development includes AI agents as first-class components in modern software development. Microsoft Agent Framework ensures that future is accessible to every .NET developer.