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
+109
@@ -0,0 +1,109 @@
|
||||
---
|
||||
name: python-development
|
||||
description: >
|
||||
Coding standards, conventions, and patterns for developing Python code in the
|
||||
Agent Framework repository. Use this when writing or modifying Python source
|
||||
files in the python/ directory.
|
||||
---
|
||||
|
||||
# Python Development Standards
|
||||
|
||||
## File Header
|
||||
|
||||
Every `.py` file must start with:
|
||||
|
||||
```python
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
```
|
||||
|
||||
## Type Annotations
|
||||
|
||||
- Always specify return types and parameter types
|
||||
- Use `Type | None` instead of `Optional[Type]`
|
||||
- Use `from __future__ import annotations` to enable postponed evaluation
|
||||
- Use suffix `T` for TypeVar names: `ChatResponseT = TypeVar("ChatResponseT", bound=ChatResponse)`
|
||||
- Use `Mapping` instead of `MutableMapping` for read-only input parameters
|
||||
- Prefer `# type: ignore[...]` over unnecessary casts, or `isinstance` checks, when these are internally called and executed methods
|
||||
But make sure the ignore is specific for both mypy and pyright so that we don't miss other mistakes
|
||||
|
||||
## Function Parameters
|
||||
|
||||
- Positional parameters: up to 3 fully expected parameters
|
||||
- Use keyword-only arguments (after `*`) for optional parameters
|
||||
- Provide string-based overrides to avoid requiring extra imports:
|
||||
|
||||
```python
|
||||
def create_agent(name: str, tool_mode: Literal['auto', 'required', 'none'] | ChatToolMode) -> Agent:
|
||||
if isinstance(tool_mode, str):
|
||||
tool_mode = ChatToolMode(tool_mode)
|
||||
```
|
||||
|
||||
- Avoid shadowing built-ins (use `next_handler` instead of `next`)
|
||||
- Avoid `**kwargs` unless needed for subclass extensibility; prefer named parameters
|
||||
|
||||
## Docstrings
|
||||
|
||||
Use Google-style docstrings for all public APIs:
|
||||
|
||||
```python
|
||||
def equal(arg1: str, arg2: str) -> bool:
|
||||
"""Compares two strings and returns True if they are the same.
|
||||
|
||||
Args:
|
||||
arg1: The first string to compare.
|
||||
arg2: The second string to compare.
|
||||
|
||||
Returns:
|
||||
True if the strings are the same, False otherwise.
|
||||
|
||||
Raises:
|
||||
ValueError: If one of the strings is empty.
|
||||
"""
|
||||
```
|
||||
|
||||
- Always document Agent Framework specific exceptions
|
||||
- Explicitly use `Keyword Args` when applicable
|
||||
- Only document standard Python exceptions when the condition is non-obvious
|
||||
|
||||
## Import Structure
|
||||
|
||||
```python
|
||||
# Core
|
||||
from agent_framework import ChatAgent, ChatMessage, tool
|
||||
|
||||
# Components
|
||||
from agent_framework.observability import enable_instrumentation
|
||||
|
||||
# Connectors (lazy-loaded)
|
||||
from agent_framework.openai import OpenAIChatClient
|
||||
from agent_framework.azure import AzureOpenAIChatClient
|
||||
```
|
||||
|
||||
## Public API and Exports
|
||||
|
||||
Define `__all__` in each module. Avoid `from module import *` in `__init__.py` files:
|
||||
|
||||
```python
|
||||
__all__ = ["ChatAgent", "ChatMessage", "ChatResponse"]
|
||||
|
||||
from ._agents import ChatAgent
|
||||
from ._types import ChatMessage, ChatResponse
|
||||
```
|
||||
|
||||
## Performance Guidelines
|
||||
|
||||
- Cache expensive computations (e.g., JSON schema generation)
|
||||
- Prefer `match/case` on `.type` attribute over `isinstance()` in hot paths
|
||||
- Avoid redundant serialization — compute once, reuse
|
||||
|
||||
## Style
|
||||
|
||||
- Line length: 120 characters
|
||||
- Format only files you changed, not the entire codebase
|
||||
- Prefer attributes over inheritance when parameters are mostly the same
|
||||
- Async by default — assume everything is asynchronous
|
||||
|
||||
## Naming Conventions for Connectors
|
||||
|
||||
- `_prepare_<object>_for_<purpose>` for methods that prepare data for external services
|
||||
- `_parse_<object>_from_<source>` for methods that process data from external services
|
||||
Reference in New Issue
Block a user