mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Eduard van Valkenburg
7e9c043c4c
* Improve PR template and breaking-change label automation - Add a structured "Related Issue" section using GitHub closing keywords - Add a Review Guide prompt (major changes, impact, reviewer focus) with a note that the focus item is for human reviewers only - Add checklist items for issue linkage / no duplicate PRs and invert the breaking-change item (checked = not breaking) - Extend label-title-prefix to prepend [BREAKING] when the "breaking change" label is added - Add label-breaking-change workflow to apply the "breaking change" label when a PR title contains [BREAKING] Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add pull-requests agent skill with dotnet/python links - Add root .github/skills/pull-requests/SKILL.md covering PR description authoring (following the PR template) and the review-comment workflow (review -> plan -> user review -> implement -> reply to all -> resolve) - Symlink the skill from python/.github/skills and dotnet/.github/skills - Reference the skill from python/AGENTS.md and dotnet/AGENTS.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fold breaking-change labeling into label-pr workflow Move the title -> 'breaking change' label logic into the existing label-pr workflow (which already applies the python/.NET labels) and drop the separate label-breaking-change workflow. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address PR title prefix review feedback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Pin patched MessagePack for .NET restore Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Revert MessagePack central pin Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Move title prefix tests out of tracked GitHub tests Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Exclude skill docs from CI path filters Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Match skill symlinks in CI path exclusions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Exclude AGENTS docs from CI path filters Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Scope title-prefix normalization to a real prefix The normalization branch in addTitlePrefix matched ^Python (no colon), so titles like "Python samples improvements" or "Pythonic refactor" were treated as already-prefixed and only re-cased, never receiving the "Python: " prefix. Scope the match to ^<prefix>:\s* so only an actual existing prefix is normalized; otherwise the prefix is prepended. Same fix applies to the .NET prefix (e.g. ".NETStandard bump"). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
72 lines
4.1 KiB
Markdown
72 lines
4.1 KiB
Markdown
# AGENTS.md
|
|
|
|
Instructions for AI coding agents working in the .NET codebase.
|
|
|
|
## Build, Test, and Lint Commands
|
|
|
|
See `./.github/skills/build-and-test/SKILL.md` for detailed instructions on building, testing, and linting projects.
|
|
|
|
## Project Structure
|
|
|
|
See `./.github/skills/project-structure/SKILL.md` for an overview of the project structure.
|
|
|
|
## Pull Requests
|
|
|
|
See `./.github/skills/pull-requests/SKILL.md` for guidance on writing PR descriptions and handling/resolving PR review comments.
|
|
|
|
### Core types
|
|
|
|
- `AIAgent`: The abstract base class that all agents derive from, providing common methods for interacting with an agent.
|
|
- `AgentSession`: The abstract base class that all agent sessions derive from, representing a conversation with an agent.
|
|
- `ChatClientAgent`: An `AIAgent` implementation that uses an `IChatClient` to send messages to an AI provider and receive responses.
|
|
- `IChatClient`: Interface for sending messages to an AI provider and receiving responses. Used by `ChatClientAgent` and implemented by provider-specific packages.
|
|
- `FunctionInvokingChatClient`: Decorator for `IChatClient` that adds function invocation capabilities.
|
|
- `AITool`: Represents a tool that an agent/AI provider can use, with metadata and an execution delegate.
|
|
- `AIFunction`: A specific type of `AITool` that represents a local function the agent/AI provider can call, with parameters and return types defined.
|
|
- `ChatMessage`: Represents a message in a conversation.
|
|
- `AIContent`: Represents content in a message, which can be text, a function call, tool output and more.
|
|
|
|
### External Dependencies
|
|
|
|
The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extensions.AI.Abstractions` (external NuGet packages)
|
|
using types like `IChatClient`, `FunctionInvokingChatClient`, `AITool`, `AIFunction`, `ChatMessage`, and `AIContent`.
|
|
|
|
## Key Conventions
|
|
|
|
- **Command output capture**: When running `dotnet build`, `dotnet test`, `dotnet format`, or similar commands, redirect output to a temp file first (e.g., `dotnet build --tl:off 2>&1 | Out-File $env:TEMP\build.log`), then analyze the file as needed. This avoids re-running expensive commands when the initial analysis misses something.
|
|
- **Encoding**: All new files must be saved with UTF-8 encoding with BOM (Byte Order Mark). This is required for `dotnet format` to work correctly. When using PowerShell `Set-Content`, always pass `-Encoding UTF8BOM` to preserve the BOM (e.g., `Set-Content $file $content -NoNewline -Encoding UTF8BOM`).
|
|
- **Copyright header**: `// Copyright (c) Microsoft. All rights reserved.` at top of all `.cs` files
|
|
- **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; test methods returning `Task`/`ValueTask` must use the `Async` suffix.
|
|
|
|
## Key Design Principles
|
|
|
|
When developing or reviewing code, verify adherence to these key design principles:
|
|
|
|
- **DRY**: Avoid code duplication by moving common logic into helper methods or helper classes.
|
|
- **Single Responsibility**: Each class should have one clear responsibility.
|
|
- **Encapsulation**: Keep implementation details private and expose only necessary public APIs.
|
|
- **Strong Typing**: Use strong typing to ensure that code is self-documenting and to catch errors at compile time.
|
|
|
|
## Sample Structure
|
|
|
|
Samples (in `./samples/` folder) should follow this structure:
|
|
|
|
1. Copyright header: `// Copyright (c) Microsoft. All rights reserved.`
|
|
2. Description comment explaining what the sample demonstrates
|
|
3. Using statements
|
|
4. Main code logic
|
|
5. 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
|