Merge pull request #78 from Azure-Samples/docs/refresh-markdown-files

docs: refresh markdown files with Durable Agents architecture

Author: dbarkol

CHANGELOG.md

@@ -6,6 +6,21 @@
 *Features*
 * ...
 
+## 2025-11-05
+
+### Features
+* Durable Task Scheduler (DTS) integration for cloud orchestration and monitoring
+* DTS dashboard scripts for Bash and PowerShell (`scripts/get-dts-dashboard-url.sh`, `.ps1`)
+* APIM region fallback logic for BasicV2 SKU deployments
+* Major lab instructions overhaul (see `docs/lab-instructions.md`)
+
+### Bug Fixes
+* Improved error handling in DTS dashboard scripts
+* Fixed image URLs in lab instructions to reference main branch
+
+### Breaking Changes
+* Removed obsolete `docs/ignite-lab-instructions.md`
+
 *Bug Fixes*
 * ...
 

LOCAL_DEVELOPMENT.md

@@ -22,8 +22,23 @@ func start
 
 **Dashboard URLs:**
 
-- DTS Dashboard: <http://localhost:8082/>
-- Azurite Blob: <http://localhost:10000/>
+- **Local DTS Dashboard**: <http://localhost:8082/> - Monitor orchestrations running locally
+- **Azurite Blob**: <http://localhost:10000/>
+
+**Monitoring Orchestrations:**
+
+- **Local**: Open <http://localhost:8082/> to view orchestrations running against the local DTS emulator
+- **Cloud**: Generate the Azure DTS dashboard URL with the provided scripts:
+
+  ```bash
+  ./scripts/get-dts-dashboard-url.sh
+  ```
+  or
+  ```powershell
+  .\scripts\get-dts-dashboard-url.ps1
+  ```
+
+  Then open the generated URL in your browser to view orchestrations running in Azure.
 
 To stop the emulators:
 

README.md

@@ -27,16 +27,15 @@ urlFragment: snippy
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=Azure-Samples/snippy&machine=basicLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json)
 [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/Azure-Samples/snippy)
 
-Snippy is an **Azure Functions**–based reference application that turns any function into an **MCP (Model Context Protocol) tool** consumable by GitHub Copilot Chat and other MCP‑aware clients. The sample implements a production‑style *code‑snippet service* with AI‑powered analysis:
+Snippy is an **Azure Functions**-based reference application that demonstrates how to build **MCP (Model Context Protocol) tools** that integrate with AI assistants like GitHub Copilot. The sample implements an intelligent *code-snippet service* featuring:
 
-* **Save snippets** – persists code, metadata and OpenAI embeddings in **Cosmos DB DiskANN**
-* **Semantic retrieve** – vector search over embeddings
-* **AI Agents** – generate a **deep wiki** or language‑specific **code style guide** from stored snippets
-* **Durable fan‑out/fan‑in with Blueprints** – [in experimental branch](https://github.com/Azure-Samples/snippy/tree/gk/durable-functions) for large‑scale processing
-* **Microsoft Fabric integration** – [in gk/fabric branch](https://github.com/Azure-Samples/snippy/tree/gk/fabric) demonstrating how to build Agents with Fabric Data Agents
+* **MCP Tool Integration** – expose Azure Functions as discoverable tools for AI assistants
+* **Durable Agents** – create stateful AI agents using **Microsoft Agent Framework** with automatic state management
+* **Multi-Agent Orchestration** – coordinate DeepWiki and CodeStyle agents using **Durable Task Scheduler**
+* **Vector Search** – semantic retrieval using **Cosmos DB DiskANN** with Azure OpenAI embeddings
+* **Monitoring & Observability** – track orchestrations in real-time with DTS dashboard (local & cloud)
 
-
-The project ships with reproducible **azd** infrastructure, so `azd up` will stand up the entire stack – Functions, Cosmos DB, Azure OpenAI and Azure AI Agents – in a single command.
+The project ships with reproducible **azd** infrastructure, so `azd up` will stand up the entire stack – Functions, Cosmos DB, Azure OpenAI, and Durable Task Scheduler – in a single command.
 
 > **Important Security Notice**
 > This repository is intended for learning and demonstration purposes. **Do not** deploy it to production without a thorough security review. At a minimum you should:
@@ -49,22 +48,33 @@ The project ships with reproducible **azd** infrastructure, so `azd up` will st
 
 ---
 
+## Recent Updates
+
+* **Durable Task Scheduler (DTS) integration** for cloud orchestration and monitoring
+* **DTS dashboard scripts**: Quickly generate monitoring URLs for Azure deployments (`scripts/get-dts-dashboard-url.sh` and `.ps1`)
+* **Multi-agent orchestration**: Coordinate DeepWiki and CodeStyle agents with Durable Functions
+* **Enhanced monitoring**: View orchestration state in local DTS emulator or Azure DTS dashboard
+
+
 ## Features
 
-* **Remote MCP trigger** – expose Functions as real‑time SSE tools
-* **AI‑assisted documentation** – "deep‑wiki" and "code‑style" agents create rich Markdown (Mermaid, diagrams, etc.)
-* **Vector search on Cosmos DB DiskANN** – low‑latency semantic retrieval
-* **One‑click deploy** – `azd up` provisions and deploys code & infra
-* **Codespaces & Dev Containers** – fully configured dev environment in your browser or local VS Code
+* **MCP Tool Integration** – expose Azure Functions as discoverable MCP tools for AI assistants via SSE protocol
+* **Durable Agents with Microsoft Agent Framework** – build stateful AI agents using `ChatAgent` with automatic conversation history management
+* **Multi-Agent Orchestration** – coordinate specialized agents (DeepWiki, CodeStyle) using Durable Task Scheduler with fan-out/fan-in patterns
+* **Vector Search on Cosmos DB DiskANN** – semantic code retrieval using Azure OpenAI embeddings and low-latency vector indexing
+* **Monitoring & Observability** – track orchestrations in real-time using DTS dashboard (localhost:8082 local, Azure portal for cloud)
+* **One-click Deploy** – `azd up` provisions and deploys complete infrastructure including Functions, Cosmos DB, Azure OpenAI, and DTS
+* **Codespaces & Dev Containers** – fully configured development environment in your browser or local VS Code
 
 ### Tool Matrix
 
-| Tool Name      | Purpose                                                             |
-| -------------- | ------------------------------------------------------------------- |
-| `save_snippet` | Save code snippets with vector embeddings for semantic search       |
-| `get_snippet`  | Retrieve previously saved code snippets by their unique name        |
-| `code_style`   | Generate language-specific code style guides from saved snippets    |
-| `deep_wiki`    | Create comprehensive wiki documentation by analyzing code snippets  |
+| Tool Name                        | Purpose                                                             |
+| -------------------------------- | ------------------------------------------------------------------- |
+| `save_snippet`                   | Save code snippets with vector embeddings for semantic search       |
+| `get_snippet`                    | Retrieve previously saved code snippets by their unique name        |
+| `code_style`                     | Generate language-specific code style guides from saved snippets    |
+| `deep_wiki`                      | Create comprehensive wiki documentation by analyzing code snippets  |
+| `generate_comprehensive_documentation` | Orchestrate multi-agent workflow to produce deep wiki and style guide |
 
 ---
 
@@ -198,33 +208,36 @@ docker compose up -d
 ./scripts/generate-settings.sh
 
 # Run the Functions app
-cd src
-func start
+```mermaid
+flowchart LR
+  subgraph mcphosts["MCP Hosts & Clients (Your Computer)"]
+    Host["Host (VS Code / IDE)"]
+    Client["Client (GitHub Copilot)"]
+  end
+  Host --"MCP Protocol"--> Client
+  Client --"Tool Discovery"--> FunctionApp["Function App (MCP Server)"]
+  FunctionApp --"Orchestrate"--> DTS["Durable Task Scheduler"]
+  DTS --"Agent Calls"--> Agents["Durable Agents<br/>DeepWiki · CodeStyle"]
+  FunctionApp --"Vector Search"--> CosmosDB
+  Agents --"Vector Search"--> CosmosDB
+  FunctionApp --"Embeddings"--> OpenAI["Azure OpenAI"]
+  Agents --"LLM Calls"--> OpenAI
+  DTS --"Dashboard"--> User["Developer/Monitor"]
 ```
 
-**Available Dashboards:**
-
-* **DTS Dashboard**: <http://localhost:8082/> - Monitor orchestration instances, view execution history
-* **Azurite**: Runs on ports 10000-10002 for Blob, Queue, and Table services
-
-#### Without Docker
-
-If Docker is not available, you can use native Azurite with Azure Storage backend:
+---
 
-```bash
-# 1. Install Azurite globally
-npm install -g azurite
+## Monitoring & Orchestration
 
-# 2. Switch to Azure Storage backend
-./scripts/switch-storage-backend.sh azureStorage
+* **Local development**: Monitor orchestrations at <http://localhost:8082/> when using the DTS emulator
+* **Azure deployment**: Use the DTS dashboard scripts to generate monitoring URLs:
+  * Bash: `./scripts/get-dts-dashboard-url.sh`
+  * PowerShell: `.\scripts\get-dts-dashboard-url.ps1`
+* View multi-agent orchestration execution, including DeepWiki and CodeStyle agent calls
+* Track tool invocations, state transitions, and execution timelines
 
-# 3. Start Azurite in a separate terminal
-azurite
+---
 
-# 4. Generate settings and run
-./scripts/generate-settings.sh
-cd src
-func start
 ```
 
 To switch back to DTS when Docker becomes available:
@@ -243,15 +256,6 @@ For detailed setup instructions and troubleshooting, see [LOCAL_DEVELOPMENT.md](
 
 Azure OpenAI model support varies by region. Verify availability [here](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#standard-deployment-model-availability) and choose the same region for all Azure resources. **eastus** and **swedencentral** are good default choices.
 
-### Costs
-
-Estimate monthly cost using the [Azure Pricing Calculator](https://azure.microsoft.com/pricing/calculator/). Major components:
-
-* Azure Functions – Consumption / Flex tiers
-* Cosmos DB – Serverless or provisioned throughput
-* Azure OpenAI – pay‑as‑you‑go per 1K tokens
-* Azure AI Agents – per‑execution billing (preview)
-
 ### Security
 
 Snippy uses User-Assigned Managed Identity for secure service-to-service authentication. The infrastructure is configured with:
@@ -269,15 +273,6 @@ For production deployments, we recommend:
 
 ---
 
-## Resources
-
-* Blog – *Build AI agent tools using Remote MCP with Azure Functions* ([https://aka.ms/snippy-blog](https://aka.ms/snippy-blog))
-* Model Context Protocol spec – [https://aka.ms/mcp](https://aka.ms/mcp)
-* Azure Functions Remote MCP docs – [https://aka.ms/azure-functions-mcp](https://aka.ms/azure-functions-mcp)
-* Develop Python apps for Azure AI – [https://learn.microsoft.com/azure/developer/python/azure-ai-for-python-developers](https://learn.microsoft.com/azure/developer/python/azure-ai-for-python-developers)
-
----
-
 ## Contributing
 
 Standard **fork → branch → PR** workflow. Use *Conventional Commits* (`feat:`, `fix:`) in commit messages.

deep-wiki.md

@@ -1,12 +1,17 @@
 # Project Overview
 
-This project is centered around the MCP (Model Context Protocol) tools designed for use with Azure Functions and AI-powered operations. The tools enable seamless integration with Azure OpenAI, Cosmos DB, and AI Agents to manage and analyze code snippets. Key functionalities include document management, vector search, error handling, logging, and provisioned cloud infrastructure using Bicep templates.
+This project is centered around the MCP (Model Context Protocol) tools designed for use with Azure Functions and AI-powered operations. The tools enable seamless integration with Azure OpenAI, Cosmos DB, and AI Agents to manage and analyze code snippets. Key functionalities include document management, vector search, error handling, logging, provisioned cloud infrastructure using Bicep templates, and **multi-agent orchestration** with monitoring via the Durable Task Scheduler (DTS) dashboard.
+
+Recent updates include:
+* Durable Task Scheduler integration for cloud orchestration
+* DTS dashboard scripts for monitoring orchestrations in Azure (`get-dts-dashboard-url.sh` and `.ps1`)
+* Multi-agent workflows coordinating DeepWiki and CodeStyle agents
 
 ## Major Concepts
 
 ### MCP Tools
 
-MCP tools automate operations related to code snippets using triggers that respond to Azure Function events. Tools such as `save_snippet`, `get_snippet`, `deep_wiki`, and `code_style` interact with various Azure services to provide a robust solution for code documentation and analysis.
+MCP tools automate operations related to code snippets using triggers that respond to Azure Function events. Tools such as `save_snippet`, `get_snippet`, `deep_wiki`, `code_style`, and `generate_comprehensive_documentation` interact with various Azure services to provide a robust solution for code documentation, analysis, and multi-agent orchestration.
 
 ### Azure Functions
 
@@ -30,40 +35,73 @@ Azure Bicep is used to define infrastructure as code, setting up Azure resources
 
 ## Diagram Visualizations
 
+### Orchestration Monitoring
+
+Monitor orchestrations using the DTS dashboard:
+* **Local**: Open <http://localhost:8082/> when using the DTS emulator
+* **Azure**: Use the provided scripts (`get-dts-dashboard-url.sh` and `.ps1`) to generate the Azure dashboard URL
+
 ### System Architecture
 
 ```mermaid
 flowchart TB
     subgraph Azure Services
-        AzureFunctions --Triggers--> MCPTools
-        MCPTools --Stores--> CosmosDB
-        MCPTools --Generates--> AzureOpenAI
-    end
-
-    subgraph MCPTool Interaction
-        SaveSnippet --Embeds--> AzureOpenAI
-        GetSnippet --Reads--> CosmosDB
+        AzureFunctions["Azure Functions<br/>(MCP Server)"]
+        DTS["Durable Task Scheduler"]
+        Agents["Durable Agents<br/>(DeepWiki · CodeStyle)"]
+        MCPTools["MCP Tools<br/>(save_snippet, get_snippet, etc.)"]
+        CosmosDB["Cosmos DB<br/>(Vector + Operational)"]
+        AzureOpenAI["Azure OpenAI<br/>(Embeddings + LLM)"]
     end
 
-    AzureFunctions -.-> Logging
-    Logging -.-> ErrorHandling
+    AzureFunctions --> MCPTools
+    MCPTools --"Orchestrate"--> DTS
+    DTS --"Agent Calls"--> Agents
+    MCPTools --"Store/Retrieve"--> CosmosDB
+    MCPTools --"Embeddings"--> AzureOpenAI
+    Agents --"Vector Search"--> CosmosDB
+    Agents --"LLM Calls"--> AzureOpenAI
+    AzureFunctions -.-> Logging["Logging & Monitoring"]
+    Logging -.-> ErrorHandling["Error Handling"]
 ```
 
 ### Data Flow
 
 ```mermaid
 sequenceDiagram
     participant User
-    participant AzureFunctionApp
-    participant AzureOpenAI
-    participant CosmosDB
-
-    User->>AzureFunctionApp: Send Snippet
-    AzureFunctionApp->>AzureOpenAI: Generate Embeddings
-    AzureOpenAI-->>AzureFunctionApp: Return Embeddings
-    AzureFunctionApp->>CosmosDB: Store Snippet & Embeddings
-    CosmosDB-->>AzureFunctionApp: Success/Failure Response
-    AzureFunctionApp-->>User: Notify Status
+    participant Copilot as GitHub Copilot
+    participant FunctionApp as Azure Functions<br/>(MCP Server)
+    participant DTS as Durable Task Scheduler
+    participant Agent as Durable Agent
+    participant OpenAI as Azure OpenAI
+    participant Cosmos as Cosmos DB
+
+    User->>Copilot: "Save this snippet"
+    Copilot->>FunctionApp: MCP Tool: save_snippet
+    FunctionApp->>OpenAI: Generate Embeddings
+    OpenAI-->>FunctionApp: Return Embeddings
+    FunctionApp->>Cosmos: Store Snippet & Embeddings
+    Cosmos-->>FunctionApp: Success Response
+    FunctionApp-->>Copilot: Confirmation
+    Copilot-->>User: "Snippet saved"
+
+    User->>Copilot: "Generate documentation"
+    Copilot->>FunctionApp: MCP Tool: generate_comprehensive_documentation
+    FunctionApp->>DTS: Start Orchestration
+    DTS->>Agent: Call DeepWikiAgent
+    Agent->>Cosmos: Vector Search
+    Cosmos-->>Agent: Relevant Snippets
+    Agent->>OpenAI: Generate Documentation
+    OpenAI-->>Agent: Documentation Content
+    Agent-->>DTS: Return Result
+    DTS->>Agent: Call CodeStyleAgent
+    Agent->>OpenAI: Generate Style Guide
+    OpenAI-->>Agent: Style Guide Content
+    Agent-->>DTS: Return Result
+    DTS-->>FunctionApp: Orchestration Complete
+    FunctionApp-->>Copilot: Combined Results
+    Copilot-->>User: Save to File
 ```
 
 ## Snippet Catalog