|
1 | 1 | # GitHub Copilot Instructions |
2 | 2 |
|
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. |
0 commit comments