mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
.NET: Add tweaks to .net agent skills (#4081)
* Add tweaks to .net agent skills * Address PR feedback
This commit is contained in:
westey
+54
-12
@@ -3,41 +3,83 @@ name: build-and-test
|
||||
description: How to build and test .NET projects in the Agent Framework repository. Use this when verifying or testing changes.
|
||||
---
|
||||
|
||||
# Build and Test
|
||||
|
||||
- Only **UnitTest** projects need to be run locally; IntegrationTests require external dependencies.
|
||||
- See `../project-structure/SKILL.md` for project structure details.
|
||||
|
||||
## Speeding Up Builds
|
||||
## Build, Test, and Lint Commands
|
||||
|
||||
```bash
|
||||
# From dotnet/ directory
|
||||
dotnet restore --tl:off # Restore dependencies for all projects
|
||||
dotnet build --tl:off # Build all projects
|
||||
dotnet test # Run all tests
|
||||
dotnet format # Auto-fix formatting for all projects
|
||||
|
||||
# Build/test/format a specific project (preferred for isolated/internal changes)
|
||||
dotnet build src/Microsoft.Agents.AI.<Package> --tl:off
|
||||
dotnet test tests/Microsoft.Agents.AI.<Package>.UnitTests
|
||||
dotnet format src/Microsoft.Agents.AI.<Package>
|
||||
|
||||
# Run a single test
|
||||
dotnet test --filter "FullyQualifiedName~Namespace.TestClassName.TestMethodName"
|
||||
|
||||
# Run unit tests only
|
||||
dotnet test --filter FullyQualifiedName\~UnitTests
|
||||
```
|
||||
|
||||
Use `--tl:off` when building to avoid flickering when running commands in the agent.
|
||||
|
||||
## Speeding Up Builds and Testing
|
||||
|
||||
The full solution is large. Use these shortcuts:
|
||||
|
||||
| Change type | What to do |
|
||||
|-------------|------------|
|
||||
| Internal logic | Build only the affected project and its `*.UnitTests` project. Fix issues, then build the full solution and run all unit tests. |
|
||||
| Isolated/Internal logic | Build only the affected project and its `*.UnitTests` project. Fix issues, then build the full solution and run all unit tests. |
|
||||
| Public API surface | Build the full solution and run all unit tests immediately. |
|
||||
|
||||
Example: Building a single code project for all target frameworks
|
||||
|
||||
```bash
|
||||
cd /workspaces/agent-framework/dotnet
|
||||
dotnet build ./src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj
|
||||
# From dotnet/ directory
|
||||
dotnet build ./src/Microsoft.Agents.AI.Abstractions
|
||||
```
|
||||
|
||||
Example: Building a single code project for just .NET 10.
|
||||
|
||||
```bash
|
||||
cd /workspaces/agent-framework/dotnet
|
||||
dotnet build ./src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj -f net10.0
|
||||
# From dotnet/ directory
|
||||
dotnet build ./src/Microsoft.Agents.AI.Abstractions -f net10.0
|
||||
```
|
||||
|
||||
Example: Running tests for a single project using .net 10.
|
||||
Example: Running tests for a single project using .NET 10.
|
||||
|
||||
```bash
|
||||
cd /workspaces/agent-framework/dotnet
|
||||
dotnet test ./tests/Microsoft.Agents.AI.Abstractions.UnitTests/Microsoft.Agents.AI.Abstractions.UnitTests.csproj -f net10.0
|
||||
# From dotnet/ directory
|
||||
dotnet test ./tests/Microsoft.Agents.AI.Abstractions.UnitTests -f net10.0
|
||||
```
|
||||
|
||||
Example: Running a single test in a specific project using .NET 10.
|
||||
Provide the full namespace, class name, and method name for the test you want to run:
|
||||
|
||||
```bash
|
||||
# From dotnet/ directory
|
||||
dotnet test ./tests/Microsoft.Agents.AI.Abstractions.UnitTests -f net10.0 --filter "FullyQualifiedName~Microsoft.Agents.AI.Abstractions.UnitTests.AgentRunOptionsTests.CloningConstructorCopiesProperties"
|
||||
```
|
||||
|
||||
### Multi-target framework tip
|
||||
|
||||
Most projects target multiple .NET frameworks. If the affected code does **not** use `#if` directives for framework-specific logic, pass `--framework net10.0` to speed up building and testing.
|
||||
Most projects target multiple .NET frameworks. If the affected code does **not** use `#if` directives for framework-specific logic, pass `-f net10.0` to speed up building and testing.
|
||||
|
||||
### Package Restore tip
|
||||
|
||||
`dotnet build` will try and restore packages for all projects on each build, which can be slow.
|
||||
Unless packages have been changed, or it's the first time building the solution, add `--no-restore` to the build command to skip this step and speed up builds.
|
||||
|
||||
Just remember to run `dotnet restore` after pulling changes, making changes to project references, or when building for the first time.
|
||||
|
||||
### Testing on Linux tip
|
||||
|
||||
Unit tests target both .NET Framework as well as .NET Core. When running on Linux, only the .NET Core tests can be run, as .NET Framework is not supported on Linux.
|
||||
|
||||
To run only the .NET Core tests, use the `-f net10.0` option with `dotnet test`.
|
||||
|
||||
+17
-1
@@ -5,7 +5,23 @@ description: Explains the project structure of the agent-framework .NET solution
|
||||
|
||||
# Agent Framework .NET Project Structure
|
||||
|
||||
## Folders
|
||||
```
|
||||
dotnet/
|
||||
├── src/
|
||||
│ ├── Microsoft.Agents.AI/ # Core AI agent implementations
|
||||
│ ├── Microsoft.Agents.AI.Abstractions/ # Core AI agent abstractions
|
||||
│ ├── Microsoft.Agents.AI.A2A/ # Agent-to-Agent (A2A) provider
|
||||
│ ├── Microsoft.Agents.AI.OpenAI/ # OpenAI provider
|
||||
│ ├── Microsoft.Agents.AI.AzureAI/ # Azure AI Foundry Agents (v2) provider
|
||||
│ ├── Microsoft.Agents.AI.AzureAI.Persistent/ # Legacy Azure AI Foundry Agents (v1) provider
|
||||
│ ├── Microsoft.Agents.AI.Anthropic/ # Anthropic provider
|
||||
│ ├── Microsoft.Agents.AI.Workflows/ # Workflow orchestration
|
||||
│ └── ... # Other packages
|
||||
├── samples/ # Sample applications
|
||||
└── tests/ # Unit and integration tests
|
||||
```
|
||||
|
||||
## Main Folders
|
||||
|
||||
| Folder | Contents |
|
||||
|--------|----------|
|
||||
|
||||
+28
-29
@@ -4,41 +4,28 @@ Instructions for AI coding agents working in the .NET codebase.
|
||||
|
||||
## Build, Test, and Lint Commands
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
See `./.github/skills/build-and-test/SKILL.md` for detailed instructions on building, testing, and linting projects.
|
||||
|
||||
## 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
|
||||
```
|
||||
See `./.github/skills/project-structure/SKILL.md` for an overview of the project structure.
|
||||
|
||||
### 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`, and `AIContent`.
|
||||
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
|
||||
|
||||
@@ -49,8 +36,19 @@ The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extension
|
||||
- **Config**: Read from environment variables with `UPPER_SNAKE_CASE` naming
|
||||
- **Tests**: Add Arrange/Act/Assert comments; use Moq for mocking
|
||||
|
||||
## 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
|
||||
@@ -60,6 +58,7 @@ The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extension
|
||||
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 in New Issue
Block a user