Skip to content

Commit 14db7f0

Browse files
Add AGENTS.md files and update coding standards for Python
- 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
1 parent 6fdf611 commit 14db7f0

26 files changed

Lines changed: 1026 additions & 95 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 99 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,101 @@
11
# GitHub Copilot Instructions
22

3-
This repository contains both Python and C# code.
4-
All python code resides under the `python/` directory.
5-
All C# code resides under the `dotnet/` directory.
6-
7-
The purpose of the code is to provide a framework for building AI agents.
8-
9-
When contributing to this repository, please follow these guidelines:
10-
11-
## C# Code Guidelines
12-
13-
Here are some general guidelines that apply to all code.
14-
15-
- The top of all *.cs files should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.`
16-
- All public methods and classes should have XML documentation comments.
17-
- After adding, modifying or deleting code, run `dotnet build`, and then fix any reported build errors.
18-
- After adding or modifying code, run `dotnet format` to automatically fix any formatting errors.
19-
20-
### C# Sample Code Guidelines
21-
22-
Sample code is located in the `dotnet/samples` directory.
23-
24-
When adding a new sample, follow these steps:
25-
26-
- The sample should be a standalone .net project in one of the subdirectories of the samples directory.
27-
- The directory name should be the same as the project name.
28-
- The directory should contain a README.md file that explains what the sample does and how to run it.
29-
- The README.md file should follow the same format as other samples.
30-
- The csproj file should match the directory name.
31-
- The csproj file should be configured in the same way as other samples.
32-
- The project should preferably contain a single Program.cs file that contains all the sample code.
33-
- The sample should be added to the solution file in the samples directory.
34-
- The sample should be tested to ensure it works as expected.
35-
- A reference to the new samples should be added to the README.md file in the parent directory of the new sample.
36-
37-
The sample code should follow these guidelines:
38-
39-
- Configuration settings should be read from environment variables, e.g. `var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");`.
40-
- Environment variables should use upper snake_case naming convention.
41-
- Secrets should not be hardcoded in the code or committed to the repository.
42-
- The code should be well-documented with comments explaining the purpose of each step.
43-
- The code should be simple and to the point, avoiding unnecessary complexity.
44-
- Prefer inline literals over constants for values that are not reused. For example, use `new ChatClientAgent(chatClient, instructions: "You are a helpful assistant.")` instead of defining a constant for "instructions".
45-
- Ensure that all private classes are sealed
46-
- Use the Async suffix on the name of all async methods that return a Task or ValueTask.
47-
- Prefer defining variables using types rather than var, to help users understand the types involved.
48-
- Follow the patterns in the samples in the same directories where new samples are being added.
49-
- The structure of the sample should be as follows:
50-
- The top of the Program.cs should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.`
51-
- Then add a comment describing what the sample is demonstrating.
52-
- Then add the necessary using statements.
53-
- Then add the main code logic.
54-
- Finally, add any helper methods or classes at the bottom of the file.
55-
56-
### C# Unit Test Guidelines
57-
58-
Unit tests are located in the `dotnet/tests` directory in projects with a `.UnitTests.csproj` suffix.
59-
60-
Unit tests should follow these guidelines:
61-
62-
- Use `this.` for accessing class members
63-
- Add Arrange, Act and Assert comments for each test
64-
- Ensure that all private classes, that are not subclassed, are sealed
65-
- Use the Async suffix on the name of all async methods
66-
- Use the Moq library for mocking objects where possible
67-
- Validate that each test actually tests the target behavior, e.g. we should not have tests that creates a mock, calls the mock and then verifies that the mock was called, without the target code being involved. We also shouldn't have tests that test language features, e.g. something that the compiler would catch anyway.
68-
- Avoid adding excessive comments to tests. Instead favour clear easy to understand code.
69-
- Follow the patterns in the unit tests in the same project or classes to which new tests are being added
3+
Microsoft Agent Framework - a multi-language framework for building, orchestrating, and deploying AI agents.
4+
5+
## Repository Structure
6+
7+
- `python/` - Python implementation (packages in `python/packages/`, samples in `python/samples/`)
8+
- `dotnet/` - C#/.NET implementation (source in `dotnet/src/`, samples in `dotnet/samples/`)
9+
- `docs/` - Design documents and architectural decision records
10+
11+
## Build, Test, and Lint Commands
12+
13+
### Python
14+
15+
```bash
16+
# From python/ directory
17+
uv run poe check # Run all checks (format, lint, type check, test)
18+
uv run poe fmt # Format code with ruff
19+
uv run poe lint # Lint with ruff
20+
uv run poe pyright # Type check with pyright
21+
uv run poe test # Run all tests with coverage
22+
23+
# Run tests for a specific package
24+
uv run --directory packages/core poe test
25+
26+
# Run a single test file
27+
uv run pytest packages/core/tests/test_agents.py
28+
29+
# Run a single test
30+
uv run pytest packages/core/tests/test_agents.py::test_function_name -v
31+
```
32+
33+
### .NET
34+
35+
```bash
36+
# From dotnet/ directory
37+
dotnet build # Build all projects
38+
dotnet test # Run all tests
39+
dotnet format # Auto-fix formatting
40+
41+
# Run a single test
42+
dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName"
43+
```
44+
45+
## Architecture
46+
47+
### Python Package Structure
48+
49+
The Python codebase uses a monorepo with lazy-loaded connector packages:
50+
51+
- `agent-framework-core` - Core abstractions (`ChatAgent`, `ChatMessage`, tool definitions, workflows)
52+
- `agent-framework-<provider>` - Provider-specific packages (azure-ai, anthropic, ollama, etc.)
53+
54+
Users import from a unified namespace:
55+
```python
56+
from agent_framework import ChatAgent, tool
57+
from agent_framework.openai import OpenAIChatClient
58+
from agent_framework.azure import AzureOpenAIChatClient
59+
```
60+
61+
Provider folders in core use `__getattr__` for lazy loading - classes are only imported when accessed.
62+
63+
### .NET Package Structure
64+
65+
- `Microsoft.Agents.AI` - Core AI agent abstractions
66+
- `Microsoft.Agents.AI.<Provider>` - Provider implementations (OpenAI, AzureAI, Anthropic, etc.)
67+
- `Microsoft.Agents.AI.Workflows` - Workflow orchestration
68+
- `Microsoft.Extensions.AI.Agents` - Integration with Microsoft.Extensions.AI
69+
70+
## Key Conventions
71+
72+
### Python
73+
74+
- **Copyright header**: `# Copyright (c) Microsoft. All rights reserved.` at top of all `.py` files
75+
- **Type hints**: Always specify return types and parameter types; use `Type | None` instead of `Optional`
76+
- **Logging**: Use `from agent_framework import get_logger` (not `import logging`)
77+
- **Docstrings**: Google-style for all public functions/classes
78+
- **Line length**: 120 characters
79+
- **Async**: Assume async by default; check function signatures
80+
- **Tests**: Do not mark with `@pytest.mark.asyncio` (auto mode enabled)
81+
- **Keyword args**: Use for functions with >3 parameters; document `**kwargs` usage
82+
83+
### .NET
84+
85+
- **Copyright header**: `// Copyright (c) Microsoft. All rights reserved.` at top of all `.cs` files
86+
- **XML docs**: Required for all public methods and classes
87+
- **Async**: Use `Async` suffix for methods returning `Task`/`ValueTask`
88+
- **Private classes**: Should be `sealed` unless subclassed
89+
- **Config**: Read from environment variables with `UPPER_SNAKE_CASE` naming
90+
- **Tests**: Use `this.` for class members; add Arrange/Act/Assert comments; use Moq for mocking
91+
92+
### Samples
93+
94+
Both Python and .NET samples follow similar patterns:
95+
1. Copyright header
96+
2. Imports/usings
97+
3. Description comment
98+
4. Main code logic
99+
5. Helper methods at bottom
100+
101+
Configuration via environment variables (never hardcode secrets). Keep samples simple and focused.

