Environment:Microsoft Agent framework Python 3 10 Runtime

Knowledge Sources	Microsoft Agent Framework DEV_SETUP.md
Domains	Infrastructure, AI_Agents
Last Updated	2026-02-11 16:45 GMT

Overview

Python 3.10+ runtime environment with uv package manager for running the Microsoft Agent Framework core and all sub-packages on Linux, Windows, or macOS.

Description

This environment defines the Python runtime, build tooling, and platform requirements for developing and running the Microsoft Agent Framework. The framework is built on Python 3.10+ and uses uv as the primary package manager (not pip). The build backend is flit. All packages in the monorepo share the same Python version constraint and are tested against Python 3.10 through 3.14 on Ubuntu and Windows runners. macOS is supported but not currently tested in CI.

Usage

Use this environment for any usage of the Microsoft Agent Framework Python packages. It is the mandatory prerequisite for all Agent Framework implementations including agent creation, orchestration workflows, declarative agents, and provider-specific integrations. Every implementation page in this wiki requires this environment.

System Requirements

Category	Requirement	Notes
OS	Linux (Ubuntu), Windows, macOS	CI tests run on ubuntu-latest and windows-latest
Python	>= 3.10	Supports 3.10, 3.11, 3.12, 3.13, 3.14
Package Manager	uv >= 0.9, < 1.0.0	Primary dependency manager (not pip)
Build Backend	flit-core >= 3.11, < 4.0	Used for package building
DevContainer	Python 3.13 (Debian Bullseye)	mcr.microsoft.com/devcontainers/python:3.13-bullseye

Dependencies

System Packages

`uv` >= 0.9 (Astral UV package manager)
`git` (for repository operations)

Python Packages (Core)

`typing-extensions` (no version constraint)
`pydantic` >= 2, < 3
`pydantic-settings` >= 2, < 3
`opentelemetry-api` >= 1.39.0
`opentelemetry-sdk` >= 1.39.0
`opentelemetry-semantic-conventions-ai` >= 0.4.13
`openai` >= 1.99.0
`azure-identity` >= 1, < 2
`azure-ai-projects` >= 2.0.0b3
`mcp[ws]` >= 1.24.0, < 2
`packaging` >= 24.1

Development Tools

`ruff` >= 0.11.8 (formatter/linter)
`pytest` >= 8.4.1
`pytest-asyncio` >= 1.0.0
`mypy` >= 1.16.1
`pyright` >= 1.1.402
`poethepoet` >= 0.36.0 (task runner)

Credentials

No credentials are required for the base runtime environment. Provider-specific credentials are documented in Environment:Microsoft_Agent_framework_API_Credentials.

Quick Install

# Install uv (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Python versions
uv python install 3.10 3.11 3.12 3.13

# Create virtual environment
uv venv --python 3.10

# Install framework and all dependencies
uv sync --dev
uv run poe install
uv run poe prek-install

# Or use single setup command (requires poe in current env)
uv run poe setup -p 3.13

Code Evidence

Python version constraint from `python/packages/core/pyproject.toml:6`:

requires-python = ">=3.10"

Supported Python classifiers from `python/packages/core/pyproject.toml:13-23`:

classifiers = [
  "License :: OSI Approved :: MIT License",
  "Development Status :: 4 - Beta",
  "Programming Language :: Python :: 3.10",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
]

Platform environments from `python/packages/core/pyproject.toml:66-70`:

environments = [
    "sys_platform == 'darwin'",
    "sys_platform == 'linux'",
    "sys_platform == 'win32'"
]

CI test matrix from `.github/workflows/python-tests.yml:19`:

python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
os: [ubuntu-latest, windows-latest]

Build system from `python/packages/core/pyproject.toml:130-132`:

[build-system]
requires = ["flit-core >= 3.11,<4.0"]
build-backend = "flit_core.buildapi"

Common Errors

Error Message	Cause	Solution
`Python version 3.9 not supported`	Python version below minimum	Install Python 3.10+: `uv python install 3.10`
`No module named 'agent_framework'`	Package not installed in venv	Run `uv sync --dev` from the `python/` directory
`uv: command not found`	uv package manager not installed	sh`
`flit_core not found`	Build backend missing	Run `uv sync --dev` to install all build dependencies

Compatibility Notes

Windows: Fully supported and CI-tested. Use PowerShell for uv installation.
WSL: Clone repository to `~/workspace` or similar folder. Avoid `/mnt/c/` paths for performance.
macOS: Supported but not currently tested in CI. Use Homebrew: `brew install uv`.
Python 3.14: Some packages have constraints. PowerFx is unavailable on 3.14+. grpcio requires >= 1.76.0 on 3.14.
DevContainer: Pre-configured with Python 3.13 on Debian Bullseye.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment