Skip to content

CLAUDE.md

Latest commit

 

History

History
246 lines (188 loc) · 9.56 KB

CLAUDE.md

File metadata and controls

246 lines (188 loc) · 9.56 KB
Raw

CLAUDE.md

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

Build Commands

Basic Build Operations

# 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

# 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:

// 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

new Builder(services, configuration)
    .WithAgentFramework()
    .WithSemanticKernel()
    .Build();

Disposable Pattern: Automatic span lifecycle management

using var scope = InvokeAgentScope.Start(details, tenantDetails, request);
scope.RecordResponse(response);
// Span automatically ends on dispose

Result Pattern: Consistent success/failure handling

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