‎.gitignore‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -199,8 +199,6 @@ temp*/
199199
.tmp/
200200
.temp/
201201

202-
agents.md
203-
204202
# AI
205203
.claude/
206204
WARP.md
Lines changed: 7 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,11 @@
11
---
22
applyTo: '**/agent-framework/python/**'
33
---
4-
- Use `uv run` as the main entrypoint for running Python commands with all packages available.
5-
- Use `uv run poe <task>` for development tasks like formatting (`fmt`), linting (`lint`), type checking (`pyright`, `mypy`), and testing (`test`).
6-
- Use `uv run --directory packages/<package> poe <task>` to run tasks for a specific package.
7-
- Read [DEV_SETUP.md](../../DEV_SETUP.md) for detailed development environment setup and available poe tasks.
8-
- Read [CODING_STANDARD.md](../../CODING_STANDARD.md) for the project's coding standards and best practices.
9-
- When verifying logic with unit tests, run only the related tests, not the entire test suite.
10-
- For new tests and samples, review existing ones to understand the coding style and reuse it.
11-
- When generating new functions, always specify the function return type and parameter types.
12-
- Do not use `Optional`; use `Type | None` instead.
13-
- Before running any commands to execute or test the code, ensure that all problems, compilation errors, and warnings are resolved.
14-
- When formatting files, format only the files you changed or are currently working on; do not format the entire codebase.
15-
- Do not mark new tests with `@pytest.mark.asyncio`.
16-
- If you need debug information to understand an issue, use print statements as needed and remove them when testing is complete.
17-
- Avoid adding excessive comments.
18-
- When working with samples, make sure to update the associated README files with the latest information. These files are usually located in the same folder as the sample or in one of its parent folders.
194

