Build Your First Autonomous AI Agent with .NET: A Step-by-Step Guide

Introduction

Welcome to the hands-on guide for creating your first AI agent using the Microsoft Agent Framework. If you've already explored Microsoft Extensions for AI (MEAI) and the VectorData library, you're ready to take the next leap: building an agent that doesn't just answer questions but acts on your behalf. Released as a production-ready 1.0 in April 2026, the Microsoft Agent Framework lets you create intelligent agents in C# (and Python) that can reason, use tools, remember context, and even collaborate with other agents—all without writing rigid, step-by-step code.

In this guide, you'll create a simple joke-telling agent called "Joker." You'll learn the core patterns and see how the framework builds directly on the familiar IChatClient abstraction from MEAI.

What You Need

• .NET SDK (version 8.0 or later)
• An Azure OpenAI resource (with a deployed model, e.g., gpt-5.4-mini)
• Environment variables configured with your endpoint URL and deployment name
• A code editor (Visual Studio, VS Code, or the dotnet CLI)
• Basic familiarity with C# and the console

Step-by-Step Instructions

Step 1: Create a New Console Application

Open your terminal and run the following command to scaffold a new console app:

dotnet new console -n MyFirstAgent
cd MyFirstAgent

This creates a simple project with a Program.cs file.

Step 2: Install the Microsoft Agent Framework Package

The agent framework lives in the Microsoft.Agents.AI NuGet package. Install it with:

dotnet add package Microsoft.Agents.AI

This also pulls in the necessary MEAI dependencies because the agent framework uses IChatClient under the hood.

Step 3: Set Up Environment Variables

You'll need two values from your Azure OpenAI resource:

• AZURE_OPENAI_ENDPOINT – The full endpoint URL (e.g., https://your-resource.openai.azure.com/)
• AZURE_OPENAI_DEPLOYMENT_NAME – The name of the model deployment (e.g., gpt-5.4-mini)

Set these in your terminal (or IDE) so the application can read them at runtime. For example, in bash:

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

In Windows Command Prompt:

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

Step 4: Write the Agent Code

Replace the contents of Program.cs 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."));

What’s happening here?

• Authentication: DefaultAzureCredential automatically handles authentication (if you're logged into Azure CLI, it will use your credentials).
• Creating the underlying chat client: GetChatClient(deploymentName) returns an AzureOpenAIChatClient that implements IChatClient.
• Conversion to an agent: The .AsAIAgent() extension method wraps the chat client into an AIAgent instance. You provide instructions (system prompt) and a name for the agent.
• Running the agent: agent.RunAsync(userInput) processes the input using the model and the agent's instructions. The agent manages the conversation internally, but here we send a single message and print the response.

Notice that the agent doesn't require any explicit tool definitions yet—this is the simplest possible agent, a pure conversational one.

Step 5: Run Your Agent

Back in the terminal, execute:

dotnet run

If everything is configured correctly, you'll see a joke printed to the console. For example:

Why are pirates called pirates? Because they just arrr!

Congratulations—you've just deployed your first autonomous AI agent! While it behaves like a simple chatbot in this example, the same pattern can be extended to give the agent tools, memory, and multi-step reasoning.

Tips & Next Steps

• Experiment with instructions: Change the instructions parameter to see how the agent's personality and behavior shift. Try "You are a helpful assistant who speaks like Shakespeare."
• Add tools: The agent framework supports tool calling. Install Microsoft.Agents.AI.Tools and register functions to let the agent perform actions like looking up weather or running calculations.
• Explore the graph-based orchestration: For multi-agent scenarios, the framework offers a graph-based model where agents can message each other and coordinate workflows. Check back for the next guide in this series!
• Secure your credentials: In production, never hardcode connection strings or store secrets in environment variables that are committed to source control. Use Azure Key Vault or a secrets manager.
• Understand the architecture: The agent framework builds on MEAI's IChatClient, which means you can swap out the underlying model provider (e.g., from Azure OpenAI to a local Ollama model) by changing the client implementation – no code changes needed.

For the complete code sample and additional resources, see the official Microsoft Agent Framework documentation.