pyproject.toml

[project]
name = "agent-framework"
description = "Microsoft Agent Framework for building AI Agents with Python. This package contains core and a curated set of optional integrations."
authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
readme = "README.md"
requires-python = ">=3.10"
version = "1.22.0"
license-files = ["LICENSE"]
urls.homepage = "https://aka.ms/agent-framework"
urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
urls.issues = "https://github.com/microsoft/agent-framework/issues"
classifiers = [
  "License :: OSI Approved :: MIT License",
  "Development Status :: 5 - Production/Stable",
  "Intended Audience :: Developers",
  "Programming Language :: Python :: 3",
  "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",
  "Programming Language :: Python :: 3.15",
  "Typing :: Typed",
]
dependencies = [
    "agent-framework-core[all]==1.22.0",
]

[dependency-groups]
dev = [
    "uv==0.13.1",
    "pytest==9.1.1",
    "pytest-asyncio==1.4.0",
    "pytest-cov==7.1.0",
    "pytest-xdist[psutil]==3.8.0",
    "pytest-timeout==2.4.0",
    "pytest-retry==1.7.0",
    "azure-monitor-opentelemetry>=1.8.10,<2",
    "mcp",
    # Optional SDK used by the agent-hooks tests and isolated source checks.
    "agent-hooks-sdk>=0.1.0a4,<0.2",
    "opentelemetry-sdk",
    # Task runtime used by every supported Python version.
    "poethepoet==0.48.0",
]
tool-runtime = [
    "packaging==26.3",
    "rich>=13.7.1,<16.0.0",
    'tomli==2.5.0; python_version < "3.11"',
]
tool-hooks = [
    "prek==0.5.5",
]
tool-markdown = [
    "pygments==2.21.0",
]

[tool.uv]
package = false
prerelease = "if-necessary"
required-version = "==0.13.1"
# Security floors for transitive dependencies.
override-dependencies = [
    "mcp>=2.2.0,<3",
    "uvicorn[standard]>=0.34.0",
    "python-multipart>=0.0.31",
]
environments = [
    "sys_platform == 'darwin'",
    "sys_platform == 'linux'",
    "sys_platform == 'win32'"
]

[tool.uv.workspace]
members = [ "packages/*" ]
exclude = [ "packages/lab" ]

[tool.uv.sources]
agent-framework = { workspace = true }
agent-framework-core = { workspace = true }
agent-framework-a2a = { workspace = true }
agent-framework-ag-ui = { workspace = true }
agent-framework-azure-ai-search = { workspace = true }
agent-framework-azure-documentdb = { workspace = true }
agent-framework-azure-cosmos = { workspace = true }
agent-framework-anthropic = { workspace = true }
agent-framework-bedrock = { workspace = true }
agent-framework-chatkit = { workspace = true }
agent-framework-claude = { workspace = true }
agent-framework-copilotstudio = { workspace = true }
agent-framework-declarative = { workspace = true }
agent-framework-devui = { workspace = true }
agent-framework-duckdb = { workspace = true }
agent-framework-foundry = { workspace = true }
agent-framework-foundry-hosting = { workspace = true }
agent-framework-foundry-local = { workspace = true }
agent-framework-gemini = { workspace = true }
agent-framework-github-copilot = { workspace = true }
agent-framework-hosting = { workspace = true }
agent-framework-hosting-a2a = { workspace = true }
agent-framework-hosting-mcp = { workspace = true }
agent-framework-hosting-responses = { workspace = true }
agent-framework-hosting-telegram = { workspace = true }
agent-framework-hyperlight = { workspace = true }
agent-framework-mem0 = { workspace = true }
agent-framework-mistral = { workspace = true }
agent-framework-mongodb = { workspace = true }
agent-framework-monty = { workspace = true }
agent-framework-ollama = { workspace = true }
agent-framework-openai = { workspace = true }
agent-framework-oracle = { workspace = true }
agent-framework-orchestrations = { workspace = true }
agent-framework-postgres = { workspace = true }
agent-framework-sql-server = { workspace = true }
agent-framework-purview = { workspace = true }
agent-framework-qdrant = { workspace = true }
agent-framework-redis = { workspace = true }
agent-framework-azure-contentunderstanding = { workspace = true }
agent-framework-tools = { workspace = true }
agent-framework-typesafe = { workspace = true }

