Microsoft Agent Framework: Build Enterprise AI Agents in Python

Andreas Nigg
Andreas Nigg · Co-Founder, Pondhouse Data
Published Updated 12 min read
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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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:

  1. Install the necessary packages:

    1pip install agent-framework agent-framework-azure-ai pydantic
  2. Configure the Azure OpenAI environment variables. The AzureOpenAIResponsesClient needs 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:

1# tools.py
2import datetime
3from typing import Annotated
4from pydantic import Field
5
6def check_system_status(
7 service_name: Annotated[str, Field(description="The IT service to check, e.g., 'email', 'vpn', 'sharepoint'.")]
8) -> str:
9 """Checks the operational status of a known IT service."""
10 print(f"--- TOOL LOG: Checking status for '{service_name}' ---")
11 known_outages = {"email": "Degraded performance"}
12 status = known_outages.get(service_name.lower(), "Fully operational.")
13 return f"Status for {service_name}: {status}"
14
15def create_support_ticket(
16 user_name: Annotated[str, Field(description="The full name of the user reporting the issue.")],
17 issue_description: Annotated[str, Field(description="A detailed description of the IT issue.")],
18) -> str:
19 """Creates a support ticket in the helpdesk system."""
20 # In a real application, this would call an API like Jira or ServiceNow
21 ticket_id = f"IT-{int(datetime.datetime.now().timestamp())}"
22 print(f"--- TOOL LOG: Creating ticket {ticket_id} for {user_name} with issue: '{issue_description}' ---")
23 return f"Successfully created ticket {ticket_id}. A technician will be in touch shortly."

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:

1# main.py
2import asyncio
3from agent_framework import ChatAgent
4from agent_framework.azure import AzureOpenAIResponsesClient
5from tools import check_system_status, create_support_ticket
6
7# 1. Initialize the client using Azure CLI credentials
8# It automatically reads the endpoint and deployment from environment variables.
9chat_client = AzureOpenAIResponsesClient()
10
11# 2. Create the agent instance, providing instructions and tools.
12helpdesk_agent = ChatAgent(
13 chat_client=chat_client,
14 instructions="""You are an enterprise IT Helpdesk assistant.
15 1. First, understand the user's problem and identify the specific IT service.
16 2. Use the `check_system_status` tool to check for outages.
17 3. If there is an outage, inform the user and tell them the team is aware. Do NOT create a ticket.
18 4. If the system is normal, you MUST get the user's name before creating a ticket. Ask for it if you don't have it.
19 5. Once you have the user's name and issue description, use the `create_support_ticket` tool.
20 6. Confirm to the user that a ticket has been created and provide the ticket number.""",
21 tools=[check_system_status, create_support_ticket],
22)
23
24async def run_conversation():
25 print("Agent: Hello! I'm the IT Helpdesk Agent. How can I assist you today?\n")
26
27 # First user message
28 user_input_1 = "Hi, my email is not working. I can't send or receive messages."
29 print(f"User: {user_input_1}")
30
31 # The thread holds the conversation history across turns.
32 thread = helpdesk_agent.get_new_thread()
33
34 # Calling 'run' on the agent instance executes the turn.
35 # The thread is updated with this interaction.
36 agent_response_1 = await helpdesk_agent.run(user_input_1, thread=thread)
37 print(f"Agent: {agent_response_1}\n")
38
39 # Second user message (simulating a scenario with no outage)
40 # NOTE: To test this path, modify tools.py to have no email outage.
41 # The agent will ask for a name.
42 # user_input_2 = "My name is Alice."
43 # print(f"User: {user_input_2}")
44
45 # # The agent remembers the context from the first message via the thread.
46 # agent_response_2 = await helpdesk_agent.run(user_input_2, thread=thread)
47 # print(f"Agent: {agent_response_2}\n")
48
49
50if __name__ == "__main__":
51 asyncio.run(run_conversation())

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

1pip install "agent-framework[web]" uvicorn

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.

