Installation

Overview

Microsoft Agent Framework is available for both Python and .NET. This guide covers installation, authentication setup, and environment configuration.

System Requirements

Python
.NET

Python version: 3.10 or higher (supports 3.10, 3.11, 3.12, 3.13, 3.14)
Package manager: pip or uv
Operating systems: Windows, macOS, Linux

Install the framework

Python
.NET

Install the core package

pip install agent-framework --pre

The --pre flag is required during the preview period.

Install optional provider packages (optional)

Install additional packages for specific providers:

# Azure AI integrations
pip install agent-framework-azure-ai --pre
pip install agent-framework-azure-ai-search --pre

# Other LLM providers
pip install agent-framework-anthropic --pre
pip install agent-framework-ollama --pre
pip install agent-framework-bedrock --pre

# Hosting and protocols
pip install agent-framework-azurefunctions --pre
pip install agent-framework-a2a --pre

# Memory and storage
pip install agent-framework-mem0 --pre
pip install agent-framework-redis --pre

# UI and development tools
pip install agent-framework-devui --pre
pip install agent-framework-chatkit --pre

Install all extensions (optional)

To install all available extensions:

pip install agent-framework[all] --pre

Verify installation

python -c "import agent_framework; print(agent_framework.__version__)"

Create a new project

dotnet new console -n MyAgentProject
cd MyAgentProject

Install core packages

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

Install optional packages

Add additional packages based on your needs:

# For Azure AI Foundry agents
dotnet add package Microsoft.Agents.AI.AzureAI

# For Anthropic
dotnet add package Microsoft.Agents.AI.Anthropic

# For hosting with Azure Functions
dotnet add package Microsoft.Agents.AI.AzureFunctions

# For Agent-to-Agent protocol
dotnet add package Microsoft.Agents.AI.A2A

# For memory providers
dotnet add package Microsoft.Agents.AI.Mem0

Verify installation

Add this to your Program.cs:

using Microsoft.Agents.AI;

Console.WriteLine("Agent Framework installed successfully!");

Then run:

dotnet run

Authentication setup

Microsoft Agent Framework uses Azure CLI credentials for authentication in development.

Install Azure CLI

Download and install from Azure CLI documentation:

Windows
macOS
Linux

winget install -e --id Microsoft.AzureCLI

brew update && brew install azure-cli

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

az login

This opens a browser window for authentication. After login, your credentials are cached locally.

Verify authentication

az account show

This displays your current Azure subscription details.

Production deployments: Use managed identities or service principals instead of Azure CLI credentials. See Azure authentication best practices.

Environment configuration

Required environment variables

Set these environment variables based on your provider:

Azure AI Foundry (Python)
Azure OpenAI (.NET)
OpenAI (Python)

# Azure AI Foundry project endpoint
export AZURE_AI_PROJECT_ENDPOINT="https://your-project-endpoint"

# Model deployment name (for Responses API)
export AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME="gpt-4o"

# Alternative: for Chat API
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o"

Get your project endpoint from ai.azure.com → Your Project → Overview → Project connection string

# Azure OpenAI endpoint
export AZURE_OPENAI_ENDPOINT="https://your-openai-resource.openai.azure.com"

# Model deployment name
export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"

Get your endpoint from Azure Portal → Your OpenAI Resource → Keys and Endpoint

# OpenAI API key
export OPENAI_API_KEY="sk-..."

# Model ID
export OPENAI_CHAT_MODEL_ID="gpt-4o"
export OPENAI_RESPONSES_MODEL_ID="gpt-4o"

Optional environment variables

Azure AI Search (RAG)

export AZURE_SEARCH_ENDPOINT="https://your-search-service.search.windows.net"
export AZURE_SEARCH_API_KEY="your-api-key"
export AZURE_SEARCH_INDEX_NAME="your-index-name"
export AZURE_SEARCH_SEMANTIC_CONFIG="your-semantic-config"

Anthropic Claude

export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_MODEL="claude-3-5-sonnet-20241022"

Ollama (Local Models)

export OLLAMA_ENDPOINT="http://localhost:11434"
export OLLAMA_MODEL="llama2"

Observability (OpenTelemetry)

export ENABLE_INSTRUMENTATION=true
export ENABLE_SENSITIVE_DATA=true
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317/"

Mem0 (Memory)

export MEM0_API_KEY="your-mem0-api-key"

Using .env files

For convenience, create a .env file in your project root:

Python
.NET

Create .env:

# Azure AI
AZURE_AI_PROJECT_ENDPOINT="https://your-project-endpoint"
AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME="gpt-4o"

# Optional: Azure AI Search
AZURE_SEARCH_ENDPOINT=""
AZURE_SEARCH_API_KEY=""
AZURE_SEARCH_INDEX_NAME=""

Load in your code:

from dotenv import load_dotenv

load_dotenv()  # Loads variables from .env

Create .env (or use appsettings.json):

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

Add the DotNetEnv package:

dotnet add package DotNetEnv

Load in your code:

DotNetEnv.Env.Load();

Never commit .env files with secrets to version control. Add .env to your .gitignore file.

Verify your installation

Test your setup with a minimal example:

# test_install.py
import asyncio
import os
from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity import AzureCliCredential
from dotenv import load_dotenv

load_dotenv()

async def test():
    credential = AzureCliCredential()
    client = AzureOpenAIResponsesClient(
        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
        deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"],
        credential=credential,
    )
    
    agent = client.as_agent(
        name="TestAgent",
        instructions="You are a helpful assistant.",
    )
    
    result = await agent.run("Say hello!")
    print(f"✓ Agent Framework is working! Response: {result}")

if __name__ == "__main__":
    asyncio.run(test())

Run the test:

Python
.NET

python test_install.py

dotnet run

Troubleshooting

Authentication errors

Error: DefaultAzureCredential failed to retrieve a tokenSolution:

Ensure you’ve run az login and authenticated successfully
Check that your Azure account has access to the resources
Verify your subscription is active: az account show
Try clearing cached credentials: az account clear then az login again

Module not found errors (Python)

Error: ModuleNotFoundError: No module named 'agent_framework'Solution:

Verify installation: pip show agent-framework-core
Check you’re using the correct Python environment
Reinstall: pip install --force-reinstall agent-framework --pre

Package not found errors (.NET)

Error: Package 'Microsoft.Agents.AI.OpenAI' could not be foundSolution:

Ensure you have access to the NuGet package source
Clear NuGet cache: dotnet nuget locals all --clear
Restore packages: dotnet restore

Environment variables not loading

Error: Variables in .env not being readSolution:Python:

Ensure python-dotenv is installed: pip install python-dotenv
Add load_dotenv() before accessing environment variables
Check .env file is in the same directory as your script

NET:

Install DotNetEnv: dotnet add package DotNetEnv
Call DotNetEnv.Env.Load() at the start of your program

Connection timeout errors

Error: Request timeout when calling Azure servicesSolution:

Check your network connection and firewall settings
Verify the endpoint URL is correct
Ensure the Azure resource is running and accessible
Check Azure service health: Azure Status

Next steps

Quickstart Guide

Build your first agent in 5 minutes

Core Concepts

Understand agents, tools, and sessions

Provider Configuration

Configure different LLM providers

Sample Code

Explore example projects

For additional help, visit the GitHub repository or join our Discord community.

Get Started

Core Concepts

Workflows

Providers

Hosting & Deployment

Migration Guides

Overview

System Requirements

Install the framework

Authentication setup

Environment configuration

Required environment variables

Optional environment variables

Using .env files

Verify your installation

Troubleshooting

Next steps

Quickstart Guide

Core Concepts

Provider Configuration

Sample Code

Build docs developers (and LLMs) love

Get Started

Core Concepts

Workflows

Providers

Hosting & Deployment

Migration Guides

​Overview

​System Requirements

​Install the framework

​Authentication setup

​Environment configuration

​Required environment variables

​Optional environment variables

​Using .env files

​Verify your installation

​Troubleshooting

​Next steps

Quickstart Guide

Core Concepts

Provider Configuration

Sample Code

Build docs developers (and LLMs) love

Overview

System Requirements

Install the framework

Authentication setup

Environment configuration

Required environment variables

Optional environment variables

Using .env files

Verify your installation

Troubleshooting

Next steps