Getting started with Microsoft Agent Framework

Who this is for, and what you will be able to do

This guide is for developers who already write a little Python and want to build agents with Microsoft's tooling. By the end you should be able to tell apart the core concepts of Microsoft Agent Framework (MAF): agents, threads, middleware, memory and workflows, and write a first agent that runs.

What it is and how it differs

Microsoft Agent Framework (MAF) is Microsoft's unified framework for building AI agents for both production and research use^[1]. It supports sequential, concurrent, group chat, handoff and magnetic orchestration. In magnetic orchestration, a manager agent creates and modifies a task list and coordinates subagents to complete the task^[1].

MAF also includes production features. It uses OpenTelemetry for observability, so tool invocations, orchestration steps, reasoning flows and performance metrics can be monitored in Microsoft Foundry dashboards^[1]. Agent threads and workflows can pause, resume and recover from errors, which makes longer running processes practical^[1]. For tasks that need approval, MAF supports human-in-the-loop workflows where those tasks are marked as requiring human approval^[1].

For interoperability, MAF agents can run in containers, on-premises and across several clouds. Agents can be created through an SDK of your choice, including Azure OpenAI and OpenAI^[1]. They can also use Agent-to-Agent (A2A) and the Model Context Protocol (MCP) to discover and use other agents and tools^[1].

Before you start

You need a Python environment and an inference service, either Azure OpenAI or OpenAI. To host a LangGraph agent on Foundry you also need the Foundry Project Manager role, and you should run az login so that DefaultAzureCredential can authenticate^[1].

Step 1: Create an agent

Creating an agent takes three things: an inference service (the LLM provider), a set of instructions, and an assigned name^[1]. This example creates a trip recommendation agent with Azure OpenAI:

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent( instructions="You are good at recommending trips to customers based on their preferences.", name="TripRecommender" )

Step 2: Run the agent

Use .run for non-streaming responses and .run_stream for streaming responses^[1]. This example is non-streaming:

result = await agent.run("What are good places to visit in Amsterdam?")
print(result.text)

Each run can also take options such as max_tokens, tools and model. When one task needs a specific model or tool, you can set it for that run only^[1].

Step 3: Keep a conversation going with threads

Multi-turn conversations use threads. A thread created with get_new_thread() can be saved and reused. If you do not create one, the framework creates a thread for the run, and it lasts only until the run ends^[1].

To keep a conversation for later, serialize the thread with await thread.serialize() and restore it with await agent.deserialize_thread(serialized_thread)^[1].

Middleware: adding logic between the agent, tools and the model

Middleware inserts actions while an agent works, for example logging. MAF has two kinds^[1].

Function middleware sits between the agent and the function or tool it calls. It can run code before and after the call, such as logging function calls. The next argument decides whether control passes to the next middleware or to the function itself^[1].

Chat middleware sits between the agent and the requests sent to the LLM. Its context includes the messages sent to the AI service, so it can record every model call^[1].

Three kinds of memory

MAF agent memory comes in three forms^[1]:

• In-memory storage: kept in the thread and valid only while the program runs.
• Persistent messages: set with chat_message_store_factory to keep conversation history across sessions.
• Dynamic memory: added to the context before each run, and can live in external services such as mem0, connected through context_providers.

Workflows: chaining agents and logic

A workflow is a predefined set of steps that can include AI agents as components. Workflows support multi-agent orchestration and checkpointing, which saves the workflow state^[1].

The core parts are executors and edges. An executor receives an input message, does its task and produces an output message that moves the workflow forward. An executor can be an AI agent or custom logic^[1]. Edges define message flow. The supported kinds are direct, conditional, switch-case, fan-out and fan-in^[1]. A direct edge is written like this:

from agent_framework import WorkflowBuilder

builder = WorkflowBuilder()
builder.add_edge(source_executor, target_executor)
builder.set_start_executor(source_executor)
workflow = builder.build()

Workflows emit events that help you watch execution. They include WorkflowStartedEvent, WorkflowOutputEvent, WorkflowErrorEvent, ExecutorInvokeEvent, ExecutorCompleteEvent and RequestInfoEvent^[1].

Hosting a LangGraph agent on Foundry

MAF is not limited to agents written with MAF. If you already have a LangChain or LangGraph agent, the langchain_azure_ai.agents.hosting package can expose the compiled LangGraph graph as a Microsoft Foundry hosted agent. Foundry then manages the runtime, sessions, scaling, identity and protocol endpoints, while the agent logic stays in LangGraph^[1].

Install the package with the hosting extra: pip install -U "langchain-azure-ai[hosting]>=1.2.4" azure-identity^[1].

There are two hosting protocols. ResponsesHostServer serves /responses, suits most conversational agents, and is the recommended default. InvocationsHostServer serves /invocations for a custom JSON shape or non-conversational processing^[1].

Before running, set two environment variables. FOUNDRY_PROJECT_ENDPOINT takes the project URL in the form https://<resource>.services.ai.azure.com/api/projects/<project>, and FOUNDRY_MODEL_NAME takes a model deployment name such as gpt-5-mini^[1].

Save the example as main.py, start it locally with python main.py, and send a Responses request to http://localhost:8088/responses to test it^[1].

Keeping conversation state

A client continues a conversation by passing previous_response_id or a conversation ID. If the graph is compiled with a LangGraph checkpointer, the conversation state is tied to the checkpoint. MemorySaver is fine for local testing; production should use a durable checkpointer^[1].

Adding human approval

If the graph calls LangGraph's interrupt(), ResponsesHostServer returns the pending interrupt as a function_call or mcp_approval_request item. The client resumes by sending a matching function_call_output or mcp_approval_response^[1].

Deploying to Foundry with azd

Deployment uses the Azure Developer CLI. Install the extension with azd ext install azure.ai.agents, initialize with azd ai agent init -m <manifest>, test locally with azd ai agent run (this needs Docker), then run azd provision and azd deploy. Deploying a hosted agent requires the Foundry Project Manager role^[1].

Common problems

• MemorySaver does not persist state, so switch to a durable checkpointer before going live^[1].
• Deploying a hosted agent needs the Foundry Project Manager role; without it the deployment steps cannot finish^[1].

Next steps

Get one single agent running first, then add tools and threads, and finally connect steps with a workflow. For the complete Foundry walkthrough, including the Invocations protocol and custom request schemas, see Microsoft's official documentation.

Adapted from lesson 14 of Microsoft's open-source course *AI Agents for Beginners*^[1], released under the MIT License.