1# main.py
2import asyncio
3from agent_framework import ChatAgent
4from agent_framework.azure import AzureOpenAIResponsesClient
5from agent_framework.devui import serve # <-- Import serve_web
6from tools import check_system_status, create_support_ticket
7
8# --- Agent definition (this part remains the same) ---
9chat_client = AzureOpenAIResponsesClient()
10helpdesk_agent = ChatAgent(
11 chat_client=chat_client,
12 instructions="""You are an enterprise IT Helpdesk assistant...""", # Instructions truncated for brevity
13 tools=[check_system_status, create_support_ticket],
14)
15# --- End of agent definition ---
16
17# Create the web application instance, passing the agent to it
18serve(entities=[helpdesk_agent], port=8090, auto_open=True)
19
20# The console-based run_conversation function is no longer needed

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:

1pip install fastapi uvicorn

Now, create api.py. It imports the agent components and wraps the helpdesk_agent in an API endpoint.

1# api.py
2import os
3from fastapi import FastAPI
4from pydantic import BaseModel
5
6# Import the agent definition components
7from agent_framework import ChatAgent
8from agent_framework.azure import AzureOpenAIResponsesClient
9from tools import check_system_status, create_support_ticket
10
11# --- Agent Definition ---
12# This is the same agent we configured for the DevUI.
13# Ensure your environment variables are set for production.
14chat_client = AzureOpenAIResponsesClient()
15helpdesk_agent = ChatAgent(
16 chat_client=chat_client,
17 instructions="""You are an enterprise IT Helpdesk assistant.
18 1. First, understand the user's problem and identify the specific IT service.
19 2. Use the `check_system_status` tool to check for outages.
20 3. If there is an outage, inform the user and tell them the team is aware. Do NOT create a ticket.
21 4. If the system is normal, you MUST get the user's name before creating a ticket. Ask for it if you don't have it.
22 5. Once you have the user's name and issue description, use the `create_support_ticket` tool.
23 6. Confirm to the user that a ticket has been created and provide the ticket number.""",
24 tools=[check_system_status, create_support_ticket],
25)
26# --- End of Agent Definition ---
27
28# Create a FastAPI app instance
29app = FastAPI(
30 title="IT Helpdesk Agent API",
31 description="An API to interact with the Microsoft Agent Framework IT Helpdesk Agent.",
32)
33
34# Define the request model for our API endpoint
35class ChatRequest(BaseModel):
36 message: str
37
38@app.post("/chat")
39async def chat_with_agent(request: ChatRequest):
40 """
41 Receives a user message and returns the agent's response.
42 No thread is passed, so each request starts a new conversation.
43 """
44 response = await helpdesk_agent.run(request.message)
45 return {"response": response}

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
    
  • Dockerfile

    This file runs our FastAPI application with Uvicorn.

    1# Use an official Python runtime as a parent image
    2FROM python:3.11-slim
    3
    4WORKDIR /app
    5
    6# Copy and install requirements
    7COPY requirements.txt .
    8RUN pip install --no-cache-dir -r requirements.txt
    9
    10# Copy the application code (api.py, tools.py)
    11COPY . .
    12
    13# Expose the port the API will run on
    14EXPOSE 8000
    15
    16# Run the Uvicorn server, pointing to the FastAPI app in api.py
    17CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "8000"]

3. Build, run and test the API

With the API and Dockerfile in place, build and run the container.

  • Build the Docker image:

    1docker build -t helpdesk-agent-api .
  • Run the container. Remember to pass your Azure credentials as environment variables.

    1docker run -p 8000:8000 \
    2 -e AZURE_OPENAI_ENDPOINT="YOUR_ENDPOINT" \
    3 -e AZURE_OPENAI_API_KEY="YOUR_API_KEY" \
    4 -e AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="YOUR_CHAT_DEPLOYMENT" \
    5 -e AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME="YOUR_RESPONSES_DEPLOYMENT" \
    6 helpdesk-agent-api
  • Test with curl. Once the container is running, open a new terminal and call the /chat endpoint:

    1curl -X POST http://localhost:8000/chat \
    2-H "Content-Type: application/json" \
    3-d '{"message": "Hi, my email is not working."}'

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

Andreas Nigg

About the author

Andreas Nigg

Co-Founder, Pondhouse Data

Andreas has spent more than eight years building data applications. At Pondhouse Data he designs and ships AI systems and integrates them into complex, real-world environments.