# microsoft/agentic-ai-lab-dotnet architecture

> Architecture diagram of the GitHub repository microsoft/agentic-ai-lab-dotnet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/agentic-ai-lab-dotnet
- Repository: https://github.com/microsoft/agentic-ai-lab-dotnet

## Overview

1. **Repository role**
   - This is not a single application; it is a **hands-on Azure AI Foundry lab**. The repo combines instructional notebooks, small runnable samples, and Terraform infrastructure so learners can deploy Azure AI resources and then exercise them from local code.

2. **Primary layout**
   - The repository is organized as **progressive learning modules**: setup, chat/RAG, agents, MCP, and Agent Framework. The remaining phases in the README are mostly planned or future lab areas.
   - The main architectural boundary is between **documentation/notebooks** and **deployable runtime code/infrastructure**.

3. **Execution surfaces**
   - Most examples run in **Jupyter notebooks / Polyglot notebooks** and are intended to be executed interactively from a developer machine.
   - The main code-based runtime samples are in:
     - `3. agents/azure-function/` for an Azure Functions integration
     - `4. agents-with-mcp/` for MCP client/server samples
     - `6. agent-framework/` for more advanced Agent Framework samples, including notebooks and a small dev UI helper

4. **Core cloud dependency: Azure AI Foundry**
   - The repo centers on **Azure AI Foundry projects and model deployments**.
   - Foundry provides the chat/completion models, embeddings, hosted agent capabilities, and project-scoped connections used across the labs.
   - The local `.env` file is the main bridge from notebook/code to cloud endpoints and resource identifiers.

5. **Infrastructure-as-code layer**
   - The `infrastructure/` folder is a Terraform-based provisioning layer.
   - It creates or wires up the supporting Azure resources: resource group, Foundry project, models, Azure OpenAI, Search, Storage, Bing grounding, identities, role assignments, logging, and related connections.
   - This layer is the foundation for the labs; it establishes the cloud-side dependencies before any notebook runs.

6. **Data and retrieval flow**
   - The RAG and search labs follow a common path: **local prompt or notebook input → Azure embedding/model endpoint → retrieval layer or search service → grounded answer generation**.
   - The repository includes sample files for retrieval and grounding scenarios, such as PDFs, text, JSON, and other resources under the agent-framework sample area.

7. **Agent tooling flow**
   - The `3. agents/` notebooks demonstrate how an Azure AI agent can call tools such as:
     - file search
     - Bing grounding
     - Azure Functions
     - Azure AI Search
     - multi-agent collaboration
   - This section is where the repo shifts from basic chat/RAG into **tool-using autonomous behavior**.

8. **Azure Functions boundary**
   - `3. agents/azure-function/` is a small .NET 10 Azure Functions project used as a **serverless tool endpoint** for agents.
   - It acts as an external callable boundary: the agent invokes the function, and the function returns a typed response object (`FooReply.cs`).

9. **MCP architecture sample**
   - `4. agents-with-mcp/` contains a **client/server split** for Model Context Protocol.
   - The MCP server exposes tools dynamically; the client consumes them through an interactive chat experience.
   - This section introduces a second integration model beyond direct tool/function calling: **tool discovery via protocol**.

10. **Agent Framework subsystem**
    - `6. agent-framework/` is the most expansive code area and demonstrates the newer Microsoft Agent Framework.
    - It is organized into capabilities rather than applications: Azure AI agents, MCP, workflows, middleware, context providers, threading, observability, and a dev UI.
    - The architecture here emphasizes **agent lifecycle management, workflow orchestration, and message/thread persistence**.

11. **State, memory, and threading**
    - Several samples focus on **conversation state as a first-class concern**:
      - service-managed threads
      - custom message stores
      - Redis-backed message storage
      - suspend/resume patterns
    - This separates transient notebook execution from persistent conversation context.

12. **Observability and quality boundary**
    - The repo includes observability examples that trace LLM calls, tool usage, and token consumption into **Application Insights**.
    - This is the operational layer for understanding what the agent or model is doing, separate from the interaction layer.

