microsoft--agent-framework/python/AGENTS.md

AGENTS.md

Instructions for AI coding agents working in the Python codebase.

Key Documentation:

• DEV_SETUP.md - Development environment setup and available poe tasks
• CODING_STANDARD.md - Coding standards, docstring format, and performance guidelines
• samples/SAMPLE_GUIDELINES.md - Sample structure and guidelines
• Python function-calling loop specification - Required behavior, scenario-to-test mapping, coverage gaps, and extra validation for function-loop changes

Agent Skills (.github/skills/) — detailed, task-specific instructions loaded on demand:

• python-development — coding standards, type annotations, docstrings, logging, performance
• python-testing — test structure, fixtures, async mode, running tests
• python-code-quality — linting, formatting, type checking, prek hooks, CI workflow
• python-feature-lifecycle — package vs feature lifecycle stages, decorators, enums, and promotion guidance
• python-package-management — monorepo structure, lazy loading, versioning, new packages
• pull-requests — writing PR descriptions (template) and handling/resolving PR review comments
• agent-framework-py-release — Python release PR workflow, CHANGELOG-driven package bumps, lifecycle version rules, and dependency-floor validation

Maintaining Documentation

When making changes to a package, check if the following need updates:

• The package's AGENTS.md file (adding/removing/renaming public APIs, architecture changes, import path changes)
• The agent skills in .github/skills/ if conventions, commands, or workflows change

At the end of every run, re-read AGENTS.md and the relevant skill files and update any guidance that the conversation revealed to be out of date, incomplete, or misleading (renamed files, changed commands, new conventions the user confirmed, etc.). Before adding a new principle or rule, ask the user whether they want it captured as a durable principle — do not invent team norms from a single conversation without explicit confirmation.

Terminology

• Avoid "GA" for Agent Framework code. Reserve GA for hosted services (e.g. "the Foundry service is GA"). For Agent Framework packages, features, and APIs use "released" or "stable" depending on context — these match the feature-lifecycle stages documented in the python-feature-lifecycle skill.

Changelog Ownership

• Individual feature, fix, documentation, and dependency PRs must not update python/CHANGELOG.md.
• CHANGELOG entries and release sections are assembled centrally during the Python release-preparation workflow.

Pull Request Description Guidance

When preparing a PR description:

• Follow the repository PR template at .github/pull_request_template.md and keep its structure/headings.
• Describe the net change relative to main (this is implied; do not call it out explicitly as "vs main").
• Do not add ad-hoc validation sections (for example, "Validation" or "Tests run"); CI/CD and the template checklist cover validation status.

Quick Reference

Run uv run poe from the python/ directory to see available commands. See DEV_SETUP.md for detailed usage.

Function-Calling Loop Changes

Changes to the Python function-calling loop, approval resume behavior, function-call history, provider serialization, or transport result handling must follow the function-calling loop specification. This area requires extra validation because small changes can duplicate side effects, orphan call/result pairs, replay stale approval authority, or make streaming and non-streaming behavior diverge. Update the specification and its scenario-to-test mapping whenever coverage or behavior changes. External contributors must check with the Agent Framework core team before picking up issues in this area.

Project Structure

python/
├── packages/
│   ├── core/                 # agent-framework-core (main package)
│   │   ├── agent_framework/  # Public API exports
│   │   └── tests/
│   ├── foundry/              # agent-framework-foundry
│   ├── anthropic/            # agent-framework-anthropic
│   ├── ollama/               # agent-framework-ollama
│   └── ...                   # Other provider packages
├── samples/                  # Sample code and examples
├── .github/skills/           # Agent skills for Copilot
└── tests/                    # Integration tests

Package Relationships

• agent-framework-core contains core abstractions and OpenAI/Azure OpenAI built-in
• Provider packages (foundry, anthropic, etc.) extend core with specific integrations
• The root agent_framework public API is lazy-loaded from packages/core/agent_framework/__init__.py and described for type checkers in packages/core/agent_framework/__init__.pyi; keep both plus __all__ in sync.
• Core uses lazy loading via __getattr__ in provider folders (e.g., agent_framework/azure/)

Package Documentation

Core

• core - Core abstractions, types, and built-in OpenAI/Azure OpenAI support

LLM Providers

• anthropic - Anthropic Claude API
• bedrock - AWS Bedrock
• claude - Claude Agent SDK
• foundry_local - Microsoft Foundry Local
• ollama - Local Ollama inference

Azure Integrations

• foundry - Microsoft Foundry chat, agent, memory, and embedding integrations
• azure-contentunderstanding - Azure Content Understanding context provider
• azure-ai-search - Azure AI Search RAG
• azure-cosmos - Azure Cosmos DB-backed history provider
• azurefunctions - Azure Functions hosting

Protocols & UI

• a2a - Agent-to-Agent protocol
• hosting-a2a - A2A hosting conversion helpers
• hosting-mcp - MCP hosting conversion helpers
• ag-ui - AG-UI protocol
• chatkit - OpenAI ChatKit integration
• devui - Developer UI for testing

Storage & Memory

• mem0 - Mem0 memory integration
• redis - Redis storage

Infrastructure

• copilotstudio - Microsoft Copilot Studio
• declarative - YAML/JSON agent definitions
• durabletask - Durable execution
• github_copilot - GitHub Copilot extensions
• purview - Data governance

Experimental

• lab - Experimental features
• monty - Monty-backed CodeAct integrations (alpha)