Python Development

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:

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:

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

# Core
from agent_framework import Agent, Message, tool

# Components
from agent_framework.observability import enable_instrumentation

# Connectors (lazy-loaded)
from agent_framework.openai import OpenAIChatClient
from agent_framework.foundry import FoundryChatClient

Public API and Exports

In __init__.py files that define package-level public APIs, use direct re-export imports plus an explicit __all__. Avoid identity aliases like from ._agents import Agent as Agent, and avoid from module import *.

Do not define __all__ in internal non-__init__.py modules. Exception: modules intentionally exposed as a public import surface (for example, agent_framework.observability) should define __all__.

__all__ = ["Agent", "Message", "ChatResponse"]

from ._agents import Agent
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