[tool.ruff]
line-length = 120
target-version = "py310"
fix = true
include = ["*.py", "*.pyi", "**/pyproject.toml", "*.ipynb"]
exclude = ["scripts"]
extend-exclude = [
    "[{][{]cookiecutter.package_name[}][}]",
]
preview = true

[tool.ruff.lint]
fixable = ["ALL"]
unfixable = []
select = [
    "ASYNC", # async checks
    "B", # bugbear checks
    "CPY", # copyright
    "D", # pydocstyle checks
    "E", # pycodestyle error checks
    "ERA", # remove connected out code
    "F", # pyflakes checks
    "FIX", # fixme checks
    "I", # isort
    "INP", # implicit namespace package
    "ISC", # implicit string concat
    "Q", # flake8-quotes checks
    "RET", # flake8-return check
    "RSE", # raise exception parantheses check
    "RUF", # RUF specific rules
    "S", # Bandit checks
    "SIM", # flake8-simplify check
    "T100", # Debugger
    "T20", # flake8-print checks
    "TD", # todos
    "W", # pycodestyle warning checks
]
ignore = [
    "D100", # allow missing docstring in public module
    "D104", # allow missing docstring in public package
    "D421", # allow property docstrings that start with a verb
    "D418", # allow overload to have a docstring
    "TD003", # allow missing link to todo issue
    "FIX002", # allow todo
    "ASYNC119", # allow yielding inside async-generator context managers
    "B027", # allow empty non-abstract method in ABC
    "B905", # `zip()` without an explicit `strict=` parameter
    "RUF067", # allow version detection in __init__.py
    "RUF201", # allow stable rule codes in Ruff selectors
]

[tool.ruff.lint.per-file-ignores]
# Ignore all directories named `tests` and `samples`.
"**/tests/**" = ["D", "INP", "TD", "ERA001", "RUF", "S"]
"samples/**" = ["D", "INP", "ERA001", "RUF", "S", "T201", "CPY"]
"*.ipynb" = ["CPY", "E501"]

[tool.ruff.format]
docstring-code-format = true

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.lint.flake8-copyright]
notice-rgx = "^# Copyright \\(c\\) Microsoft\\. All rights reserved\\."
min-file-size = 1

[tool.pytest.ini_options]
testpaths = ['packages/**/tests', 'packages/**/ag_ui_tests']
norecursedirs = '**/lab/**'
addopts = "-ra -q -r fEX"
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"
filterwarnings = []
timeout = 60
markers = [
    "azure: marks tests as Azure provider specific",
    "azure-ai: marks tests as Azure AI provider specific",
    "openai: marks tests as OpenAI provider specific",
    "integration: marks tests as integration tests that require external services",
]

[tool.coverage.run]
omit = [
    "**/__init__.py"
]

[tool.pyright]
# Pyright is the sole SOURCE-code type checker. Tests + samples are covered by mypy,
# pyrefly, ty (and zuban) instead, so Pyright excludes them entirely -- no per-package
# test executionEnvironments are needed anymore.
exclude = ["**/tests/**", "**/ag_ui_tests/**", "samples/**", "**/.venv/**", "packages/devui/frontend/**"]
typeCheckingMode = "strict"
reportUnnecessaryIsInstance = false
reportMissingTypeStubs = false
reportUnnecessaryCast = "error"
# With MyPy off source, mypy-only ``# type: ignore`` comments are now dead weight. Flag
# them so they get removed and do not creep back in.
reportUnnecessaryTypeIgnoreComment = "error"

# MyPy (and zuban, which reads this [mypy]-compatible config) no longer run on source
# code -- Pyright is the sole source-code type checker. These checkers run over the
# tests + samples instead, in a deliberately relaxed mode: real type errors in how the
# public API is exercised are caught, but test/sample authors are not burdened with
# annotating every function. See docs/skills/python-code-quality.
[tool.mypy]
plugins = ['pydantic.mypy']
python_version = "3.10"
ignore_missing_imports = true
check_untyped_defs = true
disallow_untyped_defs = false
disallow_incomplete_defs = false
disallow_untyped_decorators = false
no_implicit_optional = true
warn_return_any = false
warn_unused_ignores = false
show_error_codes = true

# NumPy 2.5 stubs use Python 3.12 type-statement syntax while mypy intentionally
# targets Python 3.10 for test typing; skip parsing NumPy internals.
[[tool.mypy.overrides]]
module = ["numpy", "numpy.*"]
follow_imports = "skip"
follow_imports_for_stubs = true

