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

Maintaining Documentation

When making changes to a package, check if the package's AGENTS.md file needs updates. This includes:

• Adding/removing/renaming public classes or functions
• Changing the package's purpose or architecture
• Modifying import paths or usage patterns

Quick Reference

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

Project Structure

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

Package Relationships

• agent-framework-core contains core abstractions and OpenAI/Azure OpenAI built-in
• Provider packages (azure-ai, anthropic, etc.) extend core with specific integrations
• Core uses lazy loading via __getattr__ in provider folders (e.g., agent_framework/azure/)

Import Patterns

# Core imports
from agent_framework import ChatAgent, ChatMessage, tool

# Provider imports (lazy-loaded)
from agent_framework.openai import OpenAIChatClient
from agent_framework.azure import AzureOpenAIChatClient, AzureAIAgentClient

Key Conventions

• Copyright: # Copyright (c) Microsoft. All rights reserved. at top of all .py files
• Types: Always specify return types and parameter types; use Type | None not Optional
• Logging: from agent_framework import get_logger (never import logging)
• Docstrings: Google-style for public APIs
• Tests: Do not use @pytest.mark.asyncio (auto mode enabled); run only related tests, not the entire suite
• Line length: 120 characters
• Comments: Avoid excessive comments; prefer clear code
• Formatting: Format only files you changed, not the entire codebase

Sample Structure

1. Copyright header: # Copyright (c) Microsoft. All rights reserved.
2. Required imports
3. Module docstring: """This sample demonstrates..."""
4. Helper functions
5. Main function(s) demonstrating functionality
6. Entry point: if __name__ == "__main__": asyncio.run(main())

When modifying samples, update associated README files in the same or parent folders.

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 - Azure AI Foundry Local
• ollama - Local Ollama inference

Azure Integrations

• azure-ai - Azure AI Foundry agents
• azure-ai-search - Azure AI Search RAG
• azurefunctions - Azure Functions hosting

Protocols & UI

• a2a - Agent-to-Agent protocol
• 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