How to Create Your First AI Agent with the Microsoft Agent Framework in .NET

Introduction

Welcome to the third installment of our series on AI building blocks for .NET. In earlier parts, we explored Microsoft Extensions for AI (MEAI) for unified LLM interaction and VectorData for semantic search and RAG. Now, we dive into the Microsoft Agent Framework—a production-ready SDK for building intelligent agents that can reason, use tools, and coordinate with other agents.

Unlike simple chatbots that merely respond to prompts, an agent is autonomous. It can break down tasks, decide which tools to invoke, evaluate outcomes, and adapt its approach. This guide will walk you through creating your first agent in C#, from setup to execution.

What You Need

• .NET 9 SDK or later (or .NET 8 with C# 12 support)
• An Azure OpenAI resource with a deployed model (e.g., gpt-4o-mini or gpt-5.4-mini) – note the endpoint and deployment name
• Azure Identity credentials (e.g., using DefaultAzureCredential, which works with Azure CLI, Visual Studio, or managed identity)
• A text editor or IDE (Visual Studio, VS Code, JetBrains Rider)
• Access to the NuGet package Microsoft.Agents.AI (version 1.0.0 or later)

Step-by-Step Guide

Step 1: Prepare Your Development Environment

Open a terminal and create a new console application:

dotnet new console -n MyFirstAgent
cd MyFirstAgent

Set your Azure OpenAI endpoint and deployment name as environment variables. This keeps sensitive data out of code:

set AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
set AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o-mini

Replace your-resource with your actual resource name. On macOS/Linux, use export instead of set.

Step 2: Install the Agent Framework NuGet Package

Run the following command to add the Microsoft.Agents.AI package to your project:

dotnet add package Microsoft.Agents.AI

This package depends on MEAI and will automatically pull in Microsoft.Extensions.AI and related libraries.

Step 3: Write the Agent Code

Open Program.cs and replace its contents with the code below. This creates a simple joke-telling agent using Azure OpenAI:

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

// Retrieve configuration from environment variables
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-4o-mini";

// Create the AI agent using the extension method
AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You are good at telling jokes.",
        name: "Joker");

// Run the agent with a user prompt
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Key points:

• AzureOpenAIClient and DefaultAzureCredential come from the Azure SDK for .NET.
• .AsAIAgent() is an extension method that wraps the chat client, adding agent capabilities like instructions and identity.
• The instructions parameter sets the agent’s system prompt – e.g., personality or behavior constraints.
• RunAsync() sends the user message and returns the agent’s response as a string.

Step 4: Run and Test the Agent

Build and run the application:

dotnet run

You should see a joke output like: Why do pirates never make good comedians? Because they always drop the punchline!

If you encounter authentication errors, ensure your Azure CLI login is current (az login) or set the environment variable AZURE_CLIENT_ID etc. for a service principal.

Step 5: Expand with Tools and Multi-Agent Workflows (Optional)

The real power of agents emerges when you equip them with tools. For example, you can define a function for searching a database or calling an API, and register it with the agent using .AddTool(). For multi-agent orchestration, use the graph-based AgentCoordinator or AgentChain classes to define workflows. Refer to the official documentation for advanced patterns.

Tips for Success

• Craft clear instructions: The instructions parameter is your system prompt. Be explicit about the agent’s role, tone, and boundaries. For example, “You are a helpful assistant that answers in rhyming couplets.”
• Use descriptive names: The name parameter is used in conversation history and logging. Pick something meaningful.
• Handle errors gracefully: Wrap the RunAsync call in a try-catch block to manage network issues or model throttling.
• Secure credentials: Never hardcode endpoint URLs or API keys. Use environment variables, user secrets, or managed identity.
• Experiment with models: The agent works with any model supporting the MEAI IChatClient. Try different deployments to compare cost and quality.
• Start simple, then iterate: Begin with a single agent and simple instructions before adding tools or collaboration.

This guide gives you the foundation to build autonomous AI agents in .NET. Next, you might explore how to add persistent memory with VectorData or orchestrate complex tasks across multiple agents. Happy coding!