Introduction

Welcome back to the building blocks for AI in .NET series. So far, we've covered Microsoft Extensions for AI (MEAI) for unified LLM interaction and Microsoft.Extensions.VectorData for semantic search and RAG. Now, we reach the third pillar: the Microsoft Agent Framework. This production-ready SDK (1.0 released April 2026) lets you create AI agents that don't just chat—they reason, use tools, remember context, and coordinate with other agents. In this how-to guide, you'll build your first simple agent using C# and the Agent Framework.

What You Need

• .NET SDK (6.0 or later, 8.0+ recommended)
• Azure OpenAI service (with a deployed model like gpt-5.4-mini)
• Environment variables: AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT_NAME
• NuGet package: Microsoft.Agents.AI
• Basic familiarity with MEAI's IChatClient interface (see Part 1 of this series)
• A code editor (Visual Studio, VS Code, JetBrains Rider, etc.)

Step-by-Step Guide

Step 1: Create a New Console Application

Open your terminal and run:

dotnet new console -o MyFirstAgent
cd MyFirstAgent

Step 2: Install the Microsoft Agent Framework Package

Add the Microsoft.Agents.AI package:

dotnet add package Microsoft.Agents.AI

This package provides the AIAgent class and the essential AsAIAgent() extension method that wraps any IChatClient into an agent.

Step 3: Set Up Environment Variables

Set the two required variables in your system or in a .env file (if using a loader). For example, on Windows PowerShell:

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

On macOS/Linux:

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

Step 4: Write the Agent Code

Open Program.cs and replace its contents with the following:

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."));

Step 5: Understand the Code

• AzureOpenAIClient – connects to your Azure OpenAI resource using DefaultAzureCredential (supports local dev via Azure CLI, Visual Studio, or managed identity).
• GetChatClient – returns an IChatClient (the MEAI abstraction).
• AsAIAgent – the core extension method that transforms the chat client into an agent. It takes two parameters: instructions (system prompt) and name (agent identifier).
• RunAsync – sends a user input to the agent and returns the final response after the agent completes its reasoning.

Step 6: Run the Agent

In your terminal, execute:

dotnet run

You should see a joke printed to the console, for example: "Why did the pirate go to the movie? Because he heard it had a good arrr-ating!"

Step 7: (Optional) Experiment with Different Instructions and Inputs

Change the instructions to something like "You are a helpful assistant that answers in rhymes." or the user input to a complex question. The agent framework automatically handles multi-turn conversation history; each RunAsync call maintains context as long as you reuse the same agent instance.

Tips and Conclusion

• Start simple. Use the AsAIAgent pattern exactly as shown—it's the easiest way to get an agent working.
• Leverage MEAI knowledge. Since the Agent Framework builds on IChatClient, all your MEAI skills (logging, retries, streaming) transfer directly.
• Remember the prerequisites. Ensure your Azure OpenAI deployment is listed in the environment variables and that you have proper credentials.
• Scale later. This single-agent example is the foundation for multi-agent workflows with graph-based orchestration (coming in a future guide).
• Check the documentation. The Agent Framework supports tool calling, memory, and agentic RAG—all topics for deeper dives.

You've now built your first AI agent. Unlike a simple chatbot, this agent can decide how to accomplish a task within its instructions. In the next part of the series, we'll add tools and show how agents can interact with external systems autonomously.