How to Build Your First AI Agent with Microsoft Agent Framework

Introduction

Welcome to this practical guide on creating an intelligent AI agent using the Microsoft Agent Framework. If you've followed our earlier discussions on Microsoft Extensions for AI (MEAI) and Microsoft.Extensions.VectorData, you already have a solid foundation. MEAI provides a unified way to communicate with large language models, while VectorData enables semantic search and retrieval-augmented generation (RAG). Now, it's time to move beyond simple question-answering and build an agent that can take actions, use tools, maintain context, and even collaborate with other agents. This step-by-step tutorial will walk you through setting up your first agent in .NET, from project creation to running a working example. By the end, you'll have a clear understanding of the agent lifecycle and how the framework simplifies orchestration.

What You Need

• .NET SDK 8.0 or later – The agent framework targets .NET and is compatible with recent versions.
• An Azure OpenAI resource – You'll need an endpoint and a deployment name (e.g., gpt-5.4-mini). Alternatively, you can use OpenAI directly, but this guide assumes Azure.
• Azure CLI installed and authenticated – Used for DefaultAzureCredential; you can also set API keys manually.
• Basic familiarity with C# and console applications – We'll keep it simple, but knowing how to create a .NET console app helps.
• Environment variables configured – AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT_NAME must be set before running the code.

Step-by-Step Instructions

Step 1: Create a New Console Application

Open your terminal or command prompt and run the following command to scaffold a new .NET console project:

dotnet new console -n MyFirstAgent
cd MyFirstAgent

This creates a directory with a Program.cs file where you'll write your agent code.

Step 2: Install the Microsoft Agent Framework NuGet Package

Add the agent framework package to your project. The package name is Microsoft.Agents.AI and it includes all the core abstractions and the Azure OpenAI integration:

dotnet add package Microsoft.Agents.AI

This command pulls the latest stable version (the framework reached 1.0 in April 2026). If you plan to use other model providers, you may need additional packages, but for this guide, Azure OpenAI is sufficient.

Step 3: Set Environment Variables

Before running your agent, you must provide your Azure OpenAI endpoint and deployment name. The simplest way is to set environment variables. On Windows (Command Prompt):

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

On macOS/Linux (bash):

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

Replace the placeholder values with your actual resource details. The DefaultAzureCredential will try to authenticate using your Azure CLI login; if you prefer an API key, you can alter the code accordingly.

Step 4: Write the Agent Creation Code

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

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

Let's break down what's happening:

• AzureOpenAIClient is the standard Azure OpenAI SDK client, initialized with your endpoint and credentials.
• GetChatClient returns an IChatClient backed by the specified deployment. This is the same interface used by MEAI.
• .AsAIAgent() is an extension method that wraps the chat client into an AIAgent. You provide instructions – a system prompt that defines the agent's behavior – and a name for the agent.
• RunAsync sends a user message to the agent. The agent will process the input using its instructions, and return the response.

The key insight here is that the agent framework builds directly on top of IChatClient. If you've used MEAI, this pattern will feel familiar. The agent inherits all the capabilities of the underlying chat model but adds the ability to maintain state and use tools.

Step 5: Build and Run the Agent

Compile the project and execute it:

dotnet run

If everything is configured correctly, you should see a joke about pirates printed in the console. For example:

Why did the pirate go to the movie theater? Because he heard they had an 'Arrrr' rating system!

Congratulations, you've just built your first AI agent! While this example is simple, note that the agent already has autonomy: it doesn't just echo responses; it uses the provided instructions to generate contextually appropriate humor.

Tips for Success

• Start with clear instructions – The instructions parameter is your primary tool for shaping agent behavior. Be specific about the role, tone, and constraints.
• Leverage MEAI and VectorData – As mentioned in earlier parts of this series, combine the agent framework with MEAI for model abstraction and VectorData for knowledge retrieval. Your agent can call IChatClient internally or use vector search to fetch relevant information before responding.
• Understand the agent lifecycle – Agents maintain conversation context across RunAsync calls. By default, the framework stores the message history; you can configure or clear it as needed.
• Experiment with multi-agent scenarios – Once you're comfortable with a single agent, explore graph-based orchestration to coordinate multiple agents for complex tasks. The 1.0 release includes robust support for such patterns.
• Secure your credentials – Avoid hardcoding API keys or endpoints. Use environment variables, Azure Key Vault, or managed identities.
• Stay updated – The Microsoft Agent Framework is evolving rapidly. Check the official documentation for new features like built-in tool integration and streaming responses.

This guide provided a minimal but practical starting point. In future articles, we'll dive into adding custom tools, handling multi-turn conversations, and orchestrating agent teams. Happy building!