13. **Local configuration and secrets**
    - Root-level `.env` plus `.env.example` are the main local configuration mechanism.
    - Notebook and sample code assume environment-driven configuration rather than hard-coded endpoints, which keeps the repo portable across Azure subscriptions and lab setups.

14. **Diagramming takeaway**
    - An accurate architecture diagram should show:
      - **Local developer workstation / notebook runtime**
      - **Terraform provisioning layer**
      - **Azure AI Foundry project and connected Azure services**
      - **Specialized integration paths** for Functions, Search, Bing, MCP, and Agent Framework
      - **Sample data assets** feeding RAG, file search, and agent scenarios
      - **Telemetry/observability sink** for traces and usage metrics

Main entry points: [`3. agents`](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/HEAD/3.%20agents) (Agents labs), [`6. agent-framework/agents/azure_ai_agents`](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/HEAD/6.%20agent-framework/agents/azure_ai_agents) (AI agents), [`infrastructure/main.tf`](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/main.tf) (Terraform), [`README.md`](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/README.md) (Lab guide)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local lab"]
  node_readme["Lab guide<br/>docs<br/>[README.md]"]
  node_setup_nb["Setup notebook<br/>[quick_start.ipynb]"]
end

subgraph group_infra["Provisioning"]
  node_tf_main["Terraform<br/>IaC<br/>[main.tf]"]
  node_tf_foundry["Foundry project<br/>IaC<br/>[foundry_project.tf]"]
  node_tf_models["Models<br/>IaC<br/>[foundry_models.tf]"]
  node_tf_connections["Connections<br/>IaC"]
  node_tf_search["Search<br/>IaC<br/>[search.tf]"]
  node_tf_storage[("Storage<br/>IaC<br/>[storage.tf]")]
  node_tf_openai["Azure OpenAI<br/>IaC<br/>[azure_openai.tf]"]
  node_tf_bing["Bing grounding<br/>IaC<br/>[bing_grounding.tf]"]
end

subgraph group_cloud["Azure services"]
  node_foundry[("AI Foundry<br/>cloud project")]
  node_openai(("Model endpoint<br/>cloud model"))
  node_search[("Search service<br/>cloud retrieval")]
  node_storage[("Blob storage<br/>cloud storage")]
  node_bing(("Bing grounding<br/>cloud tool"))
end

subgraph group_samples["Samples"]
  node_chat_rag["Chat & RAG<br/>notebooks<br/>[2. chat-rag]"]
  node_agents_nb["Agents labs<br/>notebooks<br/>[3. agents]"]
  node_func_sample["Function tool<br/>.NET Azure Function<br/>[azure-function]"]
  node_mcp_sample["MCP sample<br/>client/server<br/>[4. agents-with-mcp]"]
end

subgraph group_agentfw["Agent Framework"]
  node_af_root["Agent Framework<br/>solution<br/>[6. agent-framework]"]
  node_af_agents["AI agents<br/>notebooks<br/>[azure_ai_agents]"]
end

subgraph group_data["Sample data"]
  node_af_resources["Resources<br/>sample data<br/>[resources]"]
end

subgraph group_ops["Observability"]
  node_logs(("App Insights<br/>telemetry<br/>[logging.tf]"))
end

node_readme -->|"starts with"| node_setup_nb
node_readme -->|"guides"| node_chat_rag
node_readme -->|"guides"| node_agents_nb
node_readme -->|"includes"| node_af_root
node_setup_nb -->|"connects to"| node_foundry
node_chat_rag -->|"calls"| node_openai
node_chat_rag -->|"retrieves from"| node_search
node_agents_nb -->|"uses"| node_foundry
node_agents_nb -->|"grounds with"| node_bing
node_agents_nb -->|"invokes"| node_func_sample
node_agents_nb -->|"uses"| node_search
node_agents_nb -->|"demonstrates"| node_mcp_sample
node_func_sample -.->|"tool data"| node_openai
node_mcp_sample -->|"integrates with"| node_foundry
node_af_root -->|"contains"| node_af_agents
node_af_agents -->|"reads"| node_af_resources
node_af_agents -->|"uses"| node_foundry
node_af_agents -->|"retrieves from"| node_search
node_af_agents -->|"grounds with"| node_bing
node_tf_main -->|"provisions"| node_tf_foundry
node_tf_main -->|"provisions"| node_tf_openai
node_tf_main -->|"provisions"| node_tf_search
node_tf_main -->|"provisions"| node_tf_storage
node_tf_main -->|"provisions"| node_tf_bing
node_tf_foundry -->|"creates"| node_foundry
node_tf_openai -->|"creates"| node_openai
node_tf_search -->|"creates"| node_search
node_tf_storage -->|"creates"| node_storage
node_tf_bing -->|"enables"| node_bing
node_tf_connections -->|"wires"| node_foundry
node_tf_models -->|"deploys"| node_openai
node_chat_rag -.->|"can emit"| node_logs
node_agents_nb -.->|"can emit"| node_logs
node_af_agents -.->|"observes"| node_logs

