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
116 lines
6.2 KiB
Markdown
116 lines
6.2 KiB
Markdown
# Sample Guidelines
|
|
|
|
Samples are extremely important for developers to get started with Agent Framework. We strive to provide a wide range of samples that demonstrate the capabilities of Agent Framework with consistency and quality. This document outlines the guidelines for creating samples.
|
|
|
|
## File Structure
|
|
|
|
Every sample file should follow this order:
|
|
|
|
1. PEP 723 inline script metadata (if external dependencies are 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())`
|
|
|
|
When modifying samples, update associated README files in the same or parent folders.
|
|
|
|
## External Dependencies
|
|
|
|
When samples depend on external packages not included in the dev environment (e.g., `semantic-kernel`, `autogen-agentchat`, `pandas`), declare them using [PEP 723](https://peps.python.org/pep-0723/) inline script metadata at the top of the file, before the copyright header:
|
|
|
|
```python
|
|
# /// script
|
|
# requires-python = ">=3.10"
|
|
# dependencies = [
|
|
# "some-external-package",
|
|
# ]
|
|
# ///
|
|
# Run with any PEP 723 compatible runner, e.g.:
|
|
# uv run samples/path/to/script.py
|
|
|
|
# Copyright (c) Microsoft. All rights reserved.
|
|
```
|
|
|
|
This makes samples self-contained and runnable without installing extra packages into the dev environment. Do not add sample-only dependencies to the root `pyproject.toml` dev group.
|
|
|
|
## Syntax Checking
|
|
|
|
Run `uv run poe samples-syntax` to check samples for syntax errors and missing imports from `agent_framework`. This uses a relaxed pyright configuration that validates imports without strict type checking.
|
|
|
|
Some samples depend on external packages (e.g., `azure.ai.agentserver.agentframework`, `microsoft_agents`) that are not installed in the dev environment. These are excluded in `pyrightconfig.samples.json`. When adding or modifying these excluded samples, add them to the exclude list and manually verify they have no import errors from `agent_framework` packages by temporarily removing them from the exclude list and running the check.
|
|
|
|
## General Guidelines
|
|
|
|
- **Clear and Concise**: Samples should be clear and concise. They should demonstrate a specific set of features or capabilities of Agent Framework. The less concepts a sample demonstrates, the better.
|
|
- **Consistent Structure**: All samples should have a consistent structure. This includes the folder structure, file naming, and the content of the sample.
|
|
- **Incremental Complexity**: Samples should start simple and gradually increase in complexity. This helps developers understand the concepts and features of Agent Framework.
|
|
- **Documentation**: Samples should be over-documented.
|
|
|
|
### **Clear and Concise**
|
|
|
|
Try not to include too many concepts in a single sample. The goal is to demonstrate a specific feature or capability of Agent Framework. If you find yourself including too many concepts, consider breaking the sample into multiple samples. A good example of this is to break non-streaming and streaming modes into separate samples.
|
|
|
|
### **Consistent Structure**
|
|
|
|
! TODO: Update folder structure to our new needs.
|
|
! TODO: Decide on single samples folder or also samples in extensions
|
|
|
|
#### Getting Started Samples
|
|
|
|
The getting started samples are the simplest samples that require minimal setup. These samples should be named in the following format: `step<number>_<name>.py`. One exception to this rule is when the sample is a notebook, in which case the sample should be named in the following format: `<number>_<name>.ipynb`.
|
|
|
|
### **Incremental Complexity**
|
|
|
|
Try to do a best effort to make sure that the samples are incremental in complexity. For example, in the getting started samples, each step should build on the previous step, and the concept samples should build on the getting started samples, same with the demos.
|
|
|
|
### **Documentation**
|
|
|
|
Try to over-document the samples. This includes comments in the code, README.md files, and any other documentation that is necessary to understand the sample. We use the guidance from [PEP8](https://peps.python.org/pep-0008/#comments) for comments in the code, with a deviation for the initial summary comment in samples and the output of the samples.
|
|
|
|
For the getting started samples and the concept samples, we should have the following:
|
|
|
|
1. A README.md file is included in each set of samples that explains the purpose of the samples and the setup required to run them.
|
|
2. A summary should be included underneath the imports that explains the purpose of the sample and required components/concepts to understand the sample. For example:
|
|
|
|
```python
|
|
'''
|
|
This sample shows how to create a chatbot. This sample uses the following two main components:
|
|
- a ChatCompletionService: This component is responsible for generating responses to user messages.
|
|
- a ChatHistory: This component is responsible for keeping track of the chat history.
|
|
The chatbot in this sample is called Mosscap, who responds to user messages with long flowery prose.
|
|
'''
|
|
```
|
|
|
|
3. Mark the code with comments to explain the purpose of each section of the code. For example:
|
|
|
|
```python
|
|
# 1. Create the instance of the Kernel to register the plugin and service.
|
|
...
|
|
|
|
# 2. Create the agent with the kernel instance.
|
|
...
|
|
```
|
|
|
|
> This will also allow the sample creator to track if the sample is getting too complex.
|
|
|
|
4. At the end of the sample, include a section that explains the expected output of the sample. For example:
|
|
|
|
```python
|
|
'''
|
|
Sample output:
|
|
User:> Why is the sky blue in one sentence?
|
|
Mosscap:> The sky is blue due to the scattering of sunlight by the molecules in the Earth's atmosphere,
|
|
a phenomenon known as Rayleigh scattering, which causes shorter blue wavelengths to become more
|
|
prominent in our visual perception.
|
|
'''
|
|
```
|
|
|
|
For the demos, a README.md file must be included that explains the purpose of the demo and how to run it. The README.md file should include the following:
|
|
|
|
- A description of the demo.
|
|
- A list of dependencies required to run the demo.
|
|
- Instructions on how to run the demo.
|
|
- Expected output of the demo.
|