mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Eduard van Valkenburg
0521f5bed8
* [BREAKING] Rename ChatAgent -> Agent, ChatMessage -> Message, ChatClientProtocol -> SupportsChatGetResponse Simplify the public API by removing redundant 'Chat' prefix from core types: - ChatAgent -> Agent - RawChatAgent -> RawAgent - ChatMessage -> Message - ChatClientProtocol -> SupportsChatGetResponse Also renamed internal WorkflowMessage (was Message in _runner_context) to avoid collision. No backward compatibility aliases - this is a clean breaking change. * [BREAKING] Rename Agent chat_client parameter to client * Fix rebase issues: WorkflowMessage references and broken markdown links * Fix formatting and lint issues from code quality checks * Fix import ordering in workflow sample files * fixed rebase * Fix test failures: use WorkflowMessage and A2AMessage after ChatMessage→Message rename - Replace Message(data=..., source_id=...) with WorkflowMessage(...) in workflow tests - Fix isinstance check in A2A agent to use A2AMessage instead of Message - Fix import in test_workflow_observability.py (Message→WorkflowMessage) * Fix lint, fmt, and sample errors after ChatMessage→Message rename - Auto-fix 70+ ruff lint issues across samples (ChatMessage→Message refs) - Fix HostedVectorStoreContent→Content.from_hosted_vector_store in file search sample - Fix _normalize_messages→normalize_messages in custom agent sample - Fix context.terminate→raise MiddlewareTermination in middleware samples - Fix with_update_hook→with_transform_hook in override middleware sample - Add TOptions_co import back to custom_chat_client sample - Add noqa for FastAPI File() default in chatkit sample - Fix B023 loop variable capture in weather agent sample * fix: update Agent constructor calls from chat_client to client in declaration-only tool tests * fix: add register_cleanup to devui lazy-loading proxy and type stub * fixed tests and updated new pieces * fix agui typevar * fix merge errors * fix merge conflicts * fiux merge * Remove unused links --------- Co-authored-by: Evan Mattson <evan.mattson@microsoft.com>
110 lines
3.3 KiB
Markdown
110 lines
3.3 KiB
Markdown
---
|
|
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, Message, 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", "Message", "ChatResponse"]
|
|
|
|
from ._agents import ChatAgent
|
|
from ._types import Message, 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
|