Skip to content

CLAUDE.md

Latest commit

 

History

History
273 lines (212 loc) · 8.56 KB

CLAUDE.md

File metadata and controls

273 lines (212 loc) · 8.56 KB
Raw

CLAUDE.md

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

Repository Overview

This is the Agent365-Samples repository containing sample agents demonstrating the Microsoft Agent 365 SDK across three languages (C#/.NET, Python, Node.js/TypeScript) and multiple AI orchestrators (OpenAI, Claude, Semantic Kernel, Agent Framework, LangChain, CrewAI, etc.).

The Microsoft Agent 365 SDK extends the Microsoft 365 Agents SDK with enterprise-grade capabilities for observability, notifications, MCP tooling, and runtime utilities.

Repository Structure

Agent365-Samples/
├── dotnet/                    # C#/.NET samples
│   ├── agent-framework/      # Agent Framework orchestrator
│   └── semantic-kernel/      # Semantic Kernel orchestrator
├── python/                    # Python samples
│   ├── agent-framework/
│   ├── openai/
│   ├── claude/
│   ├── crewai/
│   └── google-adk/
├── nodejs/                    # Node.js/TypeScript samples
│   ├── openai/
│   ├── claude/
│   ├── langchain/
│   ├── devin/
│   ├── n8n/
│   ├── perplexity/
│   └── vercel-sdk/
├── salesforce/                # Salesforce/Apex samples (SFDX projects)
│   └── apex-observability/    # Native Apex Agent 365 observability + tool boundary
├── docs/                      # Repository-wide documentation
│   └── design.md             # Architectural patterns
├── prompts/                   # AI development prompts
└── scripts/                   # Utility scripts

Each language directory contains a docs/design.md with language-specific design patterns.

Common Development Commands

C# / .NET

Build:

dotnet build <path-to-sln-or-csproj>

Run:

dotnet run --project <path-to-csproj>

Solutions:

  • dotnet/agent-framework/AgentFrameworkSample.sln
  • dotnet/semantic-kernel/SemanticKernelSampleAgent.sln

Python

Setup:

cd <sample-directory>
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Run:

python host_agent_server.py
# or
python start_with_generic_host.py

Python samples use pyproject.toml for dependency management. Most samples support uv for faster dependency resolution.

Salesforce / Apex

Salesforce samples are SFDX projects (no hosted process). Use the Salesforce CLI (sf).

Validate (no persist):

cd salesforce/<sample-directory>
sf project deploy start --source-dir force-app/main/default --target-org <alias> --dry-run --test-level RunLocalTests

Deploy:

sf project deploy start --source-dir force-app/main/default --target-org <alias> --test-level RunLocalTests

Test:

sf apex run test --target-org <alias> --test-level RunLocalTests --wait 10

RunLocalTests enforces 75% aggregate org coverage. Full Apex tests require a Dev Hub + scratch org.

Node.js / TypeScript

Setup:

cd <sample-directory>
npm install

Build:

npm run build

Run:

npm start           # Production mode
npm run dev         # Development mode with hot reload

Architecture Patterns

All sample agents follow a consistent initialization and message processing flow:

Initialization Flow

  1. Load configuration (environment variables, config files)
  2. Configure observability (Agent 365 tracing/telemetry)
  3. Initialize LLM client (orchestrator-specific)
  4. Register tools (local tools + MCP servers)
  5. Configure authentication (bearer token or auth handlers)
  6. Start HTTP server (listen on /api/messages)

Message Processing Flow

  1. Authentication: JWT validation / auth handlers
  2. Observability Context Setup: Start trace span, set baggage (tenant, agent, conversation)
  3. Tool Registration: Load MCP servers and local tools
  4. LLM Invocation: Process with AI orchestrator
  5. Response: Stream or send response
  6. Cleanup: Close connections, end spans

Authentication Strategies

Authentication is configured in this priority order:

  1. Bearer Token (development): Set BEARER_TOKEN environment variable
  2. Auth Handlers (production): Configured in appsettings.json (C#), .env (Python/Node.js)
  3. No Auth (fallback): Bare LLM mode with graceful degradation

Configuration Files

  • C#: appsettings.json, appsettings.Development.json
  • Python: .env, pyproject.toml
  • Node.js: .env, package.json

Configuration typically includes:

  • LLM client settings (OpenAI/Azure OpenAI endpoints and API keys)
  • Observability settings (Agent 365 tracing)
  • Authentication settings (bearer token or auth handlers)
  • MCP tooling configuration

Observability

All samples integrate Microsoft Agent 365 observability:

  • Token caching for agentic auth tokens
  • Baggage propagation (tenant, agent, conversation IDs)
  • Framework-specific instrumentation (OpenTelemetry)
  • Custom span attributes for tracing

MCP (Model Context Protocol) Tooling

Agents can dynamically load tools from MCP servers:

  • Tools are configured per agent identity
  • Authentication flows through the same mechanism as the agent
  • Samples demonstrate both local tools (weather, datetime) and remote MCP servers (Graph API)

Key Code Locations

C# / .NET

  • Entry point: Program.cs
  • Agent implementation: Agent/MyAgent.cs (or similar)
  • Tools: Tools/ directory
  • Configuration: appsettings.json

Python

  • Entry point: host_agent_server.py or start_with_generic_host.py
  • Agent implementation: agent.py
  • Configuration: .env or embedded in pyproject.toml

Node.js / TypeScript

  • Entry point: src/index.ts
  • Agent implementation: src/agent.ts
  • LLM client: src/client.ts
  • Token cache: src/token-cache.ts
  • Configuration: .env

Code Quality Rules

Copyright Headers

All source files MUST have Microsoft copyright headers:

C# (.cs):

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

Python (.py):

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.

JavaScript/TypeScript (.js, .ts):

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

Apex (.cls):

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

Exclusions: Auto-generated files, test files, configuration files (.json, .yaml, .md), and third-party code.

Legacy Reference Check

Never use "Kairo" in code - this is a legacy reference that should be replaced with appropriate Agent 365 terminology.

Security

  • Never commit API keys, tokens, or secrets
  • Use placeholders like <<YOUR_API_KEY>> or <<PLACEHOLDER>> in config examples
  • Use environment variables, user secrets, or key vaults for sensitive data

Sample Documentation Standards

Each sample SHOULD have:

  1. README.md with:
    • What the sample demonstrates
    • Prerequisites (runtime version, API keys, tools)
    • Configuration section with example config snippets
    • How to run instructions
    • Testing options (Playground, WebChat, Teams/M365)
    • Troubleshooting section
  2. Agent Code Walkthrough (optional but recommended)
  3. manifest/ folder with:
    • manifest.json (Teams app manifest)
    • color.png (192x192 icon)
    • outline.png (32x32 icon)

Technology Stack

Component C#/.NET Python Node.js/TypeScript
HTTP Server ASP.NET Core aiohttp/FastAPI Express.js
LLM Client Azure.AI.OpenAI openai/anthropic @openai/agents
Observability OpenTelemetry OpenTelemetry OpenTelemetry
Agent 365 SDK Microsoft.Agents.* microsoft_agents.* @microsoft/agents-*

Additional Documentation

For language-specific design patterns, see:

Official Documentation