How to Build Intelligent AI Agents in .NET with Microsoft Agent Framework

Introduction

Welcome to the third installment of our series on building AI foundations in .NET. In previous guides, you learned how to use Microsoft Extensions for AI (MEAI) to interact uniformly with large language models, and how Microsoft.Extensions.VectorData enables semantic search and Retrieval-Augmented Generation (RAG) patterns. Now it’s time to move beyond simple question-answering to create agents that take action, use tools, and coordinate with other agents to solve complex problems.

An AI agent is not just a chatbot. A chatbot receives input, passes it to a model, and returns output. An agent, however, has autonomy: it reasons about a task, selects appropriate tools, calls them, evaluates results, and decides what to do next—all without requiring you to script every step. Think of it as handing a colleague a to-do list and letting them figure out how to get it done.

The Microsoft Agent Framework is a production-ready SDK for building these intelligent agents in .NET (and other languages). It reached its 1.0 release in April 2026 and supports everything from simple single‑agent scenarios to complex multi‑agent workflows with graph-based orchestration. This how‑to guide will walk you through creating your first agent using C#.

What You Need

• .NET SDK (version 8.0 or later) installed on your development machine.
• An Azure OpenAI service with a deployed model (e.g., gpt‑5.4‑mini). You’ll need the endpoint URL and deployment name.
• Azure credentials (set up via az login or environment variables) so your application can authenticate.
• A code editor or IDE (Visual Studio, VS Code, JetBrains Rider).
• Basic familiarity with C# and console applications.

Step‑by‑Step Guide

Step 1: Understand the Role of Agents

Before coding, grasp what an agent is in this context. The Agent Framework builds on top of IChatClient (from MEAI). It adds agent-specific capabilities: system instructions, tool calling, memory, and multi‑agent orchestration. For your first agent, you’ll keep it simple: an agent that follows a specific instruction (e.g., telling jokes) and responds to a user prompt.

Step 2: Set Up Your .NET Project

Create a new console application. Open your terminal and run:

dotnet new console -n MyFirstAgent
cd MyFirstAgent

Open the project in your editor. Make sure you have the necessary environment variables. You can set them in your terminal or use a .env file (with a library like dotenv.net). We’ll read them directly from environment variables for simplicity.

Step 3: Install the Agent Framework Package

Add the Microsoft.Agents.AI NuGet package to your project:

dotnet add package Microsoft.Agents.AI

This package includes the core agent abstractions and the AzureOpenAIClient support. If you target a different model provider, you might need additional packages, but for Azure OpenAI this is sufficient.

Step 4: Create Your First Agent

Replace the contents of Program.cs with the following code. It creates an agent named “Joker” that is instructed to be good at telling jokes. The agent uses your Azure OpenAI endpoint and deployment to generate responses.

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

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
    ?? "gpt-5.4-mini";

AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You are good at telling jokes.",
        name: "Joker");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Key points:

• AsAIAgent() is an extension method that wraps your chat client into an agent. It requires at least an instructions string (system prompt) and a name.
• The agent’s RunAsync method takes a user input and returns the agent’s response.
• Authentication uses DefaultAzureCredential, which works with your local Azure CLI login, managed identity, or environment variables.

Step 5: Run Your Agent

Before running, ensure you have set the required environment variables. In your terminal:

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"

On Windows use set instead of export. Then run:

dotnet run

You should see a joke printed to the console. Experiment by changing the instruction or the prompt.

Tips for Success

• Start small. Master single-agent scenarios before attempting multi‑agent coordination.
• Use clear instructions. The instructions parameter acts as a system prompt—the more precise, the better the agent’s behavior.
• Leverage tools. The Agent Framework allows you to register .NET methods as tools that the agent can call. This extends its capabilities beyond text responses.
• Handle errors gracefully. Always check for environment variables and catch exceptions from Azure service calls.
• Explore orchestration. After mastering basics, look into AgentGroupChat for multi‑agent workflows with turn‑taking and graph‑based routing.

You now have a working AI agent built with the Microsoft Agent Framework. This is just the beginning—combine it with MEAI and VectorData to build powerful, knowledge‑driven applications.