Python: Add AGENTS.md files and update coding standards #3644
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add root python/AGENTS.md with project structure and package links - Add AGENTS.md for each package describing purpose and main classes - Update .github/copilot-instructions.md with improved structure - Update python/CODING_STANDARD.md with API review guidance: - Future annotations convention (microsoft#3578) - TypeVar naming convention (microsoft#3594) - Mapping vs MutableMapping (microsoft#3577) - Avoid shadowing built-ins (microsoft#3583) - Explicit exports (microsoft#3605) - Exception documentation guidelines (microsoft#3410) - Simplify python/.github/instructions/python.instructions.md to reference AGENTS.md - Remove AGENTS.md from .gitignore
markwallace-microsoft
added
documentation
Member
Python Test Coverage Report •
Python Unit Test Overview
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a unified documentation surface for AI coding agents (AGENTS.md files) across the Python monorepo and updates coding standards and Copilot instructions to align with recent API review decisions.
Changes:
- Added a root
python/AGENTS.mdand package-levelAGENTS.mdfiles for all Python packages to document purposes, main classes, usage, and import paths. - Updated
python/CODING_STANDARD.mdwith conventions on future annotations, TypeVar naming, mapping types, avoiding built-in shadowing, explicit exports, and exception documentation practices. - Simplified the Python-specific Copilot instructions to point to
AGENTS.md, expanded the repo-wide Copilot instructions with build/test commands and architecture overview, and removedagents.mdfrom.gitignoreso these docs are tracked.
Reviewed changes
Copilot reviewed 25 out of 26 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
.github/copilot-instructions.md |
Replaced language-specific details with a concise repo-wide overview of structure, build/test commands, and key coding conventions for both Python and .NET. |
.gitignore |
Removed agents.md from ignore list to allow AGENTS.md documentation files to be committed. |
python/.github/instructions/python.instructions.md |
Simplified Python Copilot instructions to reference python/AGENTS.md and retain only high-level development guidance. |
python/AGENTS.md |
Added top-level instructions for AI agents working in the Python repo, including project structure, key conventions, sample structure, and links to all package-level AGENTS.md docs. |
python/CODING_STANDARD.md |
Documented conventions for from __future__ import annotations, TypeVar naming (*T suffix), preferring Mapping over MutableMapping for non-mutating parameters, avoiding built-in shadowing, explicit __all__ exports, and clarified when and how to document exceptions. |
python/packages/core/AGENTS.md |
Introduced an overview of the core package layout, key abstractions (agents, clients, types, tools, middleware, threads, memory, workflows), and example usage patterns. |
python/packages/a2a/AGENTS.md |
Documented the A2A package purpose, A2AAgent class, usage snippet, and supported import paths. |
python/packages/ag-ui/AGENTS.md |
Described AG-UI integration types (AGUIChatClient, AGUIHttpService, etc.), request/state types, and FastAPI endpoint helper, with usage and import paths. |
python/packages/anthropic/AGENTS.md |
Documented Anthropic Claude integration (AnthropicClient, AnthropicChatOptions) with usage example and import paths. |
python/packages/azure-ai/AGENTS.md |
Documented Azure AI Foundry agent integrations (AzureAIAgentClient, AzureAIClient, providers, settings/options) with example usage and imports. |
python/packages/azure-ai-search/AGENTS.md |
Described Azure AI Search context provider (AzureAISearchContextProvider, AzureAISearchSettings) and how to wire it into a ChatAgent. |
python/packages/azurefunctions/AGENTS.md |
Documented Azure Functions hosting (AgentFunctionApp) with usage snippet and import paths. |
python/packages/bedrock/AGENTS.md |
Documented AWS Bedrock integration (BedrockChatClient, options, guardrail config, settings) with example usage and direct import path. |
python/packages/chatkit/AGENTS.md |
Described ChatKit integration helpers (ThreadItemConverter, stream_agent_response, simple_to_agent_input) with usage and imports. |
python/packages/claude/AGENTS.md |
Documented Claude Agent SDK integration (ClaudeAgent, options, settings), usage example, and direct import path. |
python/packages/copilotstudio/AGENTS.md |
Documented Microsoft Copilot Studio agent (CopilotStudioAgent) and acquire_token helper, with example usage and import paths via agent_framework.microsoft and the direct package. |
python/packages/declarative/AGENTS.md |
Documented declarative agent/workflow support (AgentFactory, WorkflowFactory, WorkflowState, provider mapping, external input types) with usage and import paths. |
python/packages/devui/AGENTS.md |
Documented DevUI server entry points (serve, DevServer, register_cleanup, CheckpointConversationManager) plus request/response models, CLI usage, and import paths. |
python/packages/durabletask/AGENTS.md |
Described durable agent support (client/worker types, state and callback abstractions) with example client/worker usage and import paths. |
python/packages/foundry_local/AGENTS.md |
Documented Azure AI Foundry Local client (FoundryLocalClient, options, settings) with async usage example and direct import path. |
python/packages/github_copilot/AGENTS.md |
Documented GitHub Copilot agent integration (GitHubCopilotAgent, options, settings), usage example, and imports via agent_framework.github and the direct package. |
python/packages/lab/AGENTS.md |
Added overview of experimental lab subpackages (GAIA, Lightning, Tau2, namespace) with a note on experimental status and separate installation. |
python/packages/mem0/AGENTS.md |
Documented Mem0-based context provider (Mem0Provider), usage pattern, import paths, and telemetry behavior (MEM0_TELEMETRY). |
python/packages/ollama/AGENTS.md |
Documented Ollama client (OllamaChatClient, options, settings) with async usage example and import paths. |
python/packages/purview/AGENTS.md |
Documented Purview middleware, configuration, caching provider, and exception types, with usage and import examples (note: import path issue called out in review). |
python/packages/redis/AGENTS.md |
Documented Redis integration (RedisChatMessageStore, RedisProvider), usage example wiring a ChatAgent, and import paths. |
larohra
approved these changes
Feb 3, 2026
dmytrostruk
approved these changes
Feb 4, 2026
Comment on lines
+17
to
+21
| uv run poe check # Run all checks (format, lint, type check, test) | ||
| uv run poe fmt # Format code with ruff | ||
| uv run poe lint # Lint with ruff | ||
| uv run poe pyright # Type check with pyright | ||
| uv run poe test # Run all tests with coverage |
Member
There was a problem hiding this comment.
We can also specify to avoid running these commands in project root and run for individual projects that were impacted by changes. This can save some time.
| # From dotnet/ directory | ||
| dotnet build # Build all projects | ||
| dotnet test # Run all tests | ||
| dotnet format # Auto-fix formatting |
Member
There was a problem hiding this comment.
Same here, this command is expensive to run for entire solution, it's worth to specify to run it only in projects with changes.
| - `Microsoft.Agents.AI` - Core AI agent abstractions | ||
| - `Microsoft.Agents.AI.<Provider>` - Provider implementations (OpenAI, AzureAI, Anthropic, etc.) | ||
| - `Microsoft.Agents.AI.Workflows` - Workflow orchestration | ||
| - `Microsoft.Extensions.AI.Agents` - Integration with Microsoft.Extensions.AI |
Member
There was a problem hiding this comment.
It doesn't look like package Microsoft.Extensions.AI.Agents exists, I can't find it on NuGet. You should probably specify Microsoft.Extensions.AI and Microsoft.Extensions.AI.Abstractions instead and in description put some type names that are used by Agent Framework, like IChatClient, FunctionInvokingChatClient, AITool, AIContent etc.
| - **Line length**: 120 characters | ||
| - **Async**: Assume async by default; check function signatures | ||
| - **Tests**: Do not mark with `@pytest.mark.asyncio` (auto mode enabled) | ||
| - **Keyword args**: Use for functions with >3 parameters; document `**kwargs` usage |
Member
There was a problem hiding this comment.
Is >3 parameters accurate? I think we don't follow this rule across the codebase unless it's a new rule based on API review.
| - **Async**: Use `Async` suffix for methods returning `Task`/`ValueTask` | ||
| - **Private classes**: Should be `sealed` unless subclassed | ||
| - **Config**: Read from environment variables with `UPPER_SNAKE_CASE` naming | ||
| - **Tests**: Use `this.` for class members; add Arrange/Act/Assert comments; use Moq for mocking |
Member
There was a problem hiding this comment.
Use this. for class members - this is applicable to the entire codebase, not only tests.
| 2. Imports/usings | ||
| 3. Description comment | ||
| 4. Main code logic | ||
| 5. Helper methods at bottom |
Member
There was a problem hiding this comment.
nit: In Python samples we put helper methods at the top.
| - **`AgentMiddleware`** - Intercepts agent `run()` calls | ||
| - **`ChatMiddleware`** - Intercepts chat client `get_response()` calls | ||
| - **`FunctionMiddleware`** - Intercepts function/tool invocations | ||
| - **`AgentRunContext`** / **`ChatContext`** / **`FunctionInvocationContext`** - Context objects passed through middleware |
Member
There was a problem hiding this comment.
This makes me wonder if we should rename AgentRunContext to just AgentContext.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds comprehensive AGENTS.md documentation files for AI coding agents and updates coding standards based on the API review.
Changes
New AGENTS.md Files
Updated Documentation
Other
Related Issues
Parent: #3575
cc @eavanvalkenburg