# microsoft/agents-for-net architecture

> Architecture diagram of the GitHub repository microsoft/agents-for-net, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/agents-for-net
- Repository: https://github.com/microsoft/agents-for-net

## Overview

##### Project Type & Purpose
- This is a multi-package .NET SDK (not a single executable) designed to help developers build enterprise-grade “agents” (bots/workflows) that run on M365, Teams, Copilot Studio, Webchat, and third-party channels.
- It delivers a layered set of NuGet libraries (core, auth, builder, client, hosting, storage, extensions) plus samples and tests.

##### High-Level Layers & Main Components
● Core Foundation
– Microsoft.Agents.Core & Microsoft.Agents.Core.Analyzers
· Models (Activity, Card, Conversation, etc.)
· Serialization & converters (ProtocolJsonSerializer, source generators)
· Telemetry & validation
● Authentication
– Microsoft.Agents.Authentication (interfaces, connection settings)
– Microsoft.Agents.Authentication.Msal (MSAL provider, HTTP client factory)
● Builder & Dialog Engine
– Microsoft.Agents.Builder (agent host, middleware pipeline, state management)
– Microsoft.Agents.Builder.Dialogs (DialogContainer, Prompts, WaterfallDialog)
● Client & Connector
– Microsoft.Agents.Client (IAgentClient, streaming responses)
– Microsoft.Agents.Connector (REST clients for conversations, attachments, tokens)
– Microsoft.Agents.CopilotStudio.Client (Copilot Studio API wrapper)
● Hosting Adapters
– Microsoft.Agents.Hosting.AspNetCore (ASP.NET Core adapter, controllers, background queue)
– Microsoft.Agents.Hosting.A2A (agent-to-agent JSON-RPC protocol adapter)
● Storage & Transcript
– Microsoft.Agents.Storage (IStorage abstractions)
· MemoryStorage
· Blob storage (Azure Blob)
· Cosmos DB partitioned storage
– Microsoft.Agents.Storage.Transcript (ITranscriptStore, file & blob transcript stores)
● Channel & AI Extensions
– Microsoft.Agents.Extensions.SharePoint
– Microsoft.Agents.Extensions.Teams
– Microsoft.Agents.Extensions.Teams.AI (LLM clients, tools & planner modules)

##### Relationships & Interactions
- Layered dependency:
Samples → Extensions/Hosting → Client/Connector → Builder/Dialog → Auth → Core
- Storage modules plug into Builder via DI (IStorage, ITranscriptStore).
- Hosting adapters (AspNetCore/A2A) receive incoming HTTP or JSON-RPC, call into Builder.
- Builder uses Auth to acquire tokens, then uses Connector/Client to call external channels or Copilot Studio.
- Extensions augment the Builder pipeline to handle channel-specific events (Teams messages, SharePoint actions) or AI workflows.

##### Architectural Patterns & Principles
- Layered architecture (Core → Auth → Builder → Client → Hosting/Extensions)
- Dependency injection (IServiceCollection extensions in every module)
- Adapter pattern (IChannelAdapter implementations for Webchat, Teams, A2A)
- Middleware pipeline for cross-cutting concerns (logging, error handling, header propagation)
- Source generators for high-performance serialization (analyzers)
- Package-per-component monorepo with shared Directory.Build.props & global.json

