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
+77
@@ -0,0 +1,77 @@
|
||||
---
|
||||
name: python-samples
|
||||
description: >
|
||||
Guidelines for creating and modifying sample code in the Agent Framework
|
||||
Python codebase. Use this when writing new samples or updating existing ones.
|
||||
---
|
||||
|
||||
# Python Samples
|
||||
|
||||
## File Structure
|
||||
|
||||
Every sample file follows this order:
|
||||
|
||||
1. PEP 723 inline script metadata (if external dependencies needed)
|
||||
2. Copyright header: `# Copyright (c) Microsoft. All rights reserved.`
|
||||
3. Required imports
|
||||
4. Module docstring: `"""This sample demonstrates..."""`
|
||||
5. Helper functions
|
||||
6. Main function(s) demonstrating functionality
|
||||
7. Entry point: `if __name__ == "__main__": asyncio.run(main())`
|
||||
|
||||
## External Dependencies
|
||||
|
||||
Use [PEP 723](https://peps.python.org/pep-0723/) inline script metadata for
|
||||
external packages not in the dev environment:
|
||||
|
||||
```python
|
||||
# /// script
|
||||
# requires-python = ">=3.10"
|
||||
# dependencies = [
|
||||
# "some-external-package",
|
||||
# ]
|
||||
# ///
|
||||
# Run with: uv run samples/path/to/script.py
|
||||
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
```
|
||||
|
||||
Do **not** add sample-only dependencies to the root `pyproject.toml` dev group.
|
||||
|
||||
## Syntax Checking
|
||||
|
||||
```bash
|
||||
# Check samples for syntax errors and missing imports
|
||||
uv run poe samples-syntax
|
||||
|
||||
# Lint samples
|
||||
uv run poe samples-lint
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
Samples should be over-documented:
|
||||
|
||||
1. Include a README.md in each set of samples
|
||||
2. Add a summary docstring under imports explaining the purpose and key components
|
||||
3. Mark code sections with numbered comments:
|
||||
```python
|
||||
# 1. Create the client instance.
|
||||
...
|
||||
# 2. Create the agent with the client.
|
||||
...
|
||||
```
|
||||
4. Include expected output at the end of the file:
|
||||
```python
|
||||
"""
|
||||
Sample output:
|
||||
User:> Why is the sky blue?
|
||||
Assistant:> The sky is blue due to Rayleigh scattering...
|
||||
"""
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Incremental complexity** — start simple, build up (step1, step2, ...)
|
||||
- **Getting started naming**: `step<number>_<name>.py`
|
||||
- When modifying samples, update associated README files
|
||||
Reference in New Issue
Block a user