How microsoft/agentic-ai-lab-dotnet works
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 Agents labs · azure_ai_agents AI agents · main.tf Terraform · README.md Lab guide
Components 23
Local lab
Developer workstation, notebooks, and sample entry points
- Lab guide · Top-level repository guidance and learning path
README.md - Setup notebook · Initial environment and access setup
1. initial-setup/quick_start.ipynb
Provisioning
Terraform layer that creates Azure dependencies
- Terraform · Provisioning entry point for the lab environment
infrastructure/main.tf - Foundry project · Creates the Azure AI Foundry project boundary
infrastructure/foundry_project.tf - Models · Model and deployment configuration
infrastructure/foundry_models.tf - Connections · Project-scoped connections and wiring
infrastructure/foundry_connections.tf - Search · Azure AI Search provisioning
infrastructure/search.tf - Storage · Storage resources for lab content and state
infrastructure/storage.tf - Azure OpenAI · OpenAI resource wiring for model access
infrastructure/azure_openai.tf - Bing grounding · Grounding configuration for web-connected tools
infrastructure/bing_grounding.tf
Azure services
Foundry project and connected Azure resources
- AI Foundry · Central hosted project used by notebooks and agents
- Model endpoint · Chat and embedding model runtime
- Search service · Retrieval backend for RAG and file search
- Blob storage · Cloud storage for assets and persistence
- Bing grounding · External grounding source for agent answers
Samples
Progressive learning modules and runtime integrations
- Chat & RAG · Basic chat, embeddings, and retrieval labs
2. chat-rag - Agents labs · Core agent exercises from basics through tool use
3. agents - Function tool · Serverless tool endpoint used by agent samples
3. agents/azure-function - MCP sample · Model Context Protocol client and server demonstration
4. agents-with-mcp
Agent Framework
Advanced agent framework samples and supporting assets
- Agent Framework · Main Agent Framework sample area
6. agent-framework - AI agents · 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 · 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 · Tracing and usage telemetry sink
infrastructure/logging.tf
Connections 34
- 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