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.