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

Files

T

Eduard van Valkenburg 8ad66637d8 Python: Fix prek runner duplication and add skills (#3791 )

* Python: fix prek runner running fmt/lint in all packages on core change

When a core package file changed, run_tasks_in_changed_packages.py ran
fmt, lint, and pyright in ALL 22 packages (66 tasks). Only type-checking
tasks (pyright, mypy) need to propagate to all packages since type
changes in core affect downstream packages. File-local tasks (fmt, lint)
only need to run in packages with actual file changes.

This reduces a core-only change from 66 tasks to 24 tasks (2 local +
22 pyright).

Also adds no-commit-to-branch builtin hook to protect the main branch
from direct commits.

* Python: add agent skills extracted from AGENTS.md and coding standards

Add 5 skills to python/.github/skills/ following the Agent Skills format:
- python-development: coding standards, type annotations, docstrings, logging
- python-testing: test structure, fixtures, running tests, async mode
- python-code-quality: linting, formatting, type checking, prek hooks, CI
- python-package-management: monorepo structure, lazy loading, versioning
- python-samples: sample structure, PEP 723, documentation guidelines

* Python: deduplicate AGENTS.md and instructions with agent skills

* updated skills

* fixes from review

* Python: increase timeout for web search integration test

2026-02-10 12:13:38 +00:00

3.4 KiB

Raw Blame History

name, description

name	description
python-package-management	Guide for managing packages in the Agent Framework Python monorepo, including creating new connector packages, versioning, and the lazy-loading pattern. Use this when adding, modifying, or releasing packages.

Python Package Management

Monorepo Structure

python/
├── pyproject.toml              # Root package (agent-framework)
├── packages/
│   ├── core/                   # agent-framework-core (main package)
│   ├── azure-ai/               # agent-framework-azure-ai
│   ├── anthropic/              # agent-framework-anthropic
│   └── ...                     # Other connector packages

agent-framework-core contains core abstractions and OpenAI/Azure OpenAI built-in
Provider packages extend core with specific integrations
Root agent-framework depends on agent-framework-core[all]

Dependency Management

Uses uv for dependency management and poethepoet for task automation.

# Full setup (venv + install + prek hooks)
uv run poe setup

# Install/update all dependencies
uv run poe install

# Create venv with specific Python version
uv run poe venv --python 3.12

Lazy Loading Pattern

Provider folders in core use __getattr__ to lazy load from connector packages:

# In agent_framework/azure/__init__.py
_IMPORTS: dict[str, tuple[str, str]] = {
    "AzureAIAgentClient": ("agent_framework_azure_ai", "agent-framework-azure-ai"),
}

def __getattr__(name: str) -> Any:
    if name in _IMPORTS:
        import_path, package_name = _IMPORTS[name]
        try:
            return getattr(importlib.import_module(import_path), name)
        except ModuleNotFoundError as exc:
            raise ModuleNotFoundError(
                f"The package {package_name} is required to use `{name}`. "
                f"Install it with: pip install {package_name}"
            ) from exc

Adding a New Connector Package

Important: Do not create a new package unless approved by the core team.

Initial Release (Preview)

Create directory under packages/ (e.g., packages/my-connector/)
Add the package to tool.uv.sources in root pyproject.toml
Include samples inside the package (e.g., packages/my-connector/samples/)
Do NOT add to [all] extra in packages/core/pyproject.toml
Do NOT create lazy loading in core yet

Promotion to Stable

Move samples to root samples/ folder
Add to [all] extra in packages/core/pyproject.toml
Create provider folder in agent_framework/ with lazy loading __init__.py

Versioning

All non-core packages declare a lower bound on agent-framework-core
When core version bumps with breaking changes, update the lower bound in all packages
Non-core packages version independently; only raise core bound when using new core APIs

Installation Options

pip install agent-framework-core          # Core only
pip install agent-framework-core[all]     # Core + all connectors
pip install agent-framework               # Same as core[all]
pip install agent-framework-azure-ai      # Specific connector (pulls in core)

Maintaining Documentation

When changing a package, check if its AGENTS.md needs updates:

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

3.4 KiB Raw Blame History