mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00

Files

T

Eduard van Valkenburg 977c3adfb2 Python: replace pre-commit with prek, add PEP 723 script deps, clean up dev dependencies (#3748 )

* python: replace pre-commit with prek, add PEP 723 script deps, clean up dev dependencies

- Replace pre-commit with prek (Rust-native, faster pre-commit alternative)
- Move supported hooks to repo: builtin for zero-clone speed
- Add new builtin hooks: trailing-whitespace, check-merge-conflict, detect-private-key, check-added-large-files
- Update all hook versions to latest (pre-commit-hooks v6, pyupgrade v3.21.2, bandit 1.9.3, uv-pre-commit 0.10.0)
- Add PEP 723 inline script metadata to 34 samples with external deps
- Remove autogen-agentchat/autogen-ext from dev deps (now declared per-sample)
- Remove unused dev deps: pytest-env, tomli-w
- Add agent-framework-core>=1.0.0b260130 lower bound to all 21 packages
- Update CI workflow to use j178/prek-action
- Update docs: DEV_SETUP.md, AGENTS.md, CODING_STANDARD.md, SAMPLE_GUIDELINES.md

* updated lock

* python: fix prek config paths for local execution and CI workflow

Remove global 'files: ^python/' filter and strip python/ prefix from all path patterns in .pre-commit-config.yaml so prek finds files when run from the python/ directory. Update CI workflow to use --cd python instead of --config path. Include trailing whitespace fixes and dev dependency cleanup.

* python: move helper scripts to scripts/ folder and exclude from checks

* python: exclude AGENTS.md from prek markdown code lint

* python: exclude AGENTS.md and azure_ai_search sample from markdown lint

* fix m365 sample

* python: ignore CPY rule for samples with PEP 723 headers

* fix in dev_setup

* python: replace aiofiles with regular open in samples

* python: suppress reportUnusedImport in markdown code block checker

* python: use samples pyright config for markdown code block checker

Write a temp pyrightconfig.json matching pyrightconfig.samples.json rules (typeCheckingMode=off, only reportMissingImports and reportAttributeAccessIssue). Filter output to only fail on these rules since syntax-level errors (top-level await, undefined vars) are expected in README documentation snippets.

* python: use markdown-code-lint with fixed globs instead of prek file list

The prek-markdown-code-lint task received all changed files including non-README markdown and files with pre-existing broken imports. Replace with the standard markdown-code-lint task which uses the correct glob patterns (README.md, packages/**/README.md, samples/**/*.md).

* python: exclude READMEs with pre-existing broken imports from markdown lint

* python: fix broken README code snippets instead of excluding them

- ag-ui: replace TextContent (removed) with content.type == 'text'
- durabletask: fix import path to durabletask.worker.TaskHubGrpcWorker
- orchestrations: use constructor params instead of .participants() method
- observability: mark deprecated code blocks as plain text, filter
  reportMissingImports to agent_framework modules only
- remove README excludes from markdown-code-lint task

* add revision to gaia download

* feat(python): parallelize checks across packages

Run (package × task) cross-product in parallel using ThreadPoolExecutor
and subprocesses. Key changes:

- Add scripts/task_runner.py with shared parallel execution engine
- Update run_tasks_in_packages_if_exists.py to accept multiple tasks
- Update run_tasks_in_changed_packages.py with --files flag and parallel support
- Add check-packages poe task (fmt+lint+pyright+mypy in parallel)
- Add prek-markdown-code-lint and prek-samples-check with change detection
- Split CI code quality workflow into parallel prek and mypy jobs
- Update DEV_SETUP.md to document new parallel behavior

Core package changes still trigger checks on all packages.

* feat(ci): split code quality into 4 parallel jobs

Split the single prek job into parallel jobs:
- pre-commit-hooks: lightweight hooks (SKIP=poe-check)
- package-checks: fmt/lint/pyright/mypy via check-packages
- samples-markdown: samples-lint, samples-syntax, markdown-code-lint
- mypy: change-detected mypy checks

All 4 jobs run concurrently (×2 Python versions = 8 runners).

* feat(ci): use only Python 3.10 for code quality checks

* refactor(python): add future annotations and remove quoted types

Add `from __future__ import annotations` to 93 package files that
used quoted string annotations, then run pyupgrade --py310-plus to
remove the now-unnecessary quotes.

Fixes https://github.com/microsoft/agent-framework/issues/3578

2026-02-09 17:51:01 +00:00

4.2 KiB

Raw Blame History

AGENTS.md

Instructions for AI coding agents working in the Python codebase.

Key Documentation:

DEV_SETUP.md - Development environment setup and available poe tasks
CODING_STANDARD.md - Coding standards, docstring format, and performance guidelines

Maintaining Documentation

When making changes to a package, check if the package's AGENTS.md file needs updates. This includes:

Adding/removing/renaming public classes or functions
Changing the package's purpose or architecture
Modifying import paths or usage patterns

Quick Reference

Run uv run poe from the python/ directory to see available commands. See DEV_SETUP.md for detailed usage.

Project Structure

python/
├── packages/
│   ├── core/                 # agent-framework-core (main package)
│   │   ├── agent_framework/  # Public API exports
│   │   └── tests/
│   ├── azure-ai/             # agent-framework-azure-ai
│   ├── anthropic/            # agent-framework-anthropic
│   ├── ollama/               # agent-framework-ollama
│   └── ...                   # Other provider packages
├── samples/                  # Sample code and examples
└── tests/                    # Integration tests

Package Relationships

agent-framework-core contains core abstractions and OpenAI/Azure OpenAI built-in
Provider packages (azure-ai, anthropic, etc.) extend core with specific integrations
Core uses lazy loading via __getattr__ in provider folders (e.g., agent_framework/azure/)

Import Patterns

# Core imports
from agent_framework import ChatAgent, ChatMessage, tool

# Provider imports (lazy-loaded)
from agent_framework.openai import OpenAIChatClient
from agent_framework.azure import AzureOpenAIChatClient, AzureAIAgentClient

Key Conventions

Copyright: # Copyright (c) Microsoft. All rights reserved. at top of all .py files
Types: Always specify return types and parameter types; use Type | None not Optional
Logging: from agent_framework import get_logger (never import logging)
Docstrings: Google-style for public APIs
Tests: Do not use @pytest.mark.asyncio (auto mode enabled); run only related tests, not the entire suite
Line length: 120 characters
Comments: Avoid excessive comments; prefer clear code
Formatting: Format only files you changed, not the entire codebase

Samples

See samples/SAMPLE_GUIDELINES.md for sample structure, external dependency handling (PEP 723), and syntax checking instructions.

Package Documentation

Core

core - Core abstractions, types, and built-in OpenAI/Azure OpenAI support

LLM Providers

anthropic - Anthropic Claude API
bedrock - AWS Bedrock
claude - Claude Agent SDK
foundry_local - Azure AI Foundry Local
ollama - Local Ollama inference

Azure Integrations

azure-ai - Azure AI Foundry agents
azure-ai-search - Azure AI Search RAG
azurefunctions - Azure Functions hosting

Protocols & UI

a2a - Agent-to-Agent protocol
ag-ui - AG-UI protocol
chatkit - OpenAI ChatKit integration
devui - Developer UI for testing

Storage & Memory

mem0 - Mem0 memory integration
redis - Redis storage

Infrastructure

copilotstudio - Microsoft Copilot Studio
declarative - YAML/JSON agent definitions
durabletask - Durable execution
github_copilot - GitHub Copilot extensions
purview - Data governance

Experimental

lab - Experimental features

4.2 KiB Raw Blame History