Agent365-dotnet

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build Commands

### Basic Build Operations
```bash
# Build the entire solution
dotnet build src/Microsoft.Agents.A365.Sdk.sln

# Build using PowerShell script (recommended)
./build/build.ps1

# Full clean rebuild
./build/build.ps1 -Clean -Restore

# Build with tests
./build/build.ps1 -Test

# Build with NuGet packaging
./build/build.ps1 -Pack

# Debug build with tests
./build/build.ps1 -Configuration Debug -Test
```

### Testing
```bash
# Run all tests
dotnet test src/Microsoft.Agents.A365.Sdk.sln

# Run tests using build script
./build/build.ps1 -Test

# Run tests for a specific project
dotnet test src/Tests/Runtime.Tests/Microsoft.Agents.A365.Runtime.Tests.csproj
```

### Package Management
- **All package versions** are centralized in `src/Directory.Packages.props`
- To add a new package: add the version to `Directory.Packages.props`, then reference without version in the `.csproj`
- Never specify versions directly in project files

## Code Standards

### Copyright Headers
Every C# file must include this header at the top:
```csharp
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.
```

Exceptions:
- Auto-generated files (`.g.cs`, `.designer.cs`, files with `<auto-generated>` markers)
- Files in `bin/`, `obj/` directories
- Third-party or vendored code

### Legacy References
- **Never** use the keyword "Kairo" in any code - this is legacy terminology that must be replaced

### Observability Export Configuration — Coordinated Review Required

The following three constants must stay in sync. If a PR changes **any one** of them, the reviewer (human or Copilot) **must** ask the author to confirm the other two are still correct:

| Constant | Location |
|---|---|
| `ProdObservabilityScope` | `src/Observability/Runtime/Common/EnvironmentUtils.cs` (accessed via `GetObservabilityAuthenticationScope()`) |
| `DefaultEndpointHost` | `src/Observability/Runtime/Tracing/Exporters/Agent365ExporterOptions.cs` |
| Export URL path pattern | `BuildEndpointPath()` in `src/Observability/Runtime/Tracing/Exporters/Agent365ExporterCore.cs` |

Snapshot tests in `src/Tests/Microsoft.Agents.A365.Observability.Runtime.Tests/Tracing/Exporters/ExportConfigConsistencyTests.cs` will fail if any value drifts, but the developer must also verify the values are correct for the target environment — the tests only catch accidental drift, not intentional-but-incomplete updates.

### Pre-Commit Requirements
Before committing changes, ensure:
1. The solution builds: `dotnet build src/Microsoft.Agents.A365.Sdk.sln`
2. All tests pass: `dotnet test src/Microsoft.Agents.A365.Sdk.sln`
3. If adding/renaming/removing projects, update `src/Microsoft.Agents.A365.Sdk.sln`

## Architecture Overview

### Four Core Modules

This SDK extends the Microsoft 365 Agents SDK with four main areas:

**1. Runtime** (`Microsoft.Agents.A365.Runtime`)
- Multi-tenant context extraction via `TenantContextHelper` (claims, headers, items)
- Standardized result handling with `OperationResult` and `OperationError`
- Authorization services for agentic operations

**2. Observability** (6 packages under `Microsoft.Agents.A365.Observability.*`)
- OpenTelemetry-based distributed tracing with custom span processors
- Scope classes: `InvokeAgentScope`, `InferenceScope`, `ExecuteToolScope`
- Framework extensions for Agent Framework, Semantic Kernel, and OpenAI SDK
- ETW (Event Tracing for Windows) support via Hosting package
- Configuration via fluent `Builder` API

**3. Notifications** (`Microsoft.Agents.A365.Notifications`)
- Event-driven notification handling for M365 (Teams, email, Office apps)
- Support for `agents:email`, `agents:word`, `agents:excel`, `agents:powerpoint` sub-channels
- Type-safe models: `EmailReference`, `EmailResponse`, `WpxComment`
- Lifecycle notifications (user identity created, auto sign-in)

**4. Tooling** (4 packages under `Microsoft.Agents.A365.Tooling.*`)
- Model Context Protocol (MCP) server discovery and integration
- `IMcpToolServerConfigurationService` for server discovery and tool registration
- Framework-specific registration for Semantic Kernel, Agent Framework, Azure AI Foundry
- Bearer token and context header handling for tool server communication

### Extension Pattern
The SDK uses a consistent **Core + Extensions** pattern:
- Core packages provide base functionality
- Extension packages integrate with specific frameworks (SemanticKernel, AgentFramework, AzureAIFoundry, OpenAI)
- Example: `Observability/Runtime` (core) → `Observability/Extensions/SemanticKernel` (framework-specific)

### Key Design Patterns

**Builder Pattern**: Fluent API for observability configuration
```csharp
new Builder(services, configuration)
    .WithAgentFramework()
    .WithSemanticKernel()
    .Build();
```

**Disposable Pattern**: Automatic span lifecycle management
```csharp
using var scope = InvokeAgentScope.Start(details, tenantDetails, request);
scope.RecordResponse(response);
// Span automatically ends on dispose
```