# ty (preview) over tests + samples. Relaxed: ty's defaults are gradual, and a few
# categories are too noisy on test/mock-heavy code to gate on yet.
[tool.ty.rules]
unused-ignore-comment = "ignore"
unused-type-ignore-comment = "ignore"

[tool.bandit]
targets = ["agent_framework"]
exclude_dirs = ["tests", "scripts", "samples"]

[tool.poe.executor]
type = "uv"
locked = true
group = "tool-runtime"

# Workspace setup
[tool.poe.tasks.install]
help = "Install all workspace packages, extras, and dependency groups from the lockfile."
cmd = "uv sync --all-packages --all-extras --all-groups --no-group tool-runtime --no-group tool-hooks --no-group tool-markdown --frozen --prerelease=if-necessary"

[tool.poe.tasks.setup]
help = "Create the workspace virtual environment for -P/--python, install dependencies, and install prek hooks."
sequence = [
    { ref = "venv --python $python"},
    { ref = "install" },
    { ref = "prek-install" }
]
args = [{ name = "python", default = "3.13", options = ['-P', '-p', '--python'] }]

[tool.poe.tasks.venv]
help = "Create or recreate the workspace virtual environment for -P/--python."
cmd = "uv venv --clear --python $python"
args = [{ name = "python", default = "3.13", options = ['-P', '-p', '--python'] }]

[tool.poe.tasks.prek-install]
help = "Install or refresh the prek git hooks."
executor = { group = "tool-hooks", locked = true }
cmd = "prek install --overwrite"

# Syntax, typing, and validation
[tool.poe.tasks.syntax]
help = "Run Ruff formatting and Ruff checks for -P/--package packages, or use -S/--samples; add -F/--format or -C/--check to narrow the mode."
cmd = "python -m scripts.workspace_poe_tasks syntax"

[tool.poe.tasks.pyright]
help = "Run Pyright for -P/--package packages, use -A/--all for one aggregate sweep, or use -S/--samples for sample checks."
cmd = "python -m scripts.workspace_poe_tasks pyright"

[tool.poe.tasks.mypy]
help = "Run MyPy over -P/--package test suites (alias for `test-typing --checker mypy`)."
cmd = "python -m scripts.workspace_poe_tasks mypy"

[tool.poe.tasks.test-typing]
help = "Run the tests/samples type checkers (mypy, pyrefly, ty, zuban) for -P/--package, -A/--all, or -S/--samples. Narrow with `--checker NAME` (repeatable)."
cmd = "python -m scripts.workspace_poe_tasks test-typing"

[tool.poe.tasks.typing]
help = "Run Pyright over source and the tests/samples checkers for -P/--package packages, or use -A/--all."
cmd = "python -m scripts.workspace_poe_tasks typing"

[tool.poe.tasks.check-packages]
help = "Run `syntax` and `pyright` for -P/--package packages."
cmd = "python -m scripts.workspace_poe_tasks check-packages"

[tool.poe.tasks.check]
help = "Run package syntax, pyright, and tests for -P/--package packages; without -P also include sample checks and markdown code lint, or use -S/--samples for sample-only checks."
executor = { group = ["tool-runtime", "tool-markdown"], locked = true }
cmd = "python -m scripts.workspace_poe_tasks check"

[tool.poe.tasks.markdown-code-lint]
help = "Lint Python code blocks embedded in README and sample markdown files."
executor = { group = "tool-markdown", locked = true }
cmd = "python -m scripts.check_md_code_blocks 'README.md' './packages/**/README.md' './samples/**/*.md' --exclude cookiecutter-agent-framework-lab --exclude tau2 --exclude 'packages/devui/frontend' --exclude context_providers/azure_ai_search"

# Testing
[tool.poe.tasks.test]
help = "Run tests for -P/--package packages, or use -A/--all for one aggregate sweep; add -C/--cov for coverage."
cmd = "python -m scripts.workspace_poe_tasks test"

# Build and publishing
[tool.poe.tasks._clean-dist-packages]
cmd = "python -m scripts.workspace_poe_tasks clean-dist"

[tool.poe.tasks._clean-dist-meta]
cmd = "rm -rf dist"

[tool.poe.tasks.clean-dist]
help = "Remove generated dist artifacts for -P/--package packages and the root meta package."
sequence = [
    { ref = "_clean-dist-packages --package ${project}" },
    { ref = "_clean-dist-meta" },
]
args = [{ name = "project", default = "*", options = ["-P", "--package"] }]

[tool.poe.tasks._build-packages]
cmd = "python -m scripts.workspace_poe_tasks build"

[tool.poe.tasks._build-meta]
cmd = "uv build"

[tool.poe.tasks.build]
help = "Build -P/--package packages and the root meta package."
sequence = [
    { ref = "_build-packages --package ${project}" },
    { ref = "_build-meta" },
]
args = [{ name = "project", default = "*", options = ["-P", "--package"] }]

[tool.poe.tasks.publish]
help = "Publish built distributions with uv."
cmd = "uv publish"

# Dependency maintenance
[tool.poe.tasks.upgrade-dev-dependency-pins]
help = "Repin exact workspace development dependencies and on-demand tool requirements."
cmd = "python -m scripts.dependencies.upgrade_dev_dependencies"

[tool.poe.tasks._upgrade-lockfile]
cmd = "uv lock --upgrade"

[tool.poe.tasks.upgrade-dev-dependencies]
help = "Repin development dependencies, refresh uv.lock, reinstall, and rerun validation commands."
sequence = [
    { ref = "upgrade-dev-dependency-pins" },
    { ref = "_upgrade-lockfile" },
    { ref = "install" },
    { ref = "check" },
    { ref = "typing" },
]

[tool.poe.tasks.add-dependency-to-project]
help = "Add a dependency to a -P/--package workspace package selected by short name such as `core`."
cmd = "python -m scripts.dependencies.add_dependency_to_project --package ${project} --dependency ${dependency}"
args = [
    { name = "project", options = ["-P", "--package"] },
    { name = "dependency", options = ["-D", "-d", "--dependency"] },
]

[tool.poe.tasks.validate-dependency-bounds-test]
help = "Run the exhaustive workspace dependency-bound test+typing matrix, optionally scoped with -P/--package short names such as `core`."
shell = "python -m scripts.dependencies.validate_dependency_bounds --mode test --package \"$project\""
args = [{ name = "project", default = "*", options = ["-P", "--package"] }]

[tool.poe.tasks.validate-python-release]
help = "Refresh uv.lock, then run lower/upper import probes for changed package metadata on each package closure's minimum Python."
executor = "simple"
shell = """
command=(
  python -m scripts.dependencies.validate_dependency_bounds
  --mode release
  --base-ref "${base_ref}"
  --release-timeout-seconds "${timeout}"
)
if [ -n "${python}" ]; then
  command+=(--python "${python}")
fi
"${command[@]}"
"""
interpreter = "bash"
args = [
    { name = "base_ref", options = ["-B", "--base-ref"] },
    { name = "python", default = "", options = ["--python"] },
    { name = "timeout", default = "300", options = ["--timeout-seconds"] },
]

[tool.poe.tasks.validate-dependency-bounds-project]
help = "Validate lower and upper dependency bounds for a -P/--package workspace package, optionally narrowed with -M/--mode and -D/--dependency."
shell = """
command=(
    python -m scripts.dependencies.validate_dependency_bounds
    --mode "${mode}"
    --package "${project}"
)
if [ -n "${dependency}" ]; then
    command+=(--dependencies "${dependency}")
fi
"${command[@]}"
"""
interpreter = "bash"
args = [
    { name = "mode", default = "both", options = ["-M", "-m", "--mode"] },
    { name = "project", default = "*", options = ["-P", "--package"] },
    { name = "dependency", default = "", options = ["-D", "-d", "--dependency"] },
]

[tool.poe.tasks.add-dependency-and-validate-bounds]
help = "Add a dependency to a -P/--package workspace package selected by short name such as `core`, then validate its dependency bounds with -D/--dependency."
sequence = [
    { ref = "add-dependency-to-project --package ${project} --dependency ${dependency}" },
    { ref = "validate-dependency-bounds-project --mode both --package ${project} --dependency ${dependency}" },
]
args = [
    { name = "project", options = ["-P", "--package"] },
    { name = "dependency", options = ["-D", "-d", "--dependency"] },
]

[tool.setuptools.packages.find]
where = ["packages"]
include = ["agent_framework**"]
namespaces = true

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
publish-url = "https://test.pypi.org/legacy/"
explicit = true

[tool.flit.module]
name = "agent_framework_meta"

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