Merge pull request #65 from Azure-Samples/feature/migrate-to-agent-framework

Feature/migrate to agent framework

Author: dbarkol

.gitignore

@@ -47,9 +47,14 @@ appsettings.json
 .env.*.local
 .azure/
 
+# Azurite storage emulator files
 __azurite_db_blob__.json
-
 __azurite_db_blob_extent__.json
-
+__azurite_db_queue__.json
+__azurite_db_queue_extent__.json
+__azurite_db_table__.json
 __blobstorage__/
+__queuestorage__/
+AzuriteConfig
+
 src/nohup.out

LOCAL_DEVELOPMENT.md

@@ -2,6 +2,159 @@
 
 This document explains how local development authentication works for this Azure Functions project.
 
+## Quick Start
+
+### Option A: With Docker (Recommended)
+
+The fastest way to get started is using Docker Compose:
+
+```bash
+# Start both Azurite and DTS emulator
+docker compose up -d
+
+# Generate local settings from your Azure environment
+./scripts/generate-settings.sh
+
+# Run the Functions app
+cd src
+func start
+```
+
+**Dashboard URLs:**
+
+- DTS Dashboard: <http://localhost:8082/>
+- Azurite Blob: <http://localhost:10000/>
+
+To stop the emulators:
+
+```bash
+docker compose down
+```
+
+### Option B: Without Docker - Native Azurite + Azure Storage Backend
+
+If Docker is not available, you can use native Azurite and Azure Storage for Durable Functions:
+
+```bash
+# 1. Install Azurite globally via npm
+npm install -g azurite
+
+# 2. Start Azurite in a separate terminal
+azurite
+
+# 3. Temporarily switch to Azure Storage backend (see configuration below)
+
+# 4. Generate local settings
+./scripts/generate-settings.sh
+
+# 5. Run the Functions app
+cd src
+func start
+```
+
+**Configuration changes for Azure Storage backend:**
+
+Temporarily update `src/host.json` durableTask section:
+
+```json
+"durableTask": {
+  "hubName": "%TASKHUB_NAME%",
+  "storageProvider": {
+    "type": "azureStorage",
+    "connectionStringName": "AzureWebJobsStorage"
+  },
+  "tracing": {
+    "traceInputsAndOutputs": true
+  }
+}
+```
+
+Your `local.settings.json` should have:
+
+```json
+{
+  "Values": {
+    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
+    "TASKHUB_NAME": "default"
+  }
+}
+```
+
+**Note:** This approach uses Azure Storage (via Azurite) instead of DTS for orchestration state. You won't have the DTS dashboard, but all Durable Functions features will work.
+
+### Switching Between Backends
+
+Use the provided helper script to easily switch between DTS and Azure Storage:
+
+```bash
+# Switch to Azure Storage (for environments without Docker)
+./scripts/switch-storage-backend.sh azureStorage
+
+# Switch back to DTS (when Docker is available)
+./scripts/switch-storage-backend.sh dts
+```
+
+PowerShell:
+
+```powershell
+# Switch to Azure Storage
+.\scripts\switch-storage-backend.ps1 azureStorage
+
+# Switch to DTS
+.\scripts\switch-storage-backend.ps1 dts
+```
+
+The script automatically updates your `host.json` configuration and provides instructions for the required environment setup.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+1. **Docker** installed for running the Durable Task Scheduler emulator
+2. **Azurite** installed for local Azure Storage emulation
+3. **Azure CLI** installed and configured
+
+## Durable Task Scheduler Setup
+
+This project uses the **Durable Task Scheduler** (DTS) for orchestration instead of Azure Storage. For local development, you need to run the DTS emulator.
+
+### 1. Start the DTS Emulator
+
+Pull and run the DTS emulator Docker container:
+
+```bash
+# Pull the emulator image
+docker pull mcr.microsoft.com/dts/dts-emulator:latest
+
+# Run the emulator (exposes ports 8080 for gRPC and 8082 for dashboard)
+docker run -d -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest
+```
+
+The emulator exposes two ports:
+- **8080**: gRPC endpoint for the Functions app to connect
+- **8082**: Dashboard UI at http://localhost:8082/
+
+### 2. Start Azurite
+
+The Azure Functions runtime still requires Azurite for some components:
+
+```bash
+azurite start
+```
+
+### 3. Verify Configuration
+
+Check that your `local.settings.json` includes these DTS-specific settings:
+
+```json
+{
+  "Values": {
+    "DTS_CONNECTION_STRING": "Endpoint=http://localhost:8080;Authentication=None",
+    "TASKHUB_NAME": "default"
+  }
+}
+```
+
 ## Authentication Approach
 
 This project uses **Azure Managed Identity** for authentication - both in production AND for local development. **No API keys are required!**
@@ -64,6 +217,16 @@ func start
 
 The Azure Functions runtime will automatically use your Azure credentials via `DefaultAzureCredential`.
 
+### 5. Monitor Orchestrations
+
+You can monitor orchestration instances in real-time using the DTS dashboard:
+
+1. Open <http://localhost:8082/> in your browser
+2. Click on your task hub (default: **default**)
+3. View orchestration status, history, and execution details
+
+**Note**: The DTS emulator stores data in memory, so all orchestration data is lost when the container stops.
+
 ## Benefits of This Approach
 
 ✅ **No secrets to manage** - No API keys in config files or environment variables  

README.md

@@ -182,6 +182,59 @@ azd down --purge
 
 > **Note**: The first run automatically creates an Azure AD app registration with OAuth2 scope `access_as_user` for authentication.
 
+### Local Development with Emulators
+
+For local development, Snippy uses the **Durable Task Scheduler (DTS) emulator** and **Azurite** for storage. 
+
+#### With Docker (Recommended)
+
+The easiest way to run both emulators:
+
+```bash
+# Start both emulators
+docker compose up -d
+
+# Generate local.settings.json from your Azure environment
+./scripts/generate-settings.sh
+
+# Run the Functions app
+cd src
+func start
+```
+
+**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
+
+# 2. Switch to Azure Storage backend
+./scripts/switch-storage-backend.sh azureStorage
+
+# 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:
+
+```bash
+./scripts/switch-storage-backend.sh dts
+```
+
+For detailed setup instructions and troubleshooting, see [LOCAL_DEVELOPMENT.md](LOCAL_DEVELOPMENT.md).
+
 ---
 
 ## Guidance

docker-compose.yml

@@ -0,0 +1,28 @@
+version: '3.8'
+
+services:
+  # Azure Storage Emulator (Azurite)
+  azurite:
+    image: mcr.microsoft.com/azure-storage/azurite:latest
+    container_name: snippy-azurite
+    ports:
+      - "10000:10000"  # Blob service
+      - "10001:10001"  # Queue service
+      - "10002:10002"  # Table service
+    volumes:
+      - azurite-data:/data
+    command: azurite --blobHost 0.0.0.0 --queueHost 0.0.0.0 --tableHost 0.0.0.0
+    restart: unless-stopped
+
+  # Durable Task Scheduler Emulator
+  dts-emulator:
+    image: mcr.microsoft.com/dts/dts-emulator:latest
+    container_name: snippy-dts-emulator
+    ports:
+      - "8080:8080"  # gRPC endpoint for Function App connection
+      - "8082:8082"  # Dashboard UI
+    restart: unless-stopped
+
+volumes:
+  azurite-data:
+    name: snippy-azurite-data

infra/app/api.bicep

@@ -76,6 +76,16 @@ module api 'br/public:avm/res/web/site:0.15.1' = {
       scaleAndConcurrency: {
         instanceMemoryMB: instanceMemoryMB
         maximumInstanceCount: maximumInstanceCount
+        alwaysReady: [
+          {
+            name: 'http'
+            instanceCount: 1
+          }
+          {
+            name: 'durable'
+            instanceCount: 1
+          }
+        ]
       }
       runtime: {
         name: runtimeName

infra/main.bicep

@@ -225,11 +225,11 @@ module api './app/api.bicep' = {
       EMBEDDING_MODEL_DEPLOYMENT_NAME: openai.outputs.embeddingDeploymentName
       AGENTS_MODEL_DEPLOYMENT_NAME: openai.outputs.chatDeploymentName
       COSMOS_VECTOR_TOP_K: '30'
-      AZURE_OPENAI_ENDPOINT: openai.outputs.aiServicesEndpoint
+      AZURE_OPENAI_ENDPOINT: openai.outputs.azureOpenAIServiceEndpoint
       PROJECT_ENDPOINT: openai.outputs.aiFoundryProjectEndpoint
       AZURE_CLIENT_ID: apiUserAssignedIdentity.outputs.clientId
       DTS_CONNECTION_STRING: 'Endpoint=${dts.outputs.dts_URL};Authentication=ManagedIdentity;ClientID=${apiUserAssignedIdentity.outputs.clientId}'
-      TASKHUBNAME: dts.outputs.TASKHUB_NAME
+      TASKHUB_NAME: dts.outputs.TASKHUB_NAME
     }
   }
   dependsOn: [

scripts/generate-settings.ps1

@@ -7,16 +7,26 @@ $cosmosEndpoint = ($envValues | Select-String 'COSMOS_ENDPOINT="([^"]*)"').Match
 $azureOpenAIEndpoint = ($envValues | Select-String 'AZURE_OPENAI_ENDPOINT="([^"]*)"').Matches.Groups[1].Value
 $projectEndpoint = ($envValues | Select-String 'PROJECT_ENDPOINT="([^"]*)"').Matches.Groups[1].Value
 $azureWebJobsStorage = ($envValues | Select-String 'AZUREWEBJOBSSTORAGE="([^"]*)"').Matches.Groups[1].Value
+$dtsUrl = ($envValues | Select-String 'DTS_URL="([^"]*)"').Matches.Groups[1].Value
+$taskhubName = ($envValues | Select-String 'TASKHUB_NAME="([^"]*)"').Matches.Groups[1].Value
+
+# Use default taskhub name if not found
+if ([string]::IsNullOrEmpty($taskhubName)) {
+    $taskhubName = "SnippyTaskHub"
+}
 
 # Create or update local.settings.json
 Write-Host "Generating local.settings.json in src directory..."
 $settingsJson = @"
 {
   "IsEncrypted": false,
   "Values": {
+    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
     "AzureWebJobsSecretStorageType": "files",
     "FUNCTIONS_WORKER_RUNTIME": "python",
     "PYTHON_ENABLE_WORKER_EXTENSIONS": "True",
+    "DTS_CONNECTION_STRING": "Endpoint=http://localhost:8080;Authentication=None",
+    "TASKHUB_NAME": "default",
     "COSMOS_DATABASE_NAME": "dev-snippet-db",
     "COSMOS_CONTAINER_NAME": "code-snippets",
     "BLOB_CONTAINER_NAME": "snippet-backups",
@@ -34,7 +44,14 @@ $settingsJson | Out-File -FilePath "src/local.settings.json" -Encoding utf8
 Write-Host ""
 Write-Host "✅ local.settings.json generated successfully!" -ForegroundColor Green
 Write-Host ""
-Write-Host "📝 Note: This configuration uses Azure credential authentication (no API key)." -ForegroundColor Cyan
+Write-Host "📝 Note: This configuration uses:" -ForegroundColor Cyan
+Write-Host "   - Durable Task Scheduler emulator at http://localhost:8080" -ForegroundColor Cyan
+Write-Host "   - Azure credential authentication for Azure services (no API key)" -ForegroundColor Cyan
 Write-Host "   - Make sure you're logged in: az login" -ForegroundColor Cyan
 Write-Host "   - You should have been automatically assigned the 'Cognitive Services OpenAI User' role" -ForegroundColor Cyan
-Write-Host "   - If you get authentication errors, verify your role assignment in the Azure Portal" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "🐳 Before running 'func start', start the DTS emulator:" -ForegroundColor Yellow
+Write-Host "   docker compose up -d" -ForegroundColor Yellow
+Write-Host "   # Or manually: docker run -d -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest" -ForegroundColor Yellow
+Write-Host ""
+Write-Host "📊 DTS Dashboard will be available at: http://localhost:8082/" -ForegroundColor Yellow