**Result Pattern**: Consistent success/failure handling
```csharp
return OperationResult.Success;
return OperationResult.Failed(new OperationError("Message", HttpStatusCode.NotFound));
```

## Project Organization

### Target Frameworks
- Most packages: `net8.0`
- Runtime/Hosting packages: `netstandard2.0` (broader compatibility)

### Build System
- **SDK Version**: .NET 8.0.100 (defined in `src/global.json`)
- **Build Traversal**: Microsoft.Build.Traversal (v3.4.0) via `src/dirs.proj`
- **Automatic Discovery**: Projects are auto-discovered via wildcards; no manual solution maintenance needed
- **Versioning**: Nerdbank.GitVersioning (nbgv) - semantic versioning from git history

### Configuration Files
- `src/global.json` - .NET SDK version lock
- `src/Directory.Packages.props` - **Single source of truth** for all NuGet versions
- `src/Directory.Build.props` - Common build properties (warnings as errors, nullable enabled, XML docs)
- `src/dirs.proj` - Build traversal root

### Common Build Properties
- Warnings treated as errors
- Nullable reference types enabled
- XML documentation generation enabled
- Implicit usings enabled (net6.0+)
- Source Link embedded for debugging

## Key Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| `Microsoft.Agents.Builder` | 1.3.163-beta | Core Agents SDK |
| `Microsoft.Agents.AI` | 1.0.0-preview.251016.1 | Agent Framework |
| `OpenTelemetry` | 1.11.2 | Distributed tracing foundation |
| `Microsoft.SemanticKernel` | 1.65.0 | Semantic Kernel orchestration |
| `Azure.AI.OpenAI` | 2.3.0-beta.2 | Azure OpenAI SDK |
| `ModelContextProtocol.Core` | 0.2.0-preview.3 | MCP client SDK |
| `Azure.AI.Agents.Persistent` | 1.2.0-beta.4 | Azure AI Foundry |

## Important Classes and Entry Points

### Runtime (`src/Runtime/Core/`)
- `TenantContextHelper` - Extract tenant/worker ID from HttpContext
- `AgenticAuthorizationService` - Authorization for agent operations

### Observability (`src/Observability/`)
- `Builder` (Runtime) - Fluent OpenTelemetry configuration API
- `InvokeAgentScope`, `InferenceScope`, `ExecuteToolScope` - Tracing scopes
- `BaggageBuilder` - OpenTelemetry baggage context management

### Notifications (`src/Notification/`)
- `AgentNotification` - AgentExtension for routing notifications
- `AgentNotificationActivity` - Activity wrapper for notification data

### Tooling (`src/Tooling/Core/`)
- `IMcpToolServerConfigurationService` - MCP server discovery interface
- `McpToolServerConfigurationService` - Implementation
- `MCPServerConfig` - Server configuration model

## Environment Variables

| Variable | Purpose | Default |
|----------|---------|---------|
| `EnableAgent365Exporter` | Enable Agent365 telemetry exporter | `false` |
| `ASPNETCORE_ENVIRONMENT` | Environment (Development, Production) | - |
| `SuppressInvokeAgentInput` | Suppress input in invoke_agent spans | `false` |

## Testing Structure

Tests mirror the source structure in `src/Tests/`:
- Unit tests for each package (e.g., `Microsoft.Agents.A365.Runtime.Tests`)
- Integration tests (e.g., `Microsoft.Agents.A365.Observability.Runtime.IntegrationTests`)
- Framework-specific extension tests

Testing frameworks: xUnit (primary), MSTest, with Moq for mocking and FluentAssertions for assertions.

## Package Naming Convention

All published NuGet packages follow the pattern:
```
Microsoft.Agents.A365.<Module>[.Extensions.<Framework>]
```

Examples:
- `Microsoft.Agents.A365.Runtime`
- `Microsoft.Agents.A365.Observability.Extensions.SemanticKernel`
- `Microsoft.Agents.A365.Tooling.Extensions.AzureAIFoundry`

## Data Flow Examples

### Agent Invocation Tracing
1. HTTP request enters via middleware
2. `BaggageMiddleware` sets tenant/agent context in OpenTelemetry baggage
3. `InvokeAgentScope` creates root span for agent invocation
4. `InferenceScope` creates child span for LLM inference
5. `ExecuteToolScope` creates child spans for tool executions
6. Span processors add tags and export to Agent365 Exporter or Console

### MCP Tool Discovery
1. Agent receives user message requiring tools
2. Call `ListToolServersAsync` to query Tooling Gateway
3. For each server, call `GetMcpClientToolsAsync` to connect via MCP SDK
4. Register tools with orchestrator (Semantic Kernel / Agent Framework / Azure AI Foundry)
5. Agent executes user request with discovered tools

## Additional Resources

- [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/)
- [Design Documentation](docs/design.md) - Detailed architecture and package-specific design docs
- [Build Documentation](build/BUILD.md) - Comprehensive build system details