Installation

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

dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Extensions.AI.OpenAI

# Anthropic
dotnet add package Anthropic

# Google Gemini
dotnet add package Google.GenAI

# Ollama
dotnet add package OllamaSharp

Set Up Authentication

Azure Authentication

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

Install Azure CLI

Download and install the Azure CLI.

az login

This will open a browser window for authentication.

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"

$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"

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

Environment Variable Reference

Variable	Description	Required
`AZURE_OPENAI_ENDPOINT`	Your Azure OpenAI endpoint URL	Yes
`AZURE_OPENAI_DEPLOYMENT_NAME`	Model 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:

Create a new project

dotnet new console -n MyFirstAgent
cd MyFirstAgent

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

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

Authentication errors

Error: Azure.Identity.AuthenticationFailedExceptionSolution: Ensure you’re logged in with az login and have the correct permissions for your Azure OpenAI resource.

Missing environment variables

Error: AZURE_OPENAI_ENDPOINT is not setSolution: Set the required environment variables as shown in the Configure Environment Variables section.

Package version conflicts

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.

Deployment not found

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

Getting Started

Guides

API Reference

Prerequisites

Install the SDK

Additional Packages

Set Up Authentication

Azure Authentication

Configure Environment Variables

Environment Variable Reference

Create a New Project

Verify Your Setup

Troubleshooting

Next Steps

Quickstart

Create Your First Agent

​Prerequisites

​Install the SDK

​Additional Packages

​Set Up Authentication

​Azure Authentication

​Configure Environment Variables

​Environment Variable Reference

​Create a New Project

​Verify Your Setup

​Troubleshooting

​Next Steps

Quickstart

Create Your First Agent

Prerequisites

Install the SDK

Additional Packages

Set Up Authentication

Azure Authentication

Configure Environment Variables

Environment Variable Reference

Create a New Project

Verify Your Setup

Troubleshooting

Next Steps