20-
Sample structure:
21-
1. Copyright header: `# Copyright (c) Microsoft. All rights reserved.`
22-
2. Required imports.
23-
3. Short description about the sample: `"""This sample demonstrates..."""`
24-
4. Helper functions.
25-
5. Main functions that demonstrate the functionality. If it is a single scenario, use a `main` function. If there are multiple scenarios, define separate functions and add a `main` function that invokes all scenarios.
26-
6. Place `if __name__ == "__main__": asyncio.run(main())` at the end of the sample file to make the example executable.
5+
See [AGENTS.md](../../AGENTS.md) for project structure, commands, and conventions.
6+
7+
Additional guidance:
8+
- Review existing tests and samples to understand coding style before creating new ones
9+
- When verifying logic, run only related tests, not the entire suite
10+
- Resolve all errors and warnings before running code
11+
- Use print statements for debugging, then remove them when done

‎python/AGENTS.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# AGENTS.md
2+
3+
Instructions for AI coding agents working in the Python codebase.
4+
5+
**Key Documentation:**
6+
- [DEV_SETUP.md](DEV_SETUP.md) - Development environment setup and available poe tasks
7+
- [CODING_STANDARD.md](CODING_STANDARD.md) - Coding standards, docstring format, and performance guidelines
8+
9+
## Maintaining Documentation
10+
11+
When making changes to a package, check if the package's `AGENTS.md` file needs updates. This includes:
12+
- Adding/removing/renaming public classes or functions
13+
- Changing the package's purpose or architecture
14+
- Modifying import paths or usage patterns
15+
16+
## Quick Reference
17+
18+
Run `uv run poe` from the `python/` directory to see available commands. See [DEV_SETUP.md](DEV_SETUP.md) for detailed usage.
19+
20+
## Project Structure
21+
22+
```
23+
python/
24+
├── packages/
25+
│ ├── core/ # agent-framework-core (main package)
26+
│ │ ├── agent_framework/ # Public API exports
27+
│ │ └── tests/
28+
│ ├── azure-ai/ # agent-framework-azure-ai
29+
│ ├── anthropic/ # agent-framework-anthropic
30+
│ ├── ollama/ # agent-framework-ollama
31+
│ └── ... # Other provider packages
32+
├── samples/ # Sample code and examples
33+
└── tests/ # Integration tests
34+
```
35+
36+
### Package Relationships
37+
38+
- `agent-framework-core` contains core abstractions and OpenAI/Azure OpenAI built-in
39+
- Provider packages (`azure-ai`, `anthropic`, etc.) extend core with specific integrations
40+
- Core uses lazy loading via `__getattr__` in provider folders (e.g., `agent_framework/azure/`)
41+
42+
### Import Patterns
43+
44+
```python
45+
# Core imports
46+
from agent_framework import ChatAgent, ChatMessage, tool
47+
48+
# Provider imports (lazy-loaded)
49+
from agent_framework.openai import OpenAIChatClient
50+
from agent_framework.azure import AzureOpenAIChatClient, AzureAIAgentClient
51+
```
52+
53+
## Key Conventions
54+
55+
- **Copyright**: `# Copyright (c) Microsoft. All rights reserved.` at top of all `.py` files
56+
- **Types**: Always specify return types and parameter types; use `Type | None` not `Optional`
57+
- **Logging**: `from agent_framework import get_logger` (never `import logging`)
58+
- **Docstrings**: Google-style for public APIs
59+
- **Tests**: Do not use `@pytest.mark.asyncio` (auto mode enabled); run only related tests, not the entire suite
60+
- **Line length**: 120 characters
61+
- **Comments**: Avoid excessive comments; prefer clear code
62+
- **Formatting**: Format only files you changed, not the entire codebase
63+
64+
## Sample Structure
65+
66+
1. Copyright header: `# Copyright (c) Microsoft. All rights reserved.`
67+
2. Required imports
68+
3. Module docstring: `"""This sample demonstrates..."""`
69+
4. Helper functions
70+
5. Main function(s) demonstrating functionality
71+
6. Entry point: `if __name__ == "__main__": asyncio.run(main())`
72+
73+
When modifying samples, update associated README files in the same or parent folders.
74+
75+
## Package Documentation
76+
77+
### Core
78+
- [core](packages/core/AGENTS.md) - Core abstractions, types, and built-in OpenAI/Azure OpenAI support
79+
80+
### LLM Providers
81+
- [anthropic](packages/anthropic/AGENTS.md) - Anthropic Claude API
82+
- [bedrock](packages/bedrock/AGENTS.md) - AWS Bedrock
83+
- [claude](packages/claude/AGENTS.md) - Claude Agent SDK
84+
- [foundry_local](packages/foundry_local/AGENTS.md) - Azure AI Foundry Local
85+
- [ollama](packages/ollama/AGENTS.md) - Local Ollama inference
86+
87+
### Azure Integrations
88+
- [azure-ai](packages/azure-ai/AGENTS.md) - Azure AI Foundry agents
89+
- [azure-ai-search](packages/azure-ai-search/AGENTS.md) - Azure AI Search RAG
90+
- [azurefunctions](packages/azurefunctions/AGENTS.md) - Azure Functions hosting
91+
92+
### Protocols & UI
93+
- [a2a](packages/a2a/AGENTS.md) - Agent-to-Agent protocol
94+
- [ag-ui](packages/ag-ui/AGENTS.md) - AG-UI protocol
95+
- [chatkit](packages/chatkit/AGENTS.md) - OpenAI ChatKit integration
96+
- [devui](packages/devui/AGENTS.md) - Developer UI for testing
97+
98+
### Storage & Memory
99+
- [mem0](packages/mem0/AGENTS.md) - Mem0 memory integration
100+
- [redis](packages/redis/AGENTS.md) - Redis storage
101+
102+
### Infrastructure
103+
- [copilotstudio](packages/copilotstudio/AGENTS.md) - Microsoft Copilot Studio
104+
- [declarative](packages/declarative/AGENTS.md) - YAML/JSON agent definitions
105+
- [durabletask](packages/durabletask/AGENTS.md) - Durable execution
106+
- [github_copilot](packages/github_copilot/AGENTS.md) - GitHub Copilot extensions
107+
- [purview](packages/purview/AGENTS.md) - Data governance
108+
109+
### Experimental
110+
- [lab](packages/lab/AGENTS.md) - Experimental features

0 commit comments

Comments
 (0)