mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
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
This commit is contained in:
committed by
GitHub
Unverified
parent
56603ab472
commit
8ad66637d8
@@ -0,0 +1,103 @@
|
||||
---
|
||||
name: python-package-management
|
||||
description: >
|
||||
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](https://github.com/astral-sh/uv) for dependency management and
|
||||
[poethepoet](https://github.com/nat-n/poethepoet) for task automation.
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```python
|
||||
# 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)
|
||||
|
||||
1. Create directory under `packages/` (e.g., `packages/my-connector/`)
|
||||
2. Add the package to `tool.uv.sources` in root `pyproject.toml`
|
||||
3. Include samples inside the package (e.g., `packages/my-connector/samples/`)
|
||||
4. Do **NOT** add to `[all]` extra in `packages/core/pyproject.toml`
|
||||
5. Do **NOT** create lazy loading in core yet
|
||||
|
||||
### Promotion to Stable
|
||||
|
||||
1. Move samples to root `samples/` folder
|
||||
2. Add to `[all]` extra in `packages/core/pyproject.toml`
|
||||
3. 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
|
||||
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user