##### Technologies & External Services
- .NET 7 (global.json)
- Azure AD / MSAL for authentication
- Azure Blob & Cosmos DB for storage
- Microsoft Graph / Teams API / SharePoint REST
- Azure OpenAI & Azure Content Safety
- JSON-RPC for A2A
- NuGet for package distribution

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Foundation
    subgraph "Core Foundation"
        direction TB
        Core["Microsoft.Agents.Core"]:::core
        Analyzers["Microsoft.Agents.Core.Analyzers"]:::core
    end

    %% Authentication
    subgraph "Authentication"
        direction TB
        AuthCore["Microsoft.Agents.Authentication"]:::auth
        AuthMsal["Microsoft.Agents.Authentication.Msal"]:::auth
    end

    %% Builder & Dialog Engine
    subgraph "Builder & Dialog Engine"
        direction TB
        Builder["Microsoft.Agents.Builder"]:::builder
        Dialogs["Microsoft.Agents.Builder.Dialogs"]:::builder
    end

    %% Client & Connector
    subgraph "Client & Connector"
        direction TB
        Client["Microsoft.Agents.Client"]:::client
        Connector["Microsoft.Agents.Connector"]:::client
        CopilotClient["Microsoft.Agents.CopilotStudio.Client"]:::client
    end

    %% Hosting Adapters
    subgraph "Hosting Adapters"
        direction TB
        AspNetCore["Microsoft.Agents.Hosting.AspNetCore"]:::hosting
        A2A["Microsoft.Agents.Hosting.A2A"]:::hosting
    end

    %% Storage & Transcript
    subgraph "Storage & Transcript"
        direction TB
        StorageCore["Microsoft.Agents.Storage"]:::storage
        MemStorage["MemoryStorage"]:::storage
        BlobStorage["Azure Blob Storage"]:::storage
        CosmosStorage["Cosmos DB Storage"]:::storage
        Transcript["Transcript Stores"]:::storage
    end

    %% Extensions
    subgraph "Channel & AI Extensions"
        direction TB
        SharePointExt["Microsoft.Agents.Extensions.SharePoint"]:::ext
        TeamsExt["Microsoft.Agents.Extensions.Teams"]:::ext
        TeamsAI["Microsoft.Agents.Extensions.Teams.AI"]:::ext
    end

    %% Samples
    Samples["Sample Apps & Tests"]:::samples

    %% External Services
    AzureAD(("Azure AD / MSAL")):::external
    AzureGraph(("Microsoft Graph / Teams API")):::external
    SharePointAPI(("SharePoint REST API")):::external
    AzureAI(("Azure OpenAI / Content Safety")):::external
    CopilotStudio(("Copilot Studio API")):::external

    %% Dependencies & Flows
    Analyzers -->|analyzers| Core
    AuthCore -->|depends on| Core
    AuthMsal -->|implements MSAL| AuthCore
    Builder -->|DI & pipeline| AuthCore
    Dialogs -->|extends| Builder
    Client -->|IAgentClient| Builder
    Connector -->|REST| Client
    CopilotClient -->|wrapps| CopilotStudio
    AspNetCore -->|calls| Builder
    A2A -->|JSON-RPC| Builder
    Builder -->|IStorage, ITranscriptStore| StorageCore
    StorageCore -->|in-memory| MemStorage
    StorageCore -->|blobs| BlobStorage
    StorageCore -->|cosmos| CosmosStorage
    StorageCore -->|transcript| Transcript
    Builder -->|plug-in| SharePointExt
    Builder -->|plug-in| TeamsExt
    Builder -->|plug-in| TeamsAI
    Samples -->|uses| SharePointExt
    Samples -->|uses| AspNetCore
    Samples -->|uses| Client
    Samples -->|uses| Builder

    %% External Integration
    AuthMsal -->|auth| AzureAD
    AspNetCore -->|calls| AzureGraph
    SharePointExt -->|calls| SharePointAPI
    TeamsExt -->|calls| AzureGraph
    TeamsAI -->|calls| AzureAI
    CopilotClient -->|calls| CopilotStudio

    %% Click Events
    click Core "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Core/Microsoft.Agents.Core"
    click Analyzers "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Core/Microsoft.Agents.Core.Analyzers"
    click AuthCore "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Core/Microsoft.Agents.Authentication"
    click AuthMsal "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Authentication/Authentication.Msal"
    click Builder "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Builder/Microsoft.Agents.Builder"
    click Dialogs "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Builder/Microsoft.Agents.Builder.Dialogs"
    click Client "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Client/Microsoft.Agents.Client"
    click Connector "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Client/Microsoft.Agents.Connector"
    click CopilotClient "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Client/Microsoft.Agents.CopilotStudio.Client"
    click AspNetCore "https://github.com/microsoft/agents-for-net/tree/main/src/libraries/Hosting/AspNetCore"
    click A2A "https://github.com/microsoft/agents-for-net/tree/main/src/libraries/Hosting/A2A"
    click StorageCore "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Storage/Microsoft.Agents.Storage"
    click BlobStorage "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Storage/Microsoft.Agents.Storage.Blobs"
    click CosmosStorage "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Storage/Microsoft.Agents.Storage.CosmosDb"
    click Transcript "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Storage/Microsoft.Agents.Storage.Transcript"
    click SharePointExt "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Extensions/Microsoft.Agents.Extensions.SharePoint"
    click TeamsExt "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Extensions/Microsoft.Agents.Extensions.Teams"
    click TeamsAI "https://github.com/microsoft/agents-for-net/blob/main/src/libraries/Extensions/Microsoft.Agents.Extensions.Teams.AI"

    %% Styles
    classDef core fill:#dddddd,stroke:#888888
    classDef auth fill:#cce5ff,stroke:#3399ff
    classDef builder fill:#d4edda,stroke:#28a745
    classDef client fill:#ffe5b4,stroke:#ff9900
    classDef hosting fill:#e5d4f3,stroke:#800080
    classDef storage fill:#e2c1a2,stroke:#a0522d
    classDef ext fill:#fff3cd,stroke:#ffcd00
    classDef samples fill:#ffffff,stroke:#cccccc
    classDef external fill:#cceeff,stroke:#3399ff,stroke-dasharray: 5 5
```
