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

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
• python-samples — sample file structure, PEP 723, documentation guidelines

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

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.

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

Azure Integrations

• foundry - Microsoft Foundry chat, agent, memory, and embedding integrations
• 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
• 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