click node_readme "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/README.md"
click node_setup_nb "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/1. initial-setup/quick_start.ipynb"
click node_chat_rag "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/2. chat-rag"
click node_agents_nb "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/3. agents"
click node_func_sample "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/3. agents/azure-function"
click node_mcp_sample "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/4. agents-with-mcp"
click node_af_root "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/6. agent-framework"
click node_af_agents "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/6. agent-framework/agents/azure_ai_agents"
click node_af_resources "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/6. agent-framework/agents/azure_ai_agents/resources"
click node_tf_main "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/main.tf"
click node_tf_foundry "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/foundry_project.tf"
click node_tf_models "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/foundry_models.tf"
click node_tf_connections "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/foundry_connections.tf"
click node_tf_search "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/search.tf"
click node_tf_storage "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/storage.tf"
click node_tf_openai "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/azure_openai.tf"
click node_tf_bing "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/bing_grounding.tf"
click node_logs "https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/logging.tf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_setup_nb,node_logs toneBlue
class node_tf_main,node_tf_foundry,node_tf_models,node_tf_connections,node_tf_search,node_tf_storage,node_tf_openai,node_tf_bing toneAmber
class node_foundry,node_openai,node_search,node_storage,node_bing toneMint
class node_chat_rag,node_agents_nb,node_func_sample,node_mcp_sample toneRose
class node_af_root,node_af_agents toneIndigo
class node_af_resources toneTeal
```

## Components

### Local lab

Developer workstation, notebooks, and sample entry points

- [Lab guide](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/README.md): docs · Top-level repository guidance and learning path · `README.md`
- [Setup notebook](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/HEAD/1.%20initial-setup/quick_start.ipynb): notebook · Initial environment and access setup · `1. initial-setup/quick_start.ipynb`

### Provisioning

Terraform layer that creates Azure dependencies

- [Terraform](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/main.tf): IaC · Provisioning entry point for the lab environment · `infrastructure/main.tf`
- [Foundry project](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/foundry_project.tf): IaC · Creates the Azure AI Foundry project boundary · `infrastructure/foundry_project.tf`
- [Models](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/foundry_models.tf): IaC · Model and deployment configuration · `infrastructure/foundry_models.tf`
- [Connections](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/foundry_connections.tf): IaC · Project-scoped connections and wiring · `infrastructure/foundry_connections.tf`
- [Search](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/search.tf): IaC · Azure AI Search provisioning · `infrastructure/search.tf`
- [Storage](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/storage.tf): IaC · Storage resources for lab content and state · `infrastructure/storage.tf`
- [Azure OpenAI](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/azure_openai.tf): IaC · OpenAI resource wiring for model access · `infrastructure/azure_openai.tf`
- [Bing grounding](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/bing_grounding.tf): IaC · Grounding configuration for web-connected tools · `infrastructure/bing_grounding.tf`

### Azure services

Foundry project and connected Azure resources

- **AI Foundry**: cloud project · Central hosted project used by notebooks and agents
- **Model endpoint**: cloud model · Chat and embedding model runtime
- **Search service**: cloud retrieval · Retrieval backend for RAG and file search
- **Blob storage**: cloud storage · Cloud storage for assets and persistence
- **Bing grounding**: cloud tool · External grounding source for agent answers

### Samples

Progressive learning modules and runtime integrations

- [Chat & RAG](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/HEAD/2.%20chat-rag): notebooks · Basic chat, embeddings, and retrieval labs · `2. chat-rag`
- [Agents labs](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/HEAD/3.%20agents): notebooks · Core agent exercises from basics through tool use · `3. agents`
- [Function tool](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/HEAD/3.%20agents/azure-function): .NET Azure Function · Serverless tool endpoint used by agent samples · `3. agents/azure-function`
- [MCP sample](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/HEAD/4.%20agents-with-mcp): client/server · Model Context Protocol client and server demonstration · `4. agents-with-mcp`

### Agent Framework

Advanced agent framework samples and supporting assets

- [Agent Framework](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/HEAD/6.%20agent-framework): solution · Main Agent Framework sample area · `6. agent-framework`
- [AI agents](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/HEAD/6.%20agent-framework/agents/azure_ai_agents): notebooks · Azure AI Agents notebooks within the framework area · `6. agent-framework/agents/azure_ai_agents`

### Sample data

Documents and structured files used by retrieval and file-search labs

- [Resources](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/HEAD/6.%20agent-framework/agents/azure_ai_agents/resources): sample data · Documents and structured inputs for agent demos · `6. agent-framework/agents/azure_ai_agents/resources`

### Observability

Tracing and telemetry for agent and model behavior

- [App Insights](https://github.com/microsoft/agentic-ai-lab-dotnet/blob/main/infrastructure/logging.tf): telemetry · Tracing and usage telemetry sink · `infrastructure/logging.tf`

## Connections

- Lab guide → Setup notebook: starts with · Introduces the lab flow
- Lab guide → Chat & RAG: guides · Moves from setup into chat and RAG
- Lab guide → Agents labs: guides · Continues into agent labs
- Lab guide → Agent Framework: includes · Points to the Agent Framework area
- Setup notebook → AI Foundry: connects to · Uses environment-driven project settings
- Chat & RAG → Model endpoint: calls · Runs chat and embedding requests
- Chat & RAG → Search service: retrieves from · Grounds answers with search when needed
- Agents labs → AI Foundry: uses · Agent labs run against the hosted project
- Agents labs → Bing grounding: grounds with · Uses web grounding in agent workflows
- Agents labs → Function tool: invokes · Calls Azure Functions as a tool boundary
- Agents labs → Search service: uses · Demonstrates AI Search-backed agent tools
- Agents labs → MCP sample: demonstrates · Introduces protocol-based tool discovery
- Function tool → Model endpoint: tool data · Receives or forwards typed tool inputs and outputs
- MCP sample → AI Foundry: integrates with · Consumes model-backed chat experience
- Agent Framework → AI agents: contains · Main framework notebooks live here
- AI agents → Resources: reads · Uses documents and structured files as inputs
- AI agents → AI Foundry: uses · Runs against Azure AI Agents capabilities
- AI agents → Search service: retrieves from · File search and retrieval examples
- AI agents → Bing grounding: grounds with · Bing grounding samples in the framework area
- Terraform → Foundry project: provisions · Entry point into Azure resource creation
- Terraform → Azure OpenAI: provisions · Wires model services
- Terraform → Search: provisions · Creates retrieval infrastructure
- Terraform → Storage: provisions · Creates supporting storage
- Terraform → Bing grounding: provisions · Configures grounding dependencies
- Foundry project → AI Foundry: creates · Defines the hosted lab project boundary
- Azure OpenAI → Model endpoint: creates · Provides chat and embedding endpoints
- Search → Search service: creates · Provides retrieval service
- Storage → Blob storage: creates · Provides persistence for assets and state
- Bing grounding → Bing grounding: enables · Configures external grounding access
- Connections → AI Foundry: wires · Adds project-scoped service connections
- Models → Model endpoint: deploys · Maps model deployments into the project
- Chat & RAG → App Insights: can emit · Notebook runs may trace to telemetry
- Agents labs → App Insights: can emit · Agent tool usage and tokens can be traced
- AI agents → App Insights: observes · Framework samples include tracing and metrics
