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
• 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

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.

• 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.

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.

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

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

• 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/)

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

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

• 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

• 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

• mem0 - Mem0 memory integration
• redis - Redis storage

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

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