Skip to content

Commit 166e13b

Browse files
Address PR review comments and restructure instructions
- Slim down .github/copilot-instructions.md to reference language-specific docs - Add ADR section explaining templates and purpose - Create dotnet/AGENTS.md with .NET-specific build commands, conventions, and sample guidance - Update Python build/test instructions for core vs isolated changes - Fix Microsoft.Extensions.AI package references - Update kwargs guidance per issue microsoft#3642 - Fix Python sample helper placement (top, not bottom) - Document new 'typing' poe task in DEV_SETUP.md
1 parent 903f8df commit 166e13b

3 files changed

Lines changed: 80 additions & 90 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 8 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -4,98 +4,16 @@ Microsoft Agent Framework - a multi-language framework for building, orchestrati
44

55
## Repository Structure
66

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/`)
7+
- `python/` - Python implementation → see [python/AGENTS.md](../python/AGENTS.md)
8+
- `dotnet/` - C#/.NET implementation → see [dotnet/AGENTS.md](../dotnet/AGENTS.md)
99
- `docs/` - Design documents and architectural decision records
1010

11-
## Build, Test, and Lint Commands
11+
## Architectural Decision Records (ADRs)
1212

13-
### Python
13+
ADRs in `docs/decisions/` capture significant design decisions and their rationale. They document considered alternatives, trade-offs, and the reasoning behind choices.
1414

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
15+
**Templates:**
16+
- `adr-template.md` - Full template with detailed sections
17+
- `adr-short-template.md` - Abbreviated template for simpler decisions
2218

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.
19+
When proposing architectural changes, create an ADR to capture options considered and the decision rationale. See [docs/decisions/README.md](../docs/decisions/README.md) for the full process.

‎dotnet/AGENTS.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# AGENTS.md
2+
3+
Instructions for AI coding agents working in the .NET codebase.
4+
5+
## Build, Test, and Lint Commands
6+
7+
```bash
8+
# From dotnet/ directory
9+
dotnet build # Build all projects
10+
dotnet test # Run all tests
11+
dotnet format # Auto-fix formatting
12+
13+
# Build/test a specific project (preferred for isolated changes)
14+
dotnet build src/Microsoft.Agents.AI.<Package>
15+
dotnet test tests/Microsoft.Agents.AI.<Package>.UnitTests
16+
17+
# Run a single test
18+
dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName"
19+
```
20+
21+
**Note**: Changes to core packages (`Microsoft.Agents.AI`, `Microsoft.Agents.AI.Abstractions`) affect dependent projects - run checks across the entire solution. For isolated changes, build/test only the affected project to save time.
22+
23+
## Project Structure
24+
25+
```
26+
dotnet/
27+
├── src/
28+
│ ├── Microsoft.Agents.AI/ # Core AI agent abstractions
29+
│ ├── Microsoft.Agents.AI.Abstractions/ # Shared abstractions and interfaces
30+
│ ├── Microsoft.Agents.AI.OpenAI/ # OpenAI provider
31+
│ ├── Microsoft.Agents.AI.AzureAI/ # Azure AI provider
32+
│ ├── Microsoft.Agents.AI.Anthropic/ # Anthropic provider
33+
│ ├── Microsoft.Agents.AI.Workflows/ # Workflow orchestration
34+
│ └── ... # Other packages
35+
├── samples/ # Sample applications
36+
└── tests/ # Unit and integration tests
37+
```
38+
39+
### External Dependencies
40+
41+
The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extensions.AI.Abstractions` (external NuGet packages) using types like `IChatClient`, `FunctionInvokingChatClient`, `AITool`, and `AIContent`.
42+
43+
## Key Conventions
44+
45+
- **Copyright header**: `// Copyright (c) Microsoft. All rights reserved.` at top of all `.cs` files
46+
- **XML docs**: Required for all public methods and classes
47+
- **Async**: Use `Async` suffix for methods returning `Task`/`ValueTask`
48+
- **Private classes**: Should be `sealed` unless subclassed
49+
- **Config**: Read from environment variables with `UPPER_SNAKE_CASE` naming
50+
- **Tests**: Add Arrange/Act/Assert comments; use Moq for mocking
51+
52+
## Sample Structure
53+
54+
1. Copyright header: `// Copyright (c) Microsoft. All rights reserved.`
55+
2. Description comment explaining what the sample demonstrates
56+
3. Using statements
57+
4. Main code logic
58+
5. Helper methods at bottom
59+
60+
Configuration via environment variables (never hardcode secrets). Keep samples simple and focused.
61+
62+
When adding a new sample:
63+
- Create a standalone project in `samples/` with matching directory and project names
64+
- Include a README.md explaining what the sample does and how to run it
65+
- Add the project to the solution file
66+
- Reference the sample in the parent directory's README.md

‎python/DEV_SETUP.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,12 @@ Run MyPy type checking:
254254
uv run poe mypy
255255
```
256256

257+
#### `typing`
258+
Run both Pyright and MyPy type checking:
259+
```bash
260+
uv run poe typing
261+
```
262+
257263
### Code Validation
258264

259265
#### `markdown-code-lint`

0 commit comments

Comments
 (0)