mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Eduard van Valkenburg
f48c4512d3
* updated automation tasks and commands, with alias for the time being * Restore aggregate test exclusions Preserve the legacy all-tests scope for test --all by excluding lab and devui from the default aggregate sweep, while still allowing explicit package selection. Also ignore hidden/generated test directories such as .mypy_cache during aggregate discovery. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * updated versions in pre-commit --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
81 lines
2.0 KiB
Markdown
81 lines
2.0 KiB
Markdown
---
|
|
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
|
|
# Format + lint samples
|
|
uv run poe syntax -S
|
|
|
|
# Check samples for syntax errors and missing imports
|
|
uv run poe pyright -S
|
|
|
|
# Lint samples only
|
|
uv run poe syntax -S -C
|
|
```
|
|
|
|
## 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
|