Building an AI Agent with Microsoft Agent Framework: A Step-by-Step Guide

Introduction

Welcome to this guide on creating your first AI agent using the Microsoft Agent Framework. If you've followed along with earlier parts of this series, you already know how to use Microsoft Extensions for AI (MEAI) to communicate with large language models and Microsoft.Extensions.VectorData for semantic search and RAG (Retrieval-Augmented Generation). Now, it's time to give your AI the ability to do things—not just answer questions, but reason, use tools, remember context, and coordinate with other agents. That's the power of the Agent Framework.

Unlike a simple chatbot that merely passes input to a model and returns output, an agent has autonomy. It can decide which tools to call, evaluate results, and choose the next action—all without you writing explicit step-by-step instructions. The Microsoft Agent Framework, which reached its 1.0 release in April 2026, provides a production-ready SDK for building intelligent agents in .NET (and Python, though this guide focuses on C#). This guide walks you through setting up your first agent in just a few steps.

What You Need

• .NET SDK (version 8.0 or later)
• Azure OpenAI subscription or an OpenAI API key (if using a different model)
• An environment variable named AZURE_OPENAI_ENDPOINT set to your Azure OpenAI endpoint
• An environment variable named AZURE_OPENAI_DEPLOYMENT_NAME set to your deployment name (e.g., gpt-5.4-mini)
• Optional: DefaultAzureCredential requires Azure CLI or managed identity setup; alternatively, you can use an API key

Step-by-Step Instructions

Step 1: Create a New Console Application

Open your terminal or command prompt and run:

dotnet new console -n MyFirstAgent
cd MyFirstAgent

This creates a new .NET console project in a folder named MyFirstAgent.

Step 2: Install the Microsoft Agent Framework Package

Add the necessary NuGet package by running:

dotnet add package Microsoft.Agents.AI

This installs the core SDK for building agents. The Agent Framework builds directly on top of IChatClient from MEAI, so you'll also get the required dependencies automatically.

Step 3: Set Up Environment Variables

You need to configure your Azure OpenAI endpoint and deployment name. Set the environment variables in your terminal (or in your IDE settings):

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

On Windows, use setx or set them in your project's launch settings. Alternatively, you can hardcode them for testing, but using environment variables is more secure.

Step 4: Write the Agent Code

Open Program.cs and replace its contents with the following code. This creates an agent that tells jokes:

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

Explanation: The .AsAIAgent() extension method bridges any IChatClient (here from Azure OpenAI) to the Agent Framework, turning a simple chat client into an agent with given instructions and a name. The RunAsync method processes the user input and returns the agent's response.

Step 5: Run the Agent

Execute the application:

dotnet run

You should see a joke output, such as: "Why don't pirates shower before they walk the plank? Because they'll just wash up on shore later!" (depending on the model's creativity).

Step 6: Experiment with Different Instructions

Change the instructions parameter to see how the agent's behavior changes. For example:

.AsAIAgent(
    instructions: "You are a helpful travel assistant. Suggest destinations based on user preferences.",
    name: "TravelAgent")

Then call RunAsync("I want a beach vacation with good food."). The agent will now respond as a travel expert.

Tips for Success

• Start Simple: Before adding tools or multi-agent workflows, get comfortable with the basic agent pattern. It's the foundation for everything else.
• Use Descriptive Instructions: The instructions parameter acts as the system prompt. Be specific about the agent's role and capabilities to get reliable behavior.
• Handle Errors Gracefully: Always check that environment variables are set, as shown in the code, to avoid runtime crashes.
• Explore More: The Agent Framework supports adding custom tools (via tool binding), state management, and graph-based orchestration for multi-agent scenarios. Check the official documentation for advanced patterns.
• Testing with API Key: If you don't have Azure credentials set up, you can use new AzureOpenAIClient(new Uri(endpoint), new Azure.AzureKeyCredential(apiKey)) instead of DefaultAzureCredential.
• Keep Security in Mind: Never hardcode API keys or endpoints in your code. Use environment variables, Azure Key Vault, or user secrets.

Now you have a working AI agent. The next steps are to give it tools (like calculators or database queries) and connect multiple agents together. But this simple example is the perfect starting point. Happy building!