mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Eduard van Valkenburg
977c3adfb2
* 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
104 lines
4.2 KiB
Markdown
104 lines
4.2 KiB
Markdown
# AGENTS.md
|
|
|
|
Instructions for AI coding agents working in the Python codebase.
|
|
|
|
**Key Documentation:**
|
|
- [DEV_SETUP.md](DEV_SETUP.md) - Development environment setup and available poe tasks
|
|
- [CODING_STANDARD.md](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](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
|
|
|
|
```python
|
|
# 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](samples/SAMPLE_GUIDELINES.md) for sample structure, external dependency handling (PEP 723), and syntax checking instructions.
|
|
|
|
## Package Documentation
|
|
|
|
### Core
|
|
- [core](packages/core/AGENTS.md) - Core abstractions, types, and built-in OpenAI/Azure OpenAI support
|
|
|
|
### LLM Providers
|
|
- [anthropic](packages/anthropic/AGENTS.md) - Anthropic Claude API
|
|
- [bedrock](packages/bedrock/AGENTS.md) - AWS Bedrock
|
|
- [claude](packages/claude/AGENTS.md) - Claude Agent SDK
|
|
- [foundry_local](packages/foundry_local/AGENTS.md) - Azure AI Foundry Local
|
|
- [ollama](packages/ollama/AGENTS.md) - Local Ollama inference
|
|
|
|
### Azure Integrations
|
|
- [azure-ai](packages/azure-ai/AGENTS.md) - Azure AI Foundry agents
|
|
- [azure-ai-search](packages/azure-ai-search/AGENTS.md) - Azure AI Search RAG
|
|
- [azurefunctions](packages/azurefunctions/AGENTS.md) - Azure Functions hosting
|
|
|
|
### Protocols & UI
|
|
- [a2a](packages/a2a/AGENTS.md) - Agent-to-Agent protocol
|
|
- [ag-ui](packages/ag-ui/AGENTS.md) - AG-UI protocol
|
|
- [chatkit](packages/chatkit/AGENTS.md) - OpenAI ChatKit integration
|
|
- [devui](packages/devui/AGENTS.md) - Developer UI for testing
|
|
|
|
### Storage & Memory
|
|
- [mem0](packages/mem0/AGENTS.md) - Mem0 memory integration
|
|
- [redis](packages/redis/AGENTS.md) - Redis storage
|
|
|
|
### Infrastructure
|
|
- [copilotstudio](packages/copilotstudio/AGENTS.md) - Microsoft Copilot Studio
|
|
- [declarative](packages/declarative/AGENTS.md) - YAML/JSON agent definitions
|
|
- [durabletask](packages/durabletask/AGENTS.md) - Durable execution
|
|
- [github_copilot](packages/github_copilot/AGENTS.md) - GitHub Copilot extensions
|
|
- [purview](packages/purview/AGENTS.md) - Data governance
|
|
|
|
### Experimental
|
|
- [lab](packages/lab/AGENTS.md) - Experimental features
|