Microsoft Agent Framework: Build Enterprise AI Agents in Python

On this page
The Microsoft Agent Framework is Microsoft's open-source framework for building AI agents in Python and C#. It unifies the multi-agent patterns of AutoGen with the enterprise features of Semantic Kernel, and adds what production agents need: OpenTelemetry tracing, Entra ID integration, human-in-the-loop approvals and checkpointing for long-running workflows. This guide explains the architecture and then builds an IT helpdesk agent, from tools to a Docker-packaged FastAPI endpoint.
Why does that matter? We've all seen the impressive demos of agents that plan, reason, and execute complex tasks. Moving from a proof-of-concept to a reliable production application is a different story. In an enterprise setting, you need more than prompting and a well-designed agent loop. You need state management, tight security, reliable tool integration and an auditable trail of the agent's reasoning.
Many existing frameworks are excellent for rapid prototyping but lack the scaffolding for production systems. They leave developers to solve observability, error handling and long-running task management on their own (especially the last one). That leaves a big gap between a demo on a developer's machine and a business process you can trust with critical operations. Microsoft aims to close it with a single framework for the whole agent lifecycle, enterprise features included.
NOTE: One of the main advantages of the Microsoft Agent Framework is that it's one of the few agent frameworks that supports both Python and C#. It's basically the only major agent framework for C# and .NET developers.
Update (November 2026): The Python API changed after this post was written. Per Microsoft's
2026 upgrade guide,
ChatAgent is now Agent (python-1.0.0b260210), AgentThread is now AgentSession with
agent.create_session() replacing get_new_thread(), and AzureOpenAIResponsesClient was removed in
python-1.0.0rc6 in favor of FoundryChatClient or OpenAIChatClient. Azure AI Foundry is now
Microsoft Foundry; the code below
targets the late-2025 preview releases, such as agent-framework==1.0.0b251104.
Microsoft Agent Framework architecture: an operating system for agents
To see what makes the Microsoft Agent Framework special, think of it as an operating system for your AI agents. I know this sounds like click-bait, but bear with me. A standard OS provides the services applications need to run reliably: it manages memory, schedules tasks and gives software a consistent way to talk to hardware. Similarly, the Agent Framework manages an agent's memory (state), runs its programs (tools) and handles its communication with other systems (workflows).
That sounds appealing: all the required components packaged and managed by one framework, so developers can focus on the agent's logic. Let's find out if it lives up to the promise.
The four core components of the Microsoft Agent Framework
The framework consists of four components that work together.
-
AI agents are the core "workers", the "brains" of the operation. Each agent uses an LLM to reason, plan and act based on a given set of instructions. Microsoft designed these agents as an evolution of its earlier projects, combining the multi-agent conversational patterns of AutoGen with the structured, tool-oriented approach of Semantic Kernel.
-
Tools (AIFunctions) are how agents interact with the outside world. Instead of relying on fragile text parsing, the framework lets you define tools as strongly typed Python or C# functions. You decorate a standard function to expose it to the agent with its specific inputs and outputs. This makes tools safer, more predictable and easier to debug, because the framework translates the LLM's intent into a valid function call.
-
Workflows connect the agents, like a nervous system. The framework uses a graph-based system to define multi-step processes, a big step beyond simple, linear agent chains. With workflows, you can orchestrate multiple agents and tools, implement conditional logic ("if X, then do Y"), run tasks in parallel and, importantly, pause for human-in-the-loop approvals.
-
State management gives agents memory. An agent without memory is just a stateless tool. The framework provides an object called the AgentThread, which holds the entire history and context of a conversation or task. This durable memory is essential for multi-turn conversations and long-running jobs.
Enterprise features of the Microsoft Agent Framework
The core components are the foundation for a set of features built for enterprise deployment. This is where the framework tries to set itself apart from other players.
-
Observability. For any production system, you must be able to answer "Why did it do that?" The framework has built-in support for OpenTelemetry, the industry standard for tracing and logging. You can trace every step an agent takes, from its initial reasoning to the exact tool it called and the result it got back. That lets you debug failures, audit decisions and optimize performance. Our post on LLM tracing with Opik shows an open-source tool for collecting and reviewing such traces.
-
Security and governance. The framework integrates with services like Azure AI Content Safety to filter harmful content (see our post on Azure OpenAI content filters) and with Microsoft Entra ID for authentication and authorization. Its first-class support for "human-in-the-loop" workflows is a governance feature we are happy to see. You can design agents that pause and request human approval for sensitive actions, like authorizing a payment, deleting data or sending a customer-facing message, so a person always has the final say. AI can do amazing things, but most of the time you want a human in control.
-
Durability and long-running tasks. Business processes don't always finish in seconds. They can take hours or days and must survive restarts and interruptions. The framework's workflows are designed to be durable. Using a technique called checkpointing , the state of a workflow is saved to persistent storage and resumed later. You can build agents that manage a multi-day expense approval process or orchestrate a weekend-long data migration, and they pick up right where they left off.
-
Open standards and interoperability. To fit into an enterprise IT environment, a platform must speak the same language as other systems. The framework uses OpenAPI to integrate with existing APIs (the same OpenAPI specs can also be turned into MCP servers automatically) and supports the Model Context Protocol (MCP). MCP is an emerging standard for connecting AI models to external data sources and tools, so agents built on the framework can access the information they need.
Last but not least, the Microsoft Agent Framework provides full .NET support, which makes it a first-class citizen in the Microsoft ecosystem.
How durability and long-running tasks work in the Microsoft Agent Framework
Long-running durability is one of the framework's most important enterprise features, so it's worth understanding how it works. Think of a "save game". While an agent runs, its state (history, plans, etc.) is in memory. When it needs to wait for a long-running external process, the framework takes a "snapshot" of that state, saves it to a durable location and can shut down the process. When the external event completes, the framework "loads the saved game", rehydrating the agent's state so it continues exactly where it left off.
The process has three phases:
-
Pause and checkpoint: When a workflow must wait, for example for a human approval or a multi-hour data job, the framework serializes the agent's entire AgentThread into a storable format like JSON. The official documentation calls this "checkpointing".
-
Durable storage: The serialized state goes to a configurable persistence provider. In production, you would plug in a database like Azure Cosmos DB, which stores the state outside the application's memory.
-
Resume and rehydrate: When an external trigger arrives (e.g. an API call from an approval button), a new process loads the saved state from the database. It deserializes the data and rehydrates the AgentThread into a live object. The agent is "awake" again with its full memory and context, ready for the next step.
Take an expense approval bot as an example. An employee submits a $500 expense. The agent checks company policy and determines it needs manager approval. Here, the long-running process begins. The agent's workflow sends an approval request to the manager and then hits a pause point. The framework checkpoints the AgentThread, containing the receipt data, the policy check result and its current status of "awaiting_manager_approval", and saves it to a database. Hours later, the manager clicks "Approve", which triggers an API call. The API handler loads the saved state, rehydrates the agent and feeds it the "approved" event. The agent wakes up, calls the payment processing tool and confirms completion with the employee.
This ability to pause, persist and resume is what makes the Microsoft Agent Framework so interesting in our eyes.
How the Microsoft Agent Framework connects to Copilot Studio and Microsoft 365
You can use the Microsoft Agent Framework standalone, but it is also a foundational part of Microsoft's broader AI and Copilot strategy.
It is Microsoft's "pro-code" engine. Developers build enterprise-grade agents with it, and those agents can then be integrated, managed and surfaced across the Microsoft ecosystem, connecting custom development with end-user applications.
Note: Microsoft considers Copilot Studio as their "low-code" platform and Microsoft Foundry (formerly Azure AI Foundry) as the underlying infrastructure tying everything together.
Here's how the connection between Microsoft 365 Copilot and the Agent Framework plays out:
- The framework is a pro-code foundation for Copilot Studio, Microsoft's low-code platform for building and customizing copilots. Developers use the Agent Framework in Python or C# to build stateful agents with extensive business logic and tool integrations. These agents can then be connected to and managed within Copilot Studio. Developers handle the back-end logic, while business users or IT admins use the low-code interface to configure, deploy and monitor these agents without writing code. (For a low-code example, see how to use SharePoint lists as knowledge sources in Copilot Studio.)
Agent Framework connected to Copilot Studio, Microsoft Foundry (formerly Azure AI Foundry) and M365 Agents SDK
Hands-on: building an enterprise IT helpdesk agent with Microsoft Agent Framework
Now let's put the Microsoft Agent Framework into practice and see how it really works. We'll build a simple but practical IT helpdesk agent that uses state management, multi-turn conversation and tool calls.
The goal: our agent triages IT support requests. It first checks for known system outages to avoid unnecessary tickets. If there are no outages, it collects the necessary information from the user and creates a support ticket.
NOTE: We're using Python in these examples, but all of them can easily be translated to .NET C# as well. See the github repository for the semantically equivalent C# code.
Prerequisites
Before we start, make sure you have the following set up:
-
Install the necessary packages:
-
Configure the Azure OpenAI environment variables. The
AzureOpenAIResponsesClientneeds to know your endpoint and deployment name. Make sure you have the following set in your environment:- AZURE_OPENAI_ENDPOINT: Your Azure OpenAI endpoint
- AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: The name of your Azure OpenAI chat model deployment
- AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: The name of your Azure OpenAI Responses deployment
- AZURE_OPENAI_API_KEY: Your Azure OpenAI API key
Step 1: Define the tools (the agent's "hands")
First, we create the tools our agent can use. These are standard Python
functions. We use typing.Annotated and pydantic.Field to describe the
function parameters, which helps the LLM use them correctly.
Create a file named tools.py:
Step 2: Create and run the agent
Next, we define the agent and interact with it. The main class is
ChatAgent, which we configure with a client, instructions and our list of
tools. The agent itself doesn't keep the conversation history between
run() calls. That history lives in an AgentThread: we create one with
get_new_thread() and pass it to every call that belongs to the same
conversation, which gives us stateful, multi-turn interactions.
Create a file named main.py:
Step 3: Debugging with the Agent Framework Dev UI
The built-in Dev UI is very handy for following the agent's reasoning step by step. Let's adapt our code to launch it.
1. Install the web components
2. Modify main.py to serve the agent
Update main.py by replacing the run_conversation part with a call to
serve from agent_framework.devui.
When you run the script, a web UI opens in your browser at
http://localhost:8090, where you can chat with the agent and watch its tool
calls and responses in real time.
NOTE: This is actually so cool. The UI is really well made and gives a very nice overview of your chat client.
Dev UI showing a helpdesk chat and the check_system_status tool call
Step 4: Deploying your agent for production
The Dev UI is great for local development and debugging, but it is not built for production. To let other applications use your agent, expose it through a standard, scalable web API. We use FastAPI, a fast Python web framework, to create a production-ready endpoint.
1. Create the production API endpoint
We create a new file, api.py, for our web server. This keeps the production
serving logic separate from local debugging scripts.
First, make sure you have FastAPI and the Uvicorn web server installed:
Now, create api.py. It imports the agent components and wraps the
helpdesk_agent in an API endpoint.
Note on statefulness: This simple API doesn't keep any conversation
history: every request runs on a fresh AgentThread. For multi-turn chats,
keep one thread per conversation and pass it to run(..., thread=thread).
For a production environment that can scale or restart without losing
context, you also need a persistence layer that saves and loads these
threads, as described in the section on how durability and long-running
tasks work.
2. Update files for containerization
Next, prepare the files to package the application into a Docker container.
-
requirements.txt# requirements.txt agent-framework agent-framework-azure-ai fastapi uvicorn pydantic -
DockerfileThis file runs our FastAPI application with Uvicorn.
3. Build, run and test the API
With the API and Dockerfile in place, build and run the container.
-
Build the Docker image:
-
Run the container. Remember to pass your Azure credentials as environment variables.
-
Test with
curl. Once the container is running, open a new terminal and call the/chatendpoint:
You'll get a JSON response from your agent, which confirms the API works. You can deploy this container to any cloud service, such as Azure App Service or Azure Container Apps.
Wrapping up: what the Microsoft Agent Framework offers
The Microsoft Agent Framework is a production-focused toolkit for enterprise AI applications. Its main strength is that it combines the research-led patterns of AutoGen with the stability, security and structure that real-world business processes need.
As an "operating system" for agents, it takes care of state management,
observability and long-running tasks, so developers can focus on the agent's
logic. In this guide, that meant typed tools, a ChatAgent with
instructions, the Dev UI for debugging and a FastAPI endpoint in a Docker
container.
With first-class support for both Python and .NET, we expect it to become the leading enterprise-grade agent framework for the .NET ecosystem, while also giving Python developers a solid, familiar environment.
The natural next step is to take the helpdesk agent from this guide and add a persistence layer, so it survives restarts. Then move on to multi-step processes: Part 2: Orchestrating Complex Tasks with Microsoft Agent Framework Workflows continues this series.
If you are planning an agent like this for your own IT or business processes, our AI consulting team builds them with clients, from the first prototype to production.
Official resources
- Official Documentation: The best place to start for a deep dive into the framework's architecture and capabilities.
- GitHub Repository: Explore the source code, find more examples, and contribute to the project.
- Introductory Blog Post: Read the original announcement from Microsoft for more context on the vision and strategy behind the framework.
Interested in building high-quality AI agent systems?
We prepared a comprehensive guide based on cutting-edge research for how to build robust, reliable AI agent systems that actually work in production. This guide covers:
- Understanding the 14 systematic failure modes in multi-agent systems
- Evidence-based best practices for agent design
- Structured communication protocols and verification mechanisms
Further reading
- High-Quality AI Agent Systems: Learn the best practices and architectural patterns for building robust and reliable AI agents.
- AI Agents From Scratch: A foundational guide to understanding the core concepts of how AI agents work, from planning to tool execution.
- Langfuse: The Open Source Observability Platform: Dive deeper into observability for LLM applications, a key theme for building enterprise-grade agents.
- Smolagents: A Minimalist Agent Framework: Explore a different, lightweight approach to agent development for context and comparison.
- Building a RAG Pipeline with Azure AI Search: Discover how to power your agents with internal knowledge by building a retrieval-augmented generation system on Azure.


