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

<h2>Introduction</h2> <p>Welcome! This guide walks you through creating your first AI agent using the <strong>Microsoft Agent Framework</strong> 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.</p><figure style="margin:20px 0"><img src="https://devblogs.microsoft.com/dotnet/wp-content/uploads/sites/10/2026/05/agent-framework.webp" alt="How to Build Your First AI Agent in .NET with Microsoft Agent Framework" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: devblogs.microsoft.com</figcaption></figure> <h2>What You Need</h2> <ul> <li><strong>.NET 8 SDK</strong> or later (download from <a href="https://dotnet.microsoft.com/download">dotnet.microsoft.com</a>)</li> <li><strong>An Azure OpenAI resource</strong> with a deployed model (e.g., <em>gpt-5.4-mini</em>)</li> <li>The <strong>Azure OpenAI endpoint URL</strong> and <strong>deployment name</strong></li> <li>An <strong>Azure identity</strong> configured with access to the OpenAI resource (use <code>DefaultAzureCredential</code>)</li> <li>A text editor or IDE (Visual Studio, VS Code, or JetBrains Rider)</li> </ul> <h2>Step 1: Create a New Console Project</h2> <p>Open your terminal and run the following command to create a console application:</p> <pre><code>dotnet new console -n HelloAgent cd HelloAgent</code></pre> <h2>Step 2: Install the Microsoft Agents NuGet Package</h2> <p>Add the <code>Microsoft.Agents.AI</code> package to your project:</p> <pre><code>dotnet add package Microsoft.Agents.AI</code></pre> <p>This package provides the core <code>AIAgent</code> type and extension methods for building agents on top of <code>IChatClient</code>.</p> <h2>Step 3: Set Up Environment Variables</h2> <p>Your agent needs credentials to connect to Azure OpenAI. Set these environment variables in your terminal or system settings:</p> <pre><code>set AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/ set AZURE_OPENAI_DEPLOYMENT_NAME=gpt-5.4-mini</code></pre> <p>If you're using a different model name, replace <em>gpt-5.4-mini</em> accordingly.</p> <h2>Step 4: Write the Agent Code</h2> <p>Open <code>Program.cs</code> and replace its content with the following:</p> <pre><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."));</code></pre> <p>This code:</p> <ul> <li>Reads the endpoint and deployment name from environment variables.</li> <li>Creates an <code>AzureOpenAIClient</code> with <code>DefaultAzureCredential</code>.</li> <li>Gets a chat client for your model.</li> <li>Converts it into an agent using the <code>.AsAIAgent()</code> extension method, providing instructions and a name.</li> <li>Calls <code>agent.RunAsync()</code> with a prompt to get a response.</li> </ul> <h2>Step 5: Run Your Agent</h2> <p>Execute the console app:</p><figure style="margin:20px 0"><img src="https://uhf.microsoft.com/images/microsoft/RE1Mu3b.png" alt="How to Build Your First AI Agent in .NET with Microsoft Agent Framework" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: devblogs.microsoft.com</figcaption></figure> <pre><code>dotnet run</code></pre> <p>If everything is configured correctly, you'll see a pirate joke printed in the console. The agent understood its role and responded accordingly.</p> <h2>Step 6: Experiment and Extend</h2> <p>Now that you have a working agent, try modifying the <em>instructions</em> or the prompt. For example:</p> <pre><code>.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?"));</code></pre> <p>The Agent Framework also supports <strong>tool calling</strong> and <strong>multi-agent orchestration</strong> – see the <a href="#tips">Tips section</a> for next steps.</p> <h2 id="tips">Tips for Success</h2> <ul> <li><strong>Authentication:</strong> If <code>DefaultAzureCredential</code> doesn't work in your environment (e.g., local development), use <code>AzureCliCredential</code> or <code>EnvironmentCredential</code> instead.</li> <li><strong>Model Choice:</strong> Smaller models like <em>gpt-5.4-mini</em> are fast and cheap for simple tasks. For complex reasoning, try larger models.</li> <li><strong>Instructions Matter:</strong> The <code>instructions</code> parameter sets the agent's system prompt. Be specific and clear to get better results.</li> <li><strong>Error Handling:</strong> Wrap the agent call in a try-catch to handle exceptions like rate limits or token issues.</li> <li><strong>Next Steps:</strong> To add tools (e.g., weather API, database lookup), refer to the <a href="https://learn.microsoft.com/en-us/dotnet/ai/agent-framework">official Microsoft documentation</a>.</li> </ul>