Skip to main content

Overview

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

System Requirements

  • 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

1

Install the core package

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

Install optional provider packages (optional)

Install additional packages for specific providers:
3

Install all extensions (optional)

To install all available extensions:
4

Verify installation

Authentication setup

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

Install Azure CLI

Download and install from Azure CLI documentation:
2

Login to Azure

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

Verify authentication

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:
Get your project endpoint from ai.azure.com → Your Project → Overview → Project connection string

Optional environment variables

Using .env files

For convenience, create a .env file in your project root:
Create .env:
Load in your code:
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:
Run the test:

Troubleshooting

Error: DefaultAzureCredential failed to retrieve a tokenSolution:
  1. Ensure you’ve run az login and authenticated successfully
  2. Check that your Azure account has access to the resources
  3. Verify your subscription is active: az account show
  4. Try clearing cached credentials: az account clear then az login again
Error: ModuleNotFoundError: No module named 'agent_framework'Solution:
  1. Verify installation: pip show agent-framework-core
  2. Check you’re using the correct Python environment
  3. Reinstall: pip install --force-reinstall agent-framework --pre
Error: Package 'Microsoft.Agents.AI.OpenAI' could not be foundSolution:
  1. Ensure you have access to the NuGet package source
  2. Clear NuGet cache: dotnet nuget locals all --clear
  3. Restore packages: dotnet restore
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
Error: Request timeout when calling Azure servicesSolution:
  1. Check your network connection and firewall settings
  2. Verify the endpoint URL is correct
  3. Ensure the Azure resource is running and accessible
  4. 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.