mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00

Files

T

Eduard van Valkenburg eaad042241 .NET: Python: Add AGENTS.md files and update coding standards (#3644 )

* 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 (#3578)
  - TypeVar naming convention (#3594)
  - Mapping vs MutableMapping (#3577)
  - Avoid shadowing built-ins (#3583)
  - Explicit exports (#3605)
  - Exception documentation guidelines (#3410)
- Simplify python/.github/instructions/python.instructions.md to reference AGENTS.md
- Remove AGENTS.md from .gitignore

* Fix purview import path in AGENTS.md

* 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 #3642
- Fix Python sample helper placement (top, not bottom)
- Document new 'typing' poe task in DEV_SETUP.md

* Add 'typing' poe task to run both pyright and mypy

* Add kwargs guidelines from issue #3642 to CODING_STANDARD.md

* Clarify that connector packages pull in core as dependency

2026-02-05 10:27:46 +00:00

2.7 KiB

Raw Permalink Blame History

AGENTS.md

Instructions for AI coding agents working in the .NET codebase.

Build, Test, and Lint Commands

# From dotnet/ directory
dotnet build              # Build all projects
dotnet test               # Run all tests
dotnet format             # Auto-fix formatting

# Build/test a specific project (preferred for isolated changes)
dotnet build src/Microsoft.Agents.AI.<Package>
dotnet test tests/Microsoft.Agents.AI.<Package>.UnitTests

# Run a single test
dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName"

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.

Project Structure

dotnet/
├── src/
│   ├── Microsoft.Agents.AI/              # Core AI agent abstractions
│   ├── Microsoft.Agents.AI.Abstractions/ # Shared abstractions and interfaces
│   ├── Microsoft.Agents.AI.OpenAI/       # OpenAI provider
│   ├── Microsoft.Agents.AI.AzureAI/      # Azure AI provider
│   ├── Microsoft.Agents.AI.Anthropic/    # Anthropic provider
│   ├── Microsoft.Agents.AI.Workflows/    # Workflow orchestration
│   └── ...                               # Other packages
├── samples/                              # Sample applications
└── tests/                                # Unit and integration tests

External Dependencies

The framework integrates with Microsoft.Extensions.AI and Microsoft.Extensions.AI.Abstractions (external NuGet packages) using types like IChatClient, FunctionInvokingChatClient, AITool, and AIContent.

Key Conventions

XML docs: Required for all public methods and classes
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: Add Arrange/Act/Assert comments; use Moq for mocking

Sample Structure

Description comment explaining what the sample demonstrates
Using statements
Main code logic
Helper methods at bottom

Configuration via environment variables (never hardcode secrets). Keep samples simple and focused.

When adding a new sample:

Create a standalone project in samples/ with matching directory and project names
Include a README.md explaining what the sample does and how to run it
Add the project to the solution file
Reference the sample in the parent directory's README.md

2.7 KiB Raw Permalink Blame History