Skip to main content

​
Prerequisites

Before installing the Microsoft Agent Framework .NET SDK, ensure you have:
  • .NET 8.0 or later installed on your machine
  • An Azure OpenAI resource or other supported AI provider
  • Azure CLI (for authentication)

​
Install the SDK

The Microsoft Agent Framework is distributed as NuGet packages. Install the core package using the .NET CLI: 
dotnet add package Microsoft.Agents.AI

​
Additional Packages

Depending on your provider and features, you may need additional packages: 
dotnet add package Microsoft.Agents.AI.OpenAI
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity

​
Set Up Authentication

​
Azure Authentication

The SDK uses DefaultAzureCredential from Azure.Identity for authentication. This supports multiple authentication methods:
1

Install Azure CLI

Download and install the Azure CLI.
2

Sign in to Azure

az login
This will open a browser window for authentication.
3

Set your Azure subscription (if needed)

az account set --subscription "YOUR_SUBSCRIPTION_ID"
DefaultAzureCredential is convenient for development but requires careful consideration in production. Consider using ManagedIdentityCredential or other specific credentials in production environments.

​
Configure Environment Variables

Set up the required environment variables for your Azure OpenAI resource: 
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"

​
Environment Variable Reference

VariableDescriptionRequired
AZURE_OPENAI_ENDPOINTYour Azure OpenAI endpoint URLYes
AZURE_OPENAI_DEPLOYMENT_NAMEModel deployment name (e.g., gpt-4o-mini, gpt-4)No (defaults to gpt-4o-mini)

​
Create a New Project

Create a new .NET console application to start building agents:
1

Create a new project

dotnet new console -n MyFirstAgent
cd MyFirstAgent
2

Install the required packages

dotnet add package Microsoft.Agents.AI
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.AI.OpenAI
3

Verify the installation

dotnet build
You should see a successful build output.

​
Verify Your Setup

Create a simple test to verify your installation:
Program.cs
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using OpenAI.Chat;

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-4o-mini";

AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(instructions: "You are a helpful assistant.", name: "TestAgent");

Console.WriteLine(await agent.RunAsync("Hello! Are you working?"));
Run the application: 
dotnet run
If everything is configured correctly, you should see a response from your agent.

​
Troubleshooting

Error: Azure.Identity.AuthenticationFailedExceptionSolution: Ensure you’re logged in with az login and have the correct permissions for your Azure OpenAI resource.
Error: AZURE_OPENAI_ENDPOINT is not setSolution: Set the required environment variables as shown in the Configure Environment Variables section.
Error: Package dependency conflictsSolution: Ensure you’re using compatible versions. The SDK requires .NET 8.0 or later and Microsoft.Extensions.AI 10.3.0 or later.
Error: The API deployment for this resource does not existSolution: Verify your AZURE_OPENAI_DEPLOYMENT_NAME matches a deployment in your Azure OpenAI resource.
Never commit API keys or secrets to source control. Always use environment variables or Azure Key Vault for sensitive configuration.

​
Next Steps

Now that you have the SDK installed and configured:

Quickstart

Learn the core concepts and build your first agent

Create Your First Agent

Build a complete agent with tools and streaming

Build docs developers (and LLMs) love

Get started for freeTalk to us