# microsoft/msbuild-lab335-agentic-rag architecture

> Architecture diagram of the GitHub repository microsoft/msbuild-lab335-agentic-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/msbuild-lab335-agentic-rag
- Repository: https://github.com/microsoft/msbuild-lab335-agentic-rag

## Overview

##### Project type and purpose
- This repo is not an application codebase but a hands-on lab/tutorial (“Build Your First Agentic RAG Solution with Azure AI Search”).
- The goal is to guide learners through building an agent-orchestrated Retrieval-Augmented Generation (RAG) solution on Azure.

##### File structure
- Top level: README.md, SUPPORT.md, SECURITY.md, lab folder, img folder. No “src” or “backend” directories.
- “lab/” contains four exercise markdowns plus media: each exercise progressively builds RAG features (retrieval modes, semantic ranker, automated evaluation, agentic features).
- This implies the actual system design will be conceptual—mapping the target architecture learners will implement.

##### README for additional insights
- The README describes session resources, links to the Build session page and Microsoft Learn plan.
- No code; emphasis is on Azure AI Search, semantic ranking, agentic orchestration, evaluation.

- User Interface (e.g., a web client or CLI where the user submits queries)
- Agent Orchestrator (the “brain” that decides when to retrieve, ask follow-up questions, call the LLM)
- Retrieval Layer
– Azure Cognitive Search (indexes documents/media in Azure Blob Storage)
– Semantic Ranker plugin (optional semantic re-ranking service)
- Generation Layer
– Azure OpenAI Service (LLM endpoint)
- Automated Evaluation Module (optional—exercise-3)
- Data Stores
– Azure Blob Storage (raw docs, index)
– Application logs / Telemetry
- External Services
– Microsoft Learn links / Build session resources (for context, not part of runtime)

b. Relationships and interactions
1. User → UI → Agent Orchestrator
2. Orchestrator → Azure Cognitive Search (query embedding)
3. Search → returns top-k docs → optional semantic ranker → filtered docs
4. Orchestrator packages prompt + docs → Azure OpenAI → LLM response
5. If exercise-4 agentic: orchestrator may loop (follow-up retrieval → LLM) until answer complete
6. (Optional) Send response to evaluation module → feedback → logs
7. Final answer → UI → User

c. Architectural patterns & design principles
- Separation of concerns: clear layers for orchestration, retrieval, generation, evaluation
- Serverless / Microservices: each component (functions or services) can scale independently
- Event-driven loops for agentic features
- Modular extensibility: switch in/out semantic ranker, evaluation, additional retrieval modes

d. Key technologies, frameworks, libraries
- Azure Cognitive Search SDK
- Azure OpenAI SDK
- Azure Blob Storage
- (Optional) Azure Functions or Web App for orchestration
- Semantic ranking packages (e.g., Azure AI semantic ranking)
- Logging/Monitoring via Azure Application Insights

##### Final advice
- Be detailed but avoid overcomplicating: start with core RAG pipeline (retrieval + generation), then layer on semantic ranking, evaluation, agentic loop.
- Essential Azure service boundaries and how data flows through each exercise stage.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Users and Entry
    User["User"]:::external
    UI["User Interface"]:::custom
    click UI "https://github.com/microsoft/msbuild-lab335-agentic-rag/blob/main/README.md"
    User -->|"submits query"| UI

    subgraph "Lab Overview"
        Overview["Lab Overview & Setup Instructions"]:::custom
        click Overview "https://github.com/microsoft/msbuild-lab335-agentic-rag/blob/main/lab/README.md"
    end
    UI --> Overview

    %% Core RAG Pipeline
    subgraph "Core RAG Pipeline"
        direction TB
        Orchestrator["Agent Orchestrator"]:::custom
        click Orchestrator "https://github.com/microsoft/msbuild-lab335-agentic-rag/blob/main/lab/exercise-4-enable-agentic-features.md"

        subgraph "Retrieval Layer (Exercise 1)"
            ACS["Azure Cognitive Search"]:::azure
            click ACS "https://github.com/microsoft/msbuild-lab335-agentic-rag/blob/main/lab/exercise-1-explore-retrieval-modes.md"
        end

        subgraph "Semantic Ranker (Exercise 2)" 
            direction TB
            Ranker["Semantic Ranker"]:::optional
            click Ranker "https://github.com/microsoft/msbuild-lab335-agentic-rag/blob/main/lab/exercise-2-adjust-semantic-ranker.md"
        end

        subgraph "Generation Layer"
            OpenAI["Azure OpenAI Service"]:::azure
        end

        subgraph "Automated Evaluation (Exercise 3)"
            Eval["Automated Evaluation Module"]:::optional
            click Eval "https://github.com/microsoft/msbuild-lab335-agentic-rag/blob/main/lab/exercise-3-optional-automated-evaluation.md"
        end

        AzureBlob["Azure Blob Storage"]:::azure
        Logs["Application Logs/Telemetry"]:::azure
    end

    %% Core Pipeline Flow
    Overview --> Orchestrator
    Orchestrator -->|"vector query"| ACS
    ACS -->|"top-k docs"| Ranker
    Ranker -->|"re-ranked docs"| Orchestrator
    ACS -->|"top-k docs"| Orchestrator
    Orchestrator -->|"prompt + docs"| OpenAI
    OpenAI -->|"LLM response"| Orchestrator
    Orchestrator -->|"response"| Eval
    Eval -->|"feedback"| Logs
    Orchestrator -->|"final answer"| UI

    %% Data Stores Relationships
    AzureBlob --> ACS
    Orchestrator -->|"logs events"| Logs

    %% Supporting Resources
    subgraph "Supporting Resources"
        direction TB
        Images["Supporting Images & Diagrams"]:::external
        click Images "https://github.com/microsoft/msbuild-lab335-agentic-rag/tree/main/img/"
        Media["Media Assets Referenced in Labs"]:::external
        click Media "https://github.com/microsoft/msbuild-lab335-agentic-rag/tree/main/lab/media/"
        Wrapup["Lab Wrap-Up & Next Steps"]:::external
        click Wrapup "https://github.com/microsoft/msbuild-lab335-agentic-rag/blob/main/lab/wrap-up.md"
        Support["Session & Support Documentation"]:::external
        click Support "https://github.com/microsoft/msbuild-lab335-agentic-rag/blob/main/SUPPORT.md"
        Security["Security Docs"]:::external
        click Security "https://github.com/microsoft/msbuild-lab335-agentic-rag/blob/main/SECURITY.md"
    end

    %% Styling
    classDef azure fill:#daeaff,stroke:#0000ff;
    classDef custom fill:#e0ffe0,stroke:#008000;
    classDef optional fill:#f0f0f0,stroke:#888888,stroke-dasharray: 5 5;
    classDef external fill:#fff0b3,stroke:#ffaa00;
```
