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

Introduction

Welcome! This guide walks you through creating your first AI agent using the Microsoft Agent Framework for .NET. Unlike a simple chatbot, an AI agent can reason, use tools, and take actions to accomplish tasks autonomously. In this step-by-step tutorial, you'll build a lightweight agent called "Joker" that tells jokes. By the end, you'll understand the core concepts and be ready to explore more complex scenarios.

What You Need

• .NET 8 SDK or later (download from dotnet.microsoft.com)
• An Azure OpenAI resource with a deployed model (e.g., gpt-5.4-mini)
• The Azure OpenAI endpoint URL and deployment name
• An Azure identity configured with access to the OpenAI resource (use DefaultAzureCredential)
• A text editor or IDE (Visual Studio, VS Code, or JetBrains Rider)

Step 1: Create a New Console Project

Open your terminal and run the following command to create a console application:

dotnet new console -n HelloAgent
cd HelloAgent

Step 2: Install the Microsoft Agents NuGet Package

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

dotnet add package Microsoft.Agents.AI

This package provides the core AIAgent type and extension methods for building agents on top of IChatClient.

Step 3: Set Up Environment Variables

Your agent needs credentials to connect to Azure OpenAI. Set these environment variables in your terminal or system settings:

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

If you're using a different model name, replace gpt-5.4-mini accordingly.

Step 4: Write the Agent Code

Open Program.cs and replace its content 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."));

This code:

• Reads the endpoint and deployment name from environment variables.
• Creates an AzureOpenAIClient with DefaultAzureCredential.
• Gets a chat client for your model.
• Converts it into an agent using the .AsAIAgent() extension method, providing instructions and a name.
• Calls agent.RunAsync() with a prompt to get a response.

Step 5: Run Your Agent

Execute the console app:

dotnet run

If everything is configured correctly, you'll see a pirate joke printed in the console. The agent understood its role and responded accordingly.

Step 6: Experiment and Extend

Now that you have a working agent, try modifying the instructions or the prompt. For example:

.AsAIAgent(
    instructions: "You are a helpful assistant that always responds in rhyme.",
    name: "Poet");

Console.WriteLine(await agent.RunAsync("What is the capital of France?"));

The Agent Framework also supports tool calling and multi-agent orchestration – see the Tips section for next steps.

Tips for Success

• Authentication: If DefaultAzureCredential doesn't work in your environment (e.g., local development), use AzureCliCredential or EnvironmentCredential instead.
• Model Choice: Smaller models like gpt-5.4-mini are fast and cheap for simple tasks. For complex reasoning, try larger models.
• Instructions Matter: The instructions parameter sets the agent's system prompt. Be specific and clear to get better results.
• Error Handling: Wrap the agent call in a try-catch to handle exceptions like rate limits or token issues.
• Next Steps: To add tools (e.g., weather API, database lookup), refer to the official Microsoft documentation.