Skip to content
MfPy

Microsoft Agent Framework (Python) — Installation and Quick Start

Get started with agent-framework: installation, authentication, your first agent, tools, sessions, and async patterns.

This guide covers everything you need to get your first agent running in Python using agent-framework (version 1.26.0, checked 2026-11-19).


PropertyValue
Package nameagent-framework
Current version1.26.0
Import rootagent_framework
Python requirement3.11 or later (Python 3.10 installs no longer resolve from 1.25.0)
Terminal window
pip install agent-framework

The agent-framework meta package depends on agent-framework-core[all], so it pulls in every integration package (OpenAI, Foundry, Anthropic, A2A, Redis, DevUI and so on, including the beta ones). That is convenient for learning but heavy for a deployed service. For a smaller install, take the core and only the integrations you use:

Terminal window
pip install agent-framework-core # Agent, tools, sessions, workflows
pip install agent-framework-openai # OpenAI / Azure OpenAI (OpenAIChatClient)
pip install agent-framework-foundry # Microsoft Foundry (FoundryChatClient)
pip install agent-framework-a2a --pre # A2A protocol (beta)
pip install agent-framework-declarative # Declarative YAML agents

The import paths are the same either way (agent_framework.openai, agent_framework.foundry, …); a namespace whose package is not installed raises a ModuleNotFoundError naming the package to install. Two integrations have platform limits: agent-framework-github-copilot needs Python 3.11+ (now the baseline for everything), and agent-framework-hyperlight installs only on Linux x86-64 and Windows AMD64.


The framework is organised around a small number of core primitives:

  1. Agent — the primary class. Wraps a chat client, holds instructions, and orchestrates tool calls.
  2. Chat client — provider-specific wrapper (FoundryChatClient, OpenAIChatClient, AnthropicClient, …). Passed to Agent(client=...).
  3. @tool — decorator that exposes a Python function to the agent. Type hints and docstring become the tool schema automatically.
  4. AgentSession — multi-turn state. Passed to agent.run(prompt, session=session) to maintain conversation history.
  5. WorkflowBuilder — directed-graph orchestration for multi-agent pipelines.
  6. @workflow / @step — functional workflow API; write multi-step pipelines as plain async Python without graph wiring.

The following example creates a minimal single-turn agent using OpenAI as the chat backend.

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
async def main() -> None:
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a helpful assistant. Answer concisely.",
)
response = await agent.run("What is the capital of France?")
print(response.text)
asyncio.run(main())

Replace OpenAIChatClient with FoundryChatClient for Azure-hosted models:

import asyncio
import os
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
async def main() -> None:
client = FoundryChatClient(
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
model=os.environ.get("FOUNDRY_MODEL", "gpt-6.1-sol"),
credential=AzureCliCredential(),
)
agent = Agent(
client=client,
instructions="You are a helpful assistant.",
)
response = await agent.run("Summarise the agent-framework in one sentence.")
print(response.text)
asyncio.run(main())

Use the @tool decorator to expose Python functions. The framework reads type hints and the docstring to build the tool schema automatically.

import asyncio
from agent_framework import Agent, tool
from agent_framework.openai import OpenAIChatClient
@tool
def get_weather(location: str) -> str:
"""Return the current weather for a location."""
return f"Sunny, 22°C in {location}"
async def main() -> None:
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a weather assistant.",
tools=[get_weather],
)
response = await agent.run("What is the weather in London?")
print(response.text)
asyncio.run(main())

Use agent.create_session() to maintain conversation history across multiple turns:

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
async def main() -> None:
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a helpful assistant.",
)
session = agent.create_session()
response1 = await agent.run("My name is Alice.", session=session)
print(response1.text)
response2 = await agent.run("What is my name?", session=session)
print(response2.text) # Agent remembers: Alice
asyncio.run(main())

Pass stream=True to agent.run() to receive token-by-token output:

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
async def main() -> None:
agent = Agent(
client=OpenAIChatClient(),
instructions="You are a helpful assistant.",
)
async for chunk in await agent.run("Explain asyncio in Python.", stream=True):
print(chunk.text, end="", flush=True)
print()
asyncio.run(main())

ModuleNotFoundError: No module named 'agent_framework'

Section titled “ModuleNotFoundError: No module named 'agent_framework'”

Run pip install agent-framework in your active environment. For provider-specific classes, install the matching sub-package (e.g. pip install agent-framework-openai).

ModuleNotFoundError: The 'agent-framework-foundry' package is not installed

Section titled “ModuleNotFoundError: The 'agent-framework-foundry' package is not installed”

The agent_framework.foundry, agent_framework.openai, agent_framework.anthropic (and so on) namespaces ship with the core package and load their integration package on first use. Install the package the message names: pip install agent-framework-foundry. (The older agent-framework-azure-ai package stopped at 1.0.0rc6 and does not provide FoundryChatClient.)

ImportError: cannot import name 'ChatAgent' (or ChatMessage, ai_function)

Section titled “ImportError: cannot import name 'ChatAgent' (or ChatMessage, ai_function)”

The code was written for a 2025 preview. Those names were renamed before 1.0: ChatAgent → Agent, ChatMessage → Message, @ai_function → @tool. See the list of breaking changes.

SettingNotFoundError when creating the client

Section titled “SettingNotFoundError when creating the client”

OpenAIChatClient() with no arguments reads OPENAI_API_KEY and OPENAI_MODEL (or OPENAI_CHAT_MODEL) from the environment. A missing model gives “Model must be specified via the ‘model’ parameter or the ‘OPENAI_CHAT_MODEL’, ‘OPENAI_MODEL’ environment variable”; a missing key gives the less obvious “Exactly one of ‘base_url’, ‘endpoint’ must be provided”, because without a key the client cannot tell which service you mean. Set the variables, or pass model= and api_key= explicitly. A .env file is read only when you pass env_file_path=.


  • Comprehensive guide — configuration, agents, streaming, sessions, workflows and more on one page
  • Model providers — all chat client constructors with real signatures
  • Tools — @tool, FunctionTool, approval gates, schemas, runtime context
  • MCP integration — MCPStdioTool, MCPStreamableHTTPTool, as_mcp_server()
  • Multi-agent orchestration — WorkflowBuilder, sequential, concurrent, handoff, group chat
  • API map — which page documents each class