Guide · Open source
How to use agent-framework: install, run a first agent and tips
Updated · written with AI from the project's own documentation and checked against our catalogue data
Microsoft Agent Framework (MAF) is an open, multi-language framework for building AI agents and multi-agent workflows in Python and .NET. It is aimed at developers who plan to take agents from prototype to production. After this guide you will know how to install the packages, run a basic agent from the README quickstart, and decide whether the framework fits your project.
Microsoft Agent Frameworkmicrosoft/agent-framework · ★ 14.5k · MIT Install options & downloads Quick start
- 1Check your prerequisites. Confirm you have Python with pip or the dotnet SDK, and a Microsoft Foundry project for the quickstart. The README does not state required Python or .NET versions.
- 2Install the package. Run pip install agent-framework for Python, or dotnet add package Microsoft.Agents.AI for .NET.
- 3Sign in to Azure. For the Python quickstart, run az login so AzureCliCredential can authenticate.
- 4Set the Foundry endpoint. Set FOUNDRY_PROJECT_ENDPOINT and, optionally, FOUNDRY_MODEL, or pass the values directly in code.
- 5Run the basic agent. Run the Python or .NET quickstart script to get a haiku from the HaikuAgent.
- 6Build a workflow. Move to the workflow samples to connect several agents using sequential, concurrent, handoff or group patterns.
What Microsoft Agent Framework is and who it is for
An AI agent is a program that uses a language model to carry out tasks. Microsoft Agent Framework provides code libraries for building agents and for connecting several agents into workflows. It supports Python and C#/.NET with consistent APIs.
The README says the framework is a strong fit if you expect to run agents in production, need orchestration beyond a single prompt or stateless chat loop, or want provider flexibility so your architecture can change without major rewrites. It is not meant for a simple chatbot or a single prompt call.
- Good fit: multi-step orchestration, production deployments, teams using Python and .NET
- Probably more than you need: a single prompt call or a simple chatbot
- Go is not in this repo; the README points to microsoft/agent-framework-go
Install agent-framework for Python or .NET
Choose the language you work in. For Python, the README installs the package with pip. It notes that this installs the standard package set and that the experimental agent-framework-lab package must be installed separately. It also mentions the install may take a minute on first run on Windows.
For .NET, add the core package with the dotnet CLI. The README also lists Foundry integration packages for the .NET quickstart.
- Python prerequisites: pip (the README does not state a Python version)
- Python quickstart also needs the Azure CLI and an az login session
- .NET prerequisites: the dotnet SDK (the README does not state a version)
- Quickstart needs access to a Microsoft Foundry project
pip install agent-framework
dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Foundry
dotnet add package Azure.AI.Projects
dotnet add package Azure.IdentityRun a basic agent in Python
The Python quickstart creates an agent backed by Azure Responses through Microsoft Foundry. It authenticates with AzureCliCredential, so run az login first. The agent is given a name and instructions, then called with agent.run.
The endpoint, deployment name and API version can be set through environment variables or passed directly to FoundryChatClient. The sample comments show the FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL variables.
- Run az login to sign in with the Azure CLI
- Set FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL, or pass the values in code
- Run the script with asyncio, as the sample does
# pip install agent-framework
# Use `az login` to authenticate with Azure CLI
import os
import asyncio
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
async def main():
agent = Agent(
client=FoundryChatClient(
credential=AzureCliCredential(),
),
name="HaikuAgent",
instructions="You are an upbeat assistant that writes beautifully.",
)
print(await agent.run("Write a haiku about Microsoft Agent Framework."))
if __name__ == "__main__":
asyncio.run(main())Run a basic agent in .NET
The .NET quickstart creates an agent with AIProjectClient.AsAIAgent(...). It reads the Foundry project endpoint from the FOUNDRY_PROJECT_ENDPOINT environment variable and uses DefaultAzureCredential for authentication. The model name defaults to the value in FOUNDRY_MODEL, falling back to the default shown in the sample.
Once created, the agent is invoked with RunAsync, like other AIAgent objects.
- Set FOUNDRY_PROJECT_ENDPOINT before running; the sample throws if it is missing
- Optionally set FOUNDRY_MODEL to choose the deployment
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
AIAgent agent =
new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
.AsAIAgent(model: deploymentName, instructions: "You are an upbeat assistant that writes beautifully.", name: "HaikuAgent");
Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));Explore orchestration, middleware and observability
Beyond a single agent, the README lists graph-based workflows that support sequential, concurrent, handoff and group collaboration patterns. Workflows also include checkpointing, streaming, human-in-the-loop control and time-travel.
The framework also lists middleware for request and response processing, built-in OpenTelemetry integration for tracing and monitoring, declarative agents defined in YAML, and a DevUI for testing and debugging workflows. Samples for each are linked from the README's Key Features section.
- Orchestration: sequential, concurrent, handoff and group collaboration
- Middleware: request/response processing, exception handling, custom pipelines
- Observability: OpenTelemetry distributed tracing
- Declarative agents: define agents in YAML
- DevUI: interactive developer UI for agents and workflows
Find more examples and learning resources
The README links to Microsoft Learn pages for an overview, a quick start, step-by-step tutorials, a user guide, and migration guides from Semantic Kernel and AutoGen. The Python packages, .NET source and sample folders are linked from Key Features.
If you hit a problem, the README has Troubleshooting and Community & Feedback sections, plus a Microsoft Foundry Discord.
- Microsoft Learn: quick start, tutorials and user guide
- Samples: python/samples and dotnet/samples folders in the repo
- Community: Microsoft Foundry Discord linked from the README
What people use it for
- Building a production agent that runs multi-step tasks instead of a single prompt
- Connecting several agents into a workflow with handoff or group collaboration
- Adding OpenTelemetry tracing to agents to monitor and debug them
- Defining agents in YAML so their setup can be versioned
- Hosting agents on Foundry-hosted infrastructure using the samples in the repo
Frequently asked questions
How do I install agent-framework?
For Python, run pip install agent-framework. For .NET, run dotnet add package Microsoft.Agents.AI. The README says the Python install includes the standard package set, and agent-framework-lab must be installed separately for experimental modules.
Is agent-framework free to use?
The repository is released under the MIT licence. Foundry, Azure and other cloud services used in the quickstart are separate products, and the README does not describe their pricing.
What do I need to run the quickstart?
The Python quickstart needs pip, the Azure CLI with az login, and a Microsoft Foundry project. The .NET path needs the dotnet SDK and a Foundry project endpoint. The README does not state exact Python or .NET versions.
Does agent-framework only work with Azure?
No. The README says it supports a broad ecosystem including Microsoft Foundry, Azure OpenAI, OpenAI and the GitHub Copilot SDK, and aims to let you switch providers without major rewrites. The quickstart itself uses Foundry.
How does agent-framework compare to LangGraph, AutoGen or Semantic Kernel?
The README does not compare it to other tools. It does provide migration guides from Semantic Kernel and AutoGen on Microsoft Learn. Comparable projects in the same space include LangGraph, AutoGen, CrewAI and Semantic Kernel.
Where is the Go version of agent-framework?
The README says Go support lives in a separate repository, microsoft/agent-framework-go, which has its own documentation, samples and issue tracker.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use Microsoft Agent Framework if you are building multi-step or multi-agent systems in Python or .NET that you plan to run in production, and you are comfortable writing code and configuring cloud credentials. If you only need a simple chatbot or single prompt call, or you need Go from this repo, pick a lighter tool or the separate Go repository instead.
Install options & downloads