diff --git a/.devcontainer/xxx-AgenticAIApps/devcontainer.json b/.devcontainer/xxx-AgenticAIApps/devcontainer.json new file mode 100644 index 0000000000..d68c02c016 --- /dev/null +++ b/.devcontainer/xxx-AgenticAIApps/devcontainer.json @@ -0,0 +1,28 @@ +{ + "name" : "xxx-AgenticAIApps", + "image": "mcr.microsoft.com/devcontainers/python:3.11", + "workspaceFolder": "/workspace/xxx-AgenticAIApps/Student/Resources", + "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached", + "hostRequirements": { + "cpus": 2 + }, + "waitFor": "onCreateCommand", + "updateContentCommand": "python3 -m pip install -r requirements.txt", + "postCreateCommand": "", + "features": { + "ghcr.io/devcontainers/features/azure-cli:1": { + "installBicep": true + } + }, + "customizations": { + "codespaces": { + "openFiles": [] + }, + "vscode": { + "extensions": [ + "ms-toolsai.jupyter", + "ms-python.python" + ] + } + } + } diff --git a/xxx-AgenticAIApps/Coach/Lectures.pptx b/xxx-AgenticAIApps/Coach/Lectures.pptx new file mode 100644 index 0000000000..34cfe52f45 Binary files /dev/null and b/xxx-AgenticAIApps/Coach/Lectures.pptx differ diff --git a/xxx-AgenticAIApps/Coach/README.md b/xxx-AgenticAIApps/Coach/README.md new file mode 100644 index 0000000000..af082db509 --- /dev/null +++ b/xxx-AgenticAIApps/Coach/README.md @@ -0,0 +1,113 @@ +# What The Hack - AgenticAIApps - Coach Guide + +## Introduction + +Welcome to the coach's guide for **AgenticAIApps**, a modern **Azure Agentic AI Hack** designed to help participants build, test, and scale intelligent multi-agent systems. +Here you will find links to specific guidance for coaches for each of the challenges. + +This hack includes an optional [lecture presentation](Lectures.pptx) that features short presentations to introduce key topics associated with each challenge. It is recommended that the host present each short presentation before attendees kick off that challenge. + +**NOTE:** If you are a Hackathon participant, this is the answer guide. Don't cheat yourself by looking at these during the hack! Go learn something. :) + +## Learning Objectives + +This project is designed to teach participants how to build agentic applications using Azure’s AI ecosystem. +Participants will orchestrate intelligent agents using Semantic Kernel, implement secure communication protocols, and deploy multi-agent workflows with live metric integration via Azure Monitor. By the end, participants will be equipped to design, deploy, and manage scalable, secure, and collaborative AI agents in real-world scenarios. + +Participants will learn to: + +- Provision and configure a Linux VM in Azure with read/write permissions +- Deploy and test **Anomaly Detector**, **Resource Optimizer**, and **Alert Manager** agents +- Orchestrate multi-agent collaboration for real-time decision-making +- Build and visualize logs locally and in Azure (via Streamlit or Power BI) +- Spike VM resources to test agent detection and resilience +- Integrate Azure tools (Monitor, Storage, and AI Foundry) for advanced observability + +--- + +## Coach's Guides + +- **Challenge 00:** [Azure AI Foundry Onboarding & Environment Prep](./Solution-00.md) + *Set up your Azure environment and validate permissions.* + +- **Challenge 01:** [Semantic Kernel Setup & Configuration](./Solution-01.md) + *Deploy a Linux VM with contributor permissions and enable SSH access.* + +- **Challenge 02:** [Build the Anomaly Detector Agent (Real Azure Metrics)](./Solution-02.md) + *Set up your environment with Python, Bash, and Azure SDKs, and create your first monitoring agent.* + +- **Challenge 03:** [Build the Resource Optimizer Agent (Real Azure Integration)](./Solution-03.md) + *Implement automated resource adjustments based on detected anomalies.* + +- **Challenge 04:** [Build the Alert Manager Agent (Live Azure Integration)](./Solution-04.md) + *Design a communication layer to notify or log alerts from your system.* + +- **Challenge 05:** [Orchestrate Agent-to-Agent Communication](./Solution-05.md) + *Build an orchestrator to coordinate communication between agents.* + +- **Challenge 06:** [Enable Agent-to-Agent Communication (A2A)](./Solution-06.md) + *Enable agents to share context, pass messages, and coordinate actions dynamically.* + +- **Challenge 07:** [Build the Anomaly & Resolution Tracker](./Solution-07.md) + *Log and visualize all anomaly and resolution events in real time.* + +- **Challenge 08:** [Spike VM Resources & Test Agent Detection](./Solution-08.md) + *Simulate CPU and memory spikes to validate your agentic system.* + +--- + +## Coach Prerequisites + +Before hosting, coaches should ensure they can perform the following: + +- **Active Azure Subscription** +- **Python 3.7 or higher** *(Python 3.13 preferred)* +- **Pip** (Python package installer) +- **GitHub account** with access to the AgenticAIApps repository and **Codespaces** +- **VS Code** with Python and Azure extensions +- **Azure CLI** installed and authenticated +- Basic familiarity with **Linux, SSH, and Bash scripting** +- (Optional) Azure Monitor, Streamlit, and Power BI for visualization + +Always review the [What The Hack Hosting Guide](https://aka.ms/wthhost) for event-specific instructions. + +### Student Resources + +Coaches should download and package the `/Student/Resources` folder into a `Resources.zip` file and provide it to students at the start of the hack. + +**NOTE:** Students should **not** have access to the repository before or during the hack. + +--- + +## Azure Requirements + +Students require access to an Azure subscription capable of creating and consuming resources used in the challenges. +This includes: + +- VM creation and scaling +- Storage access (for logs) +- Permissions to deploy agents and monitoring solutions + +--- + +## Learning Resources + +- [Microsoft Agent Framework – Python User Guide](https://learn.microsoft.com/en-us/agent-framework/user-guide/agents/agent-types/?pivots=programming-language-python) +- [Connect to a VM using SSH (Azure Docs)](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/mac-create-ssh-keys) +- [Introduction to Bash and Linux CLI](https://ubuntu.com/tutorials/command-line-for-beginners) +- [Azure AI Foundry Overview](https://learn.microsoft.com/en-us/azure/ai-foundry/) + +--- + +## Repository Contents + +- `./Coach` – Coach's guide and related files +- `./Coach/Solutions` – Completed solution files for each challenge +- `./Student` – Student challenge guide +- `./Student/Resources` – Resource files, sample code, and scripts for students + +--- + +## Contributors + +- **Esvin Ruiz** diff --git a/xxx-AgenticAIApps/Coach/Solution-00.md b/xxx-AgenticAIApps/Coach/Solution-00.md new file mode 100644 index 0000000000..6dfb90a741 --- /dev/null +++ b/xxx-AgenticAIApps/Coach/Solution-00.md @@ -0,0 +1,117 @@ +# Challenge 00 - Azure AI Foundry Onboarding & Environment Prep - Coach's Guide + +**[Home](./README.md)** - [Next Solution >](./Solution-01.md) + +## Notes & Guidance + +This guide walks you through setting up your development environment and Azure subscription for working with Azure AI Foundry. It is designed to help coaches and participants prepare their cloud-based workspace for the challenges ahead. + +### Prerequisites + +- Python (Version 3.7 or higher, Python 3.13 preferred) +- Pip (package installer for Python) +- Active Azure Subscription +- Azure Developer CLI + +Reference documentation: +- [Azure AI Foundry Overview](https://learn.microsoft.com/en-us/azure/azure-ai-foundry/overview) + +--- + +### Create Azure AI Foundry Resource in Azure Account + +- Log in to your Azure portal +- Create a new Azure AI Foundry resource +- Note down your resource endpoint URL (you'll need this later) + +--- + +### Set Up GitHub Codespaces + +GitHub Codespaces provides a cloud-hosted development environment that eliminates the need for local setup. + +- Navigate to the project repository: + [Agentic AI Apps GitHub Repository](https://github.com/WhatTheHack/tree/xxx-AgenticAIApps) +- Click the green **Code** button and select **Codespaces > Create codespace on main** +- Wait for the environment to initialize. It will automatically install dependencies and configure your workspace. +- Use the integrated terminal to run commands and interact with Azure resources. +- Authenticate your Codespace CLI session with Azure by running: + + ```bash + az login + ``` + + - This will open a browser window to complete the login process + - Once authenticated, your Codespace CLI will be connected to your Azure subscription + +--- + +### Install Required Packages + +Once your Codespace is ready, open the terminal and run: + +```bash +pip install azure-ai-projects azure-identity +``` + +Verify installation: + +```bash +pip list +``` + +--- + +### Create a Virtual Machine with Permissions + +To support later stages of the project, you'll need a Linux-based virtual machine with read/write permissions. + +- Open the Azure Portal and navigate to **Virtual Machines** +- Click **Create > Virtual Machine** +- Use the following configuration: + - **Resource Group:** Same as your Azure AI Foundry project + - **Virtual Machine Name:** `agentic-vm-test` + - **Region:** West US 2 + - **Availability Zone:** Zone 1 + - **Image:** Ubuntu 22.04 LTS + - **Size:** Standard B2pts v2 (2 vCPUs, 1 GiB memory) + - **Authentication Type:** SSH public key + - **Inbound Ports:** Allow SSH (port 22) +- Click **Next: Disks** and accept the default settings +- Click **Next: Networking** and ensure the VM is assigned a public IP +- Click **Next: Management**, then enable **System Assigned Managed Identity** +- After deployment, go to **Access Control (IAM)** for the VM and assign the **Contributor** role + +> ⚠️ This VM is intended for testing purposes only. Do not use it for production workloads. + +--- + +### Repository Usage Notes + +The [Agentic AI Apps GitHub Repository](https://github.com/WhatTheHack/tree/xxx-AgenticAIApps) contains all the source code and configuration files needed for this challenge. + +- **Codespaces Ready:** Preconfigured for GitHub Codespaces—launch and start coding immediately +- **Project Structure:** Each challenge is organized into its own folder. Start with `Challenge-01` +- **Auto-Setup:** Dependencies install automatically when the Codespace launches +- **Customization:** Modify `.devcontainer` files to adjust the environment +- **Sync with Azure:** Use the terminal to authenticate and interact with Foundry resources + +--- + +## Next Steps: +Your Azure AI Foundry development environment is now fully configured. +You’ve installed the required SDKs, authenticated with Azure, and confirmed that your workspace can register and run agents. + +Tip: Keep your `.env` and Foundry configuration handy — you’ll reuse them throughout every subsequent challenge. + +--- + +Proceed to **[Challenge 001 – Semantic Kernel Setup & Configuration](./Solution-01.md)** to: +- Integrate **Semantic Kernel** for planning and reasoning. +- Explore how prompts, skills, and plugins form the cognitive layer of your agents. +- Learn how agents interpret natural language requests and turn them into structured actions. +- Prepare the foundation for multi-agent collaboration in future challenges. + +--- + +All sections marked with `🔹 STUDENT MISSING SECTION` are **what students were expected to implement themselves** in the student guide. Coaches can reference these for solution verification. diff --git a/xxx-AgenticAIApps/Coach/Solution-01.md b/xxx-AgenticAIApps/Coach/Solution-01.md new file mode 100644 index 0000000000..91a54e8db7 --- /dev/null +++ b/xxx-AgenticAIApps/Coach/Solution-01.md @@ -0,0 +1,194 @@ +# Challenge 01 - Semantic Kernel Setup & Configuration – Coach's Guide + +[< Previous Solution](./Solution-00.md) - **[Home](./README.md)** - [Next Solution >](./Solution-02.md) + +--- + +## Notes & Guidance + +This guide walks coaches and participants through setting up Semantic Kernel using Azure OpenAI services inside GitHub Codespaces. It enables orchestration of intelligent agents for planning and task execution. + +--- + +### Environment Setup + +* Use **GitHub Codespaces** + + * Launch directly from the **Agentic AI Apps** GitHub repository. + * Dependencies install automatically when the Codespace initializes. + +--- + +### Secure Your Credentials + +* Create a `.env` file in your project root and add the following keys: + +```env +OPENAIAPIKEY=your-azure-openai-api-key +OPENAIENDPOINT=your-azure-openai-endpoint +OPENAIDEPLOYMENTNAME=your-model-deployment +OPENAIMODEL_NAME=gpt-4o +AZURE_SUBSCRIPTION_ID=your-subscription-id +AZURE_RESOURCE_GROUP=your-resource-group +AZURE_VM_NAME=your-vm-name +``` + +* Add `.env` to `.gitignore` to protect sensitive credentials. +* Avoid spaces around `=` — they prevent variables from loading correctly. + +--- + +### Kernel Initialization + +Create a file called `test_kernel.py`: + +```python +import os +import asyncio +from dotenv import load_dotenv +from semantic_kernel.kernel import Kernel +from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion + +load_dotenv() + +api_key = os.getenv("OPENAIAPIKEY") +endpoint = os.getenv("OPENAIENDPOINT") +deployment_name = os.getenv("OPENAIDEPLOYMENTNAME") + +kernel = Kernel() +kernel.add_service( + AzureChatCompletion( + service_id="chatcompletion", + deployment_name=deployment_name, + endpoint=endpoint, + api_key=api_key + ) +) + +# 🔹 STUDENT MISSING SECTION: Prompt testing +async def run(): + result = await kernel.invoke_prompt_async("What is Semantic Kernel?") + print(result) + +asyncio.run(run()) +``` + +✅ **Expected Output:** + +``` +"Semantic Kernel is an open-source SDK that lets you build AI-first apps..." +``` + +--- + +### Organize Your Skills + +Create a `skills/` folder to store Semantic Kernel plugins. Each skill should include: + +* `config.json` — defines the skill’s name, description, and inputs. +* `skprompt.txt` — contains the prompt template or logic. + +This structure lets you modularize functionality and invoke skills dynamically. + +Example skills: + +* `MonitorSkill` +* `AnomalySkill` +* `AzureMonitorSkill` *(new — for live data)* + +--- + +### Add a Live Azure Monitor Skill + +Create a file named `azure_monitor_skill.py` in the `skills/` folder: + +```python +import os +from azure.monitor.query import MetricsQueryClient +from azure.identity import DefaultAzureCredential +from dotenv import load_dotenv +from semantic_kernel.skill_definition import sk_function + +load_dotenv() + +class AzureMonitorSkill: + def __init__(self): + self.credential = DefaultAzureCredential() + self.client = MetricsQueryClient(self.credential) + self.subscription_id = os.getenv("AZURE_SUBSCRIPTION_ID") + self.resource_group = os.getenv("AZURE_RESOURCE_GROUP") + self.vm_name = os.getenv("AZURE_VM_NAME") + + # 🔹 STUDENT MISSING SECTION: Function to retrieve CPU metric + @sk_function(name="get_vm_cpu", description="Retrieve current CPU usage for a VM") + def get_vm_cpu(self) -> str: + resource_id = ( + f"/subscriptions/{self.subscription_id}/resourceGroups/" + f"{self.resource_group}/providers/Microsoft.Compute/virtualMachines/{self.vm_name}" + ) + + response = self.client.query_resource( + resource_id=resource_id, + metric_names=["Percentage CPU"], + timespan="PT1H" + ) + + for metric in response.metrics: + if metric.timeseries and metric.timeseries[0].data: + last_point = metric.timeseries[0].data[-1] + if last_point.average is not None: + return f"Current CPU usage: {last_point.average:.2f}%" + + return "No CPU data available." +``` + +Then register it inside your main kernel file (`test_kernel.py`): + +```python +# 🔹 STUDENT MISSING SECTION: Skill registration +from skills.azure_monitor_skill import AzureMonitorSkill + +kernel.import_skill(AzureMonitorSkill(), "azure_monitor") + +async def run(): + cpu_data = await kernel.skills.azure_monitor.get_vm_cpu() + print(cpu_data) +``` + +**Expected Output (example):** + +``` +Current CPU usage: 21.43% +``` + +--- + +### Why This Matters + +By connecting Semantic Kernel to Azure Monitor: + +* Agents can react to **live telemetry** instead of mock anomalies. +* Lays the foundation for Challenge 02, where your **Anomaly Detector Agent** will use these metrics for proactive monitoring. +* Aligns Foundry agents with **real Azure resources**, enabling autonomous cloud management. + +--- + +### Next Steps + +After completing this setup, your agents can interpret, plan, and act on **real data** within your Azure environment. + +--- + +Proceed to **[Challenge 02 – Build the Anomaly Detector Agent (Real Azure Metrics)](./Solution-02.md)** to: + +* Connect your Semantic Kernel agents to **Azure Monitor metrics**. +* Detect real-time anomalies in **CPU, memory, and disk I/O**. +* Trigger optimization and orchestration flows using **live telemetry**. +* Build a foundation for intelligent, self-healing cloud agents. + +🧩 *Keep your Azure credentials and Foundry session active — Challenge 02 builds directly on this configuration.* + +--- + +All sections marked with `🔹 STUDENT MISSING SECTION` are **what students were expected to implement themselves** in the student guide. Coaches can reference these for solution verification. + diff --git a/xxx-AgenticAIApps/Coach/Solution-02.md b/xxx-AgenticAIApps/Coach/Solution-02.md new file mode 100644 index 0000000000..7183848ed2 --- /dev/null +++ b/xxx-AgenticAIApps/Coach/Solution-02.md @@ -0,0 +1,148 @@ +# Challenge 2 - Build the Anomaly Detector Agent (Real Azure Metrics) - Coach's Guide + +[< Previous Solution](./Solution-01.md) - **[Home](./README.md)** - [Next Solution >](./Solution-03.md) + + +## Notes & Guidance + +This guide walks coaches and participants through building an agent that monitors real-time Azure metrics and detects anomalies in system performance. It introduces Azure Monitor integration and agentic alerting logic. + +--- + +### Environment Setup + +- Use GitHub Codespaces + Required packages install automatically when the Codespace initializes: + +```bash +pip install azure-monitor-query azure-identity python-dotenv +```` + +* Create a `.env` file in your project root + Include the following keys: + +```env +AZURESUBSCRIPTIONID=your-subscription-id +AZURERESOURCEGROUP=your-resource-group +AZURERESOURCENAME=your-vm-name +AZURE_METRICS=Percentage CPU,Available Memory Bytes,Disk Read Bytes/sec +``` + +> **Tip:** Add `.env` to `.gitignore` to protect credentials. + +--- + +### Agent Initialization + +Create a file called `anomaly_detector.py` and define the agent: + +```python +import os +from azure.identity import DefaultAzureCredential +from azure.monitor.query import MetricsQueryClient +from azure.monitor.query.models import MetricAggregationType +from azure.ai.foundry import Agent, Message, Thread +from dotenv import load_dotenv +from datetime import timedelta + +load_dotenv() + +class AnomalyDetectorAgent(Agent): + def init(self): + super().init(name="anomaly-detector") + self.client = MetricsQueryClient(credential=DefaultAzureCredential()) + self.resource_id = ( + f"/subscriptions/{os.getenv('AZURESUBSCRIPTIONID')}" + f"/resourceGroups/{os.getenv('AZURERESOURCEGROUP')}" + f"/providers/Microsoft.Compute/virtualMachines/{os.getenv('AZURERESOURCENAME')}" + ) + self.metrics = [m.strip() for m in os.getenv("AZURE_METRICS").split(",")] + + # 🔹 STUDENT MISSING SECTION: Retrieve latest metric + def get_latest_metric(self, metric_name): + response = self.client.query_resource( + resource_uri=self.resource_id, + metric_names=[metric_name], + timespan=timedelta(minutes=5), + aggregations=[MetricAggregationType.AVERAGE] + ) + for metric in response.metrics: + for timeseries in metric.timeseries: + for data in timeseries.data: + if data.average is not None: + return data.average + return None + + # 🔹 STUDENT MISSING SECTION: Run method to check for anomalies + def run(self, thread: Thread, message: Message): + anomalies = [] + for metric in self.metrics: + value = self.get_latest_metric(metric) + print(f"{metric}: {value}") + if value is None: + continue + if ( + ("CPU" in metric and value > 75) or + ("Memory" in metric and value < 1e9) or + ("Disk" in metric and value > 5e7) + ): + anomalies.append(f"{metric} = {value}") + + if anomalies: + alert = "⚠️ Anomalies detected:\n" + "\n".join(anomalies) + thread.send_message(Message(content=alert, role="agent")) + else: + print("No anomalies detected.") +``` + +--- + +### Register and Test the Agent + +#### Register the Agent + +```python +# register_anomaly.py +from azure.ai.foundry import AgentClient +from anomaly_detector import AnomalyDetectorAgent + +client = AgentClient() +agent = AnomalyDetectorAgent() +client.register_agent(agent) +``` + +Run: + +```bash +python register_anomaly.py +``` + +#### Test the Agent + +```python +# test_anomaly.py +from azure.ai.foundry import AgentClient + +client = AgentClient() +thread = client.create_thread() +client.send_message(thread.id, "Run anomaly check", agent_name="anomaly-detector") +``` + +Run: + +```bash +python test_anomaly.py +``` + +Expected output: Real metric values printed and alerts triggered if thresholds are exceeded. + +--- + +### Next Steps + +Proceed to Challenge 03 to build a **Resource Optimizer Agent** that responds to anomalies and simulates Azure-based optimizations. + +--- + +All sections marked with `🔹 STUDENT MISSING SECTION` are **what students were expected to implement themselves** in the student guide. Coaches can reference these for solution verification. + diff --git a/xxx-AgenticAIApps/Coach/Solution-03.md b/xxx-AgenticAIApps/Coach/Solution-03.md new file mode 100644 index 0000000000..c93281c8f0 --- /dev/null +++ b/xxx-AgenticAIApps/Coach/Solution-03.md @@ -0,0 +1,133 @@ +# Challenge 03 - Build the Resource Optimizer Agent (Real Azure Integration) - Coach's Guide + +[< Previous Solution](./Solution-02.md) - **[Home](./README.md)** - [Next Solution >](./Solution-04.md) + +## Notes & Guidance + +In this challenge, participants create a **Resource Optimizer Agent** that responds to anomalies detected by the Anomaly Detector Agent and performs simulated or real Azure optimizations. +The agent demonstrates integration between **Semantic Kernel**, **Azure Monitor**, and the **Azure Management SDK**. + +--- + +### Environment Setup + +- Provision a Linux VM (`agentic-vm-test`) with **Contributor permissions** to ensure read/write access. +- Install required SDKs: + +```bash +pip install azure-mgmt-compute azure-identity python-dotenv +```` + +* `.env` file should include: + +```env +AZURESUBSCRIPTIONID=your-subscription-id +AZURERESOURCEGROUP=your-resource-group +AZUREVMNAME=your-vm-name +``` + +> Ensure your VM has **read/write permissions** — necessary for optimization actions. + +--- + +### Create the Resource Optimizer Agent + +Create `resource_optimizer.py`: + +```python +import os +from azure.identity import DefaultAzureCredential +from azure.mgmt.compute import ComputeManagementClient +from azure.ai.foundry import Agent, Message, Thread +from dotenv import load_dotenv + +load_dotenv() + +class ResourceOptimizerAgent(Agent): + def init(self): + super().init(name="resource-optimizer") + + # 🔹 STUDENT MISSING SECTION: Initialize Azure credentials & ComputeManagementClient + self.subscription_id = os.getenv("AZURESUBSCRIPTIONID") + self.resource_group = os.getenv("AZURERESOURCEGROUP") + self.vm_name = os.getenv("AZUREVMNAME") + self.credential = DefaultAzureCredential() + self.compute_client = ComputeManagementClient(self.credential, self.subscription_id) + + # 🔹 STUDENT MISSING SECTION: Run method to process anomaly messages + def run(self, thread: Thread, message: Message): + print("Optimizer received:", message.content) + response = "" + + # Example logic: check message content for CPU/memory/disk anomalies + if "CPU" in message.content: + response = self.scale_vm("Standard_DS2_v2") + elif "Memory" in message.content: + response = self.scale_vm("Standard_DS3_v2") + elif "Disk" in message.content: + response = self.scale_vm("Standard_DS4_v2") + else: + response = "No actionable anomalies detected." + + thread.send_message(Message(content=response, role="agent")) + + # 🔹 STUDENT MISSING SECTION: Scale VM method using Azure SDK + def scale_vm(self, new_size): + vm = self.compute_client.virtual_machines.get(self.resource_group, self.vm_name) + vm.hardware_profile.vm_size = new_size + poller = self.compute_client.virtual_machines.begin_create_or_update( + self.resource_group, + self.vm_name, + vm + ) + poller.wait() + return f"VM scaled to {new_size}" +``` + +--- + +### Register and Test the Agent + +#### Register the Agent + +```python +from azure.ai.foundry import AgentClient +from resource_optimizer import ResourceOptimizerAgent + +client = AgentClient() +agent = ResourceOptimizerAgent() +client.register_agent(agent) +``` + +Run: + +```bash +python register_optimizer.py +``` + +#### Test the Agent + +```python +from azure.ai.foundry import AgentClient + +client = AgentClient() +thread = client.create_thread() +client.send_message(thread.id, "⚠️ Anomaly detected: Percentage CPU = 92", agent_name="resource-optimizer") +``` + +Expected behavior: The agent prints the message, identifies the anomaly, and scales the VM according to the logic. + +--- + +### Next Steps + +Once the **Resource Optimizer Agent** is working: + +* Move to Challenge 04 to build an **Alert Manager Agent** that coordinates notifications and alert responses across your system. +* Explore logging, visualization, and orchestration for multi-agent workflows. + +--- + +All sections marked with `🔹 STUDENT MISSING SECTION` are **what students were expected to implement themselves** in the student guide. Coaches can reference these for solution verification. + + diff --git a/xxx-AgenticAIApps/Coach/Solution-04.md b/xxx-AgenticAIApps/Coach/Solution-04.md new file mode 100644 index 0000000000..cbff493c6e --- /dev/null +++ b/xxx-AgenticAIApps/Coach/Solution-04.md @@ -0,0 +1,128 @@ +# Challenge 04 - Build the Alert Manager Agent (Live Azure Integration) - Coach's Guide + +[< Previous Solution](./Solution-03.md) - **[Home](./README.md)** - [Next Solution >](./Solution-05.md) + +## Notes & Guidance + +In this challenge, participants build an **Alert Manager Agent** that notifies stakeholders when anomalies or optimizations occur. This involves integrating with **Azure Monitor Action Groups** and simulating real-world alert handling within an agentic workflow. + +--- + +### Environment Setup + +Install required dependencies: + +```bash +pip install azure-monitor-query azure-identity azure-mgmt-monitor python-dotenv +```` + +Update your `.env` file to include alert group settings: + +```env +AZURESUBSCRIPTIONID=your-subscription-id +AZURERESOURCEGROUP=your-resource-group +AZUREACTIONGROUP_NAME=your-action-group-name +``` + +> ⚠️ Ensure you have **Contributor permissions** to the resource group for managing alerts and action groups. + +--- + +### Create the Alert Manager Agent + +Create `alert_manager.py`: + +```python +import os +from azure.identity import DefaultAzureCredential +from azure.mgmt.monitor import MonitorManagementClient +from azure.ai.foundry import Agent, Message, Thread +from dotenv import load_dotenv + +load_dotenv() + +class AlertManagerAgent(Agent): + def init(self): + super().init(name="alert-manager") + + # 🔹 STUDENT MISSING SECTION: Initialize subscription ID, resource group, and Azure Monitor client + self.subscription_id = os.getenv("AZURESUBSCRIPTIONID") + self.resource_group = os.getenv("AZURERESOURCEGROUP") + self.monitor_client = MonitorManagementClient( + credential=DefaultAzureCredential(), + subscription_id=self.subscription_id + ) + + # 🔹 STUDENT MISSING SECTION: Define agent behavior when receiving anomaly or optimization messages + def run(self, thread: Thread, message: Message): + print("Alert Manager received:", message.content) + + if "Anomaly" in message.content or "Optimization" in message.content: + alert_msg = f"🚨 Alert triggered: {message.content}" + thread.send_message(Message(content=alert_msg, role="agent")) + print("Sending alert to Azure Monitor action group…") + self.send_alert(alert_msg) + + # 🔹 STUDENT MISSING SECTION: Implement method to simulate sending alert to Azure Monitor + def send_alert(self, alert_msg): + # Simulated alert sending for demonstration + print(f"Simulated alert sent: {alert_msg}") +``` + +--- + +### Register and Test the Agent + +#### Register the Agent + +```python +# register_alert.py +from azure.ai.foundry import AgentClient +from alert_manager import AlertManagerAgent + +client = AgentClient() +agent = AlertManagerAgent() +client.register_agent(agent) +``` + +Run: + +```bash +python register_alert.py +``` + +#### Test the Agent + +```python +# test_alert.py +from azure.ai.foundry import AgentClient + +client = AgentClient() +thread = client.create_thread() +client.send_message(thread.id, "⚠️ Optimization failed due to high CPU usage", agent_name="alert-manager") +``` + +Run: + +```bash +python test_alert.py +``` + +Expected Output: + +``` +Alert Manager received: ⚠️ Optimization failed due to high CPU usage +Alert triggered: ⚠️ Optimization failed due to high CPU usage +Simulated alert sent: 🚨 Alert triggered: ⚠️ Optimization failed due to high CPU usage +``` + +--- + +### Next Steps + +Once the Alert Manager Agent is complete, proceed to **Challenge 05**, where students will build the **Agent-to-Agent Communication Layer** that enables collaboration and orchestration among the Anomaly Detector, Resource Optimizer, and Alert Manager agents. + +--- + +All sections marked with `🔹 STUDENT MISSING SECTION` are **what students were expected to implement themselves** in the student guide. Coaches can reference these for solution verification. + diff --git a/xxx-AgenticAIApps/Coach/Solution-05.md b/xxx-AgenticAIApps/Coach/Solution-05.md new file mode 100644 index 0000000000..4fde41bd74 --- /dev/null +++ b/xxx-AgenticAIApps/Coach/Solution-05.md @@ -0,0 +1,129 @@ +# Challenge 05 - Orchestrate Agent-to-Agent Communication - Coach's Guide + +[< Previous Solution](./Solution-04.md) - **[Home](../README.md)** - [Next Solution >](./Solution-06.md) + +## Notes & Guidance + +This challenge connects all previous agents — **Anomaly Detector**, **Resource Optimizer**, and **Alert Manager** — into a unified system. It introduces **message routing**, **shared threads for memory**, and optional **Semantic Kernel planning** for adaptive orchestration. + +--- + +### Environment Setup + +Install dependencies: + +```bash +pip install python-dotenv azure-ai-foundry +```` + +Ensure all three agents are already registered and available in your workspace. + +--- + +### Orchestrator Initialization + +Create `agent_orchestrator.py`: + +```python +from azure.ai.foundry import AgentClient, Thread +from dotenv import load_dotenv +import os + +load_dotenv() + +class AgentOrchestrator: + def __init__(self): + # 🔹 STUDENT MISSING SECTION: Initialize AgentClient and map agent names + self.client = AgentClient() + self.agents = { + "anomaly": "anomaly-detector", + "optimizer": "resource-optimizer", + "alert": "alert-manager" + } + + # 🔹 STUDENT MISSING SECTION: Create a new communication thread for shared state + def create_thread(self): + return self.client.create_thread() + + # 🔹 STUDENT MISSING SECTION: Define how messages are routed to each agent + def send_to_agent(self, thread: Thread, agent_key: str, message: str): + agent_name = self.agents.get(agent_key) + if not agent_name: + print(f"Unknown agent: {agent_key}") + return + self.client.send_message(thread.id, message, agent_name=agent_name) + + # 🔹 STUDENT MISSING SECTION: Implement orchestration flow between agents + def orchestrate(self): + thread = self.create_thread() + print(" Step 1: Trigger Anomaly Detector") + self.send_to_agent(thread, "anomaly", "Check system metrics") + + print(" Step 2: Trigger Resource Optimizer") + self.send_to_agent(thread, "optimizer", "Respond to detected anomalies") + + print(" Step 3: Trigger Alert Manager") + self.send_to_agent(thread, "alert", "Notify stakeholders of critical issues") + + print(" Orchestration complete.") +``` + +--- + +### Run the Orchestrator + +Create `run_orchestrator.py`: + +```python +from agent_orchestrator import AgentOrchestrator + +orchestrator = AgentOrchestrator() +orchestrator.orchestrate() +``` + +Run the orchestrator: + +```bash +python run_orchestrator.py +``` + +Expected Output: + +``` + Step 1: Trigger Anomaly Detector + Step 2: Trigger Resource Optimizer + Step 3: Trigger Alert Manager + Orchestration complete. +``` + +--- + +### Optional: Semantic Kernel Integration + +For intelligent planning and adaptive execution, you can integrate **Semantic Kernel**: + +```python +from semantickernel import Kernel + +kernel = Kernel() +plan = kernel.create_plan("Detect and respond to system anomalies dynamically") +``` + +This allows your orchestrator to make **context-aware decisions** and support **autonomous collaboration** between agents. + +--- + +### Success Criteria + +Students should demonstrate: + +* The **Anomaly Detector**, **Resource Optimizer**, and **Alert Manager** agents are registered. +* The orchestrator successfully routes messages across agents using a shared thread. +* Execution produces an ordered flow of operations, simulating anomaly detection, optimization, and alerting. +* Optional: Use of **Semantic Kernel** or similar planning logic for intelligent task sequencing. + +--- + +All sections marked with `🔹 STUDENT MISSING SECTION` are **what students were expected to implement themselves** in the student guide. +Coaches can reference these to verify solution accuracy. + diff --git a/xxx-AgenticAIApps/Coach/Solution-06.md b/xxx-AgenticAIApps/Coach/Solution-06.md new file mode 100644 index 0000000000..a58ea1bc68 --- /dev/null +++ b/xxx-AgenticAIApps/Coach/Solution-06.md @@ -0,0 +1,144 @@ +# Challenge 06 - Enable Agent-to-Agent Communication (A2A) - Coach's Guide + +[< Previous Solution](./Solution-05.md) - **[Home](./README.md)** - [Next Solution >](./Solution-07.md) + +## Notes & Guidance + +In this challenge, participants enable **real-time communication between Azure Agents**, allowing them to exchange context and coordinate actions. This marks the transition from isolated automation to a **collaborative, agentic network** powered by shared threads and dynamic planning. + +--- + +## Goal + +Build a communication layer that enables agents to: + +- Share context through **shared threads** +- Exchange messages dynamically +- Coordinate actions using **shared memory** +- Optionally leverage **Semantic Kernel** or **Autogen v2** for autonomous planning + +--- + +## 🧩 Shared Thread Communication + +Enhance your orchestrator to support **dynamic interaction** between agents. + +Create or update `agent_orchestrator.py`: + +```python +# 🔹 STUDENT MISSING SECTION: Implement dynamic orchestration method +def orchestrate_dynamic(self, user_input): + thread = self.create_thread() + + # Step 1: Trigger Anomaly Detector + self.send_to_agent(thread, "anomaly", user_input) + + # Step 2: Retrieve anomaly message + messages = self.get_thread_messages(thread) + anomaly_msg = next((m.content for m in messages if "Anomaly" in m.content), None) + + # Step 3: Trigger Resource Optimizer if anomaly detected + if anomaly_msg: + self.send_to_agent(thread, "optimizer", anomaly_msg) + + # Step 4: Retrieve optimization message + messages = self.get_thread_messages(thread) + optimization_msg = next((m.content for m in messages if "🛠️" in m.content), None) + + # Step 5: Trigger Alert Manager if optimization succeeded + if optimization_msg: + self.send_to_agent(thread, "alert", optimization_msg) + + return self.get_thread_messages(thread) +```` + +### Explanation + +* **Shared thread**: Keeps all agent messages in the same context. +* **Sequential routing**: Each agent reads and reacts to prior messages. +* **Dynamic flow**: The orchestrator adapts based on actual responses. + +--- + +## Update the App to Use Dynamic Orchestration + +Update `app.py` so user input triggers your new dynamic orchestration: + +```python +# 🔹 STUDENT MISSING SECTION: Integrate orchestrator into app logic +async def handle_user_input(user_input): + messages = orchestrator.orchestrate_dynamic(user_input) + return [msg.content for msg in messages] +``` + +> 💡 The `async` keyword ensures compatibility with future streaming or concurrent message handling. + +--- + +## Add Agent Role Awareness (Optional) + +To improve clarity in logs and dashboards, tag messages by agent role. + +```python +return [f"{msg.role}: {msg.content}" for msg in messages] +``` + +Example output: + +``` +anomaly-detector: High CPU detected +resource-optimizer: Scaling VM to Standard_DS2_v2 +alert-manager: Notification sent to admin +``` + +--- + +## Optional: Semantic Kernel Integration + +For adaptive task routing, integrate **Microsoft Semantic Kernel**: + +```python +# 🔹 STUDENT MISSING SECTION: Implement dynamic planning via Semantic Kernel +from semantickernel import Kernel + +kernel = Kernel() +plan = kernel.create_plan("Detect and respond to system anomalies") +for step in plan.steps: + orchestrator.send_to_agent(thread, step.plugin_name, step.description) +``` + +This enables **goal-driven orchestration**, allowing agents to decide which should act next based on current system state and context. + +--- + +## Expected Behavior + +When running the system: + +* **Anomaly Detector** identifies anomalies from Azure metrics +* **Resource Optimizer** responds and applies optimizations +* **Alert Manager** notifies users and stakeholders +* All messages and context flow through **shared threads** + +Example output: + +``` +anomaly-detector: Anomaly detected: CPU = 92% +resource-optimizer: Scaling VM to Standard_DS2_v2 +alert-manager: Alert sent: VM scaled successfully +``` + +--- + +## Next Steps + +Proceed to **Challenge 07** to extend your agentic system with: + +* Persistent memory between sessions +* Historical anomaly tracking +* Context-aware planning using Azure AI Foundry or Semantic Kernel + +--- + +All sections marked with `🔹 STUDENT MISSING SECTION` are **what students were expected to implement themselves** in the student guide. +Coaches can reference these to confirm the correctness of submitted solutions. diff --git a/xxx-AgenticAIApps/Coach/Solution-07.md b/xxx-AgenticAIApps/Coach/Solution-07.md new file mode 100644 index 0000000000..19882c3d38 --- /dev/null +++ b/xxx-AgenticAIApps/Coach/Solution-07.md @@ -0,0 +1,179 @@ +# Challenge 07 - Build the Anomaly & Resolution Tracker - Coach's Guide + +[< Previous Solution](./Solution-06.md) - **[Home](./README.md)** - [Next Solution >](./Solution-08.md) + +## Notes & Guidance + +In this challenge, participants will **track anomalies and resolutions** detected by their Azure Agents and visualize the results in real time. You’ll implement lightweight logging, optionally add a Streamlit dashboard, and explore Azure-based storage options for enterprise-scale tracking. + +--- + +## Goal + +Build a tracking system that: + +- Logs anomalies detected by the **Anomaly Detector Agent** +- Logs resolutions applied by the **Resource Optimizer Agent** +- Visualizes all events locally or in Azure +- Optionally integrates with **Streamlit**, **Power BI**, or **Azure Workbooks** + +--- + +## Log Anomalies and Resolutions + +Update each agent to log its actions to a local file (or a database, if desired). +Python’s built-in `logging` module is perfect for this. + +### Example — *Anomaly Detector Agent* + +```python +import logging + +logging.basicConfig(filename='agent_log.txt', level=logging.INFO, format='[%(asctime)s] %(message)s') + +def log_anomaly(metric, value): + logging.info(f"Anomaly Detected: {metric} = {value}") +```` + +Use `log_anomaly()` inside your anomaly detection logic whenever an issue is detected. + +--- + +### Example — *Resource Optimizer Agent* + +```python +def log_resolution(action): + logging.info(f"Resolution Applied: {action}") +``` + +Call `log_resolution()` after each successful optimization or simulated fix. + +--- + +## Structure the Log Format + +Maintain a **consistent format** for readability and parsing: + +``` +[2025-08-21 14:32:10] Anomaly Detected: CPU = 92% +[2025-08-21 14:32:15] Resolution Applied: Scaled VM to Standard_DS2_v2 +``` + +This makes it easy to visualize or analyze later — either manually or with tools like **Streamlit** or **Power BI**. + +> **Tip:** Use `logging.basicConfig(..., format='[%(asctime)s] %(message)s')` to automatically include timestamps. + +--- + +## Visualize with Streamlit (Optional) + +🔹 **This section is not included in the student guide.** +Coaches can use it to demonstrate how to turn logs into a real-time dashboard. + +Create a file named **`dashboard.py`**: + +```python +import streamlit as st + +st.title("🔍 Anomaly & Resolution Tracker") + +with open("agent_log.txt") as f: + logs = f.readlines() + +for line in logs: + st.text(line.strip()) +``` + +Run the dashboard with: + +```bash +streamlit run dashboard.py +``` + +Then open the local URL Streamlit provides (usually `http://localhost:8501`) to view your live log feed. + +--- + +## (Optional) Store Logs in Azure Table or Cosmos DB + +🔹 **This section is not in the student guide.** +It provides advanced options for enterprise-level tracking and cloud persistence. + +For a **cloud-based tracking system**, you can log directly into **Azure Table Storage** or **Azure Cosmos DB** for long-term retention and visualization. + +### Option A – Azure Table Storage + +Install the SDK: + +```bash +pip install azure-data-tables +``` + +Then use: + +```python +from azure.data.tables import TableServiceClient +from datetime import datetime +import os + +service = TableServiceClient.from_connection_string(conn_str=os.getenv("AZURE_STORAGE_CONNECTION_STRING")) +table_client = service.get_table_client(table_name="AgentLogs") + +def log_to_table(event_type, detail): + entity = { + "PartitionKey": "AgentLogs", + "RowKey": str(datetime.utcnow().timestamp()), + "EventType": event_type, + "Detail": detail + } + table_client.create_entity(entity) +``` + +### Option B – Azure Cosmos DB + +Use **`azure-cosmos`** for structured, scalable document storage. +Each log can be stored as a JSON document and visualized using **Power BI** or **Azure Workbooks**. + +--- + +## Expected Behavior + +When running your system: + +* **Anomaly Detector** logs events like: + + ``` + [2025-10-11 14:01:10] Anomaly Detected: CPU = 91% + ``` +* **Resource Optimizer** logs resolutions: + + ``` + [2025-10-11 14:01:15] Resolution Applied: Scaled VM to Standard_DS2_v2 + ``` +* Logs can be viewed locally or through your **Streamlit dashboard** (🔹 *dashboard is a coach-only enhancement*). + +--- + +## Success Criteria + +A student has successfully completed Challenge 07 when they can: + +* Log anomalies detected by the Anomaly Detector Agent to a local file or database. +* Log resolutions applied by the Resource Optimizer Agent consistently. +* View logs in the correct timestamped format. +* Demonstrate that both anomaly detection and resolution events are captured and trackable in real time. + +--- + +🔹 **Coach Extension:** +Encourage students to explore: + +* Streamlit for local dashboards +* Azure Table or Cosmos DB for persistent logging +* Power BI or Azure Workbooks for advanced visualization + +--- + +All sections marked with `🔹 STUDENT MISSING SECTION` are **what students were expected to implement themselves** in the student guide. Coaches can reference these for solution verification. + + diff --git a/xxx-AgenticAIApps/Coach/Solution-08.md b/xxx-AgenticAIApps/Coach/Solution-08.md new file mode 100644 index 0000000000..d7ec9f5aaa --- /dev/null +++ b/xxx-AgenticAIApps/Coach/Solution-08.md @@ -0,0 +1,199 @@ +# Challenge 008 – Spike VM Resources & Test Agent Detection – Coach's Guide + +[< Previous Solution](./Solution-07.md) - **[Home](./README.md)** + +## Goal +Temporarily spike CPU and memory on your VM to test agent detection. +Participants will observe the **Anomaly Detector**, **Resource Optimizer**, and **Alert Manager** responding to real-time changes. + +--- + +## Important Pre-Step: Establish a Baseline +Before creating the spike: +1. Connect to your Azure environment. +2. Run your agents **without any artificial load**: + +```bash +python test_anomaly.py +# or +python run_orchestrator.py +```` + +* Confirm no anomalies are logged — this is your baseline reference. + +--- + +## Choose the Appropriate Stress Script + +### Linux/macOS – Bash or Zsh Users (`spike_vm.sh`) + +```bash +#!/usr/bin/env bash +# CPU + Memory stress test for Linux/macOS + +DURATION=${1:-30} # default duration in seconds +MEMORY_MB=${2:-1024} # default memory allocation + +echo "🔁 Spiking CPU and memory for $DURATION seconds (Memory: $MEMORY_MB MB)..." + +# CPU spike: spawn a background loop per CPU core +CPU_CORES=$(nproc) +for i in $(seq 1 $CPU_CORES); do + ( while :; do 1..200000 | xargs -n1 echo | md5sum > /dev/null; done ) & +done + +# Memory spike: allocate arrays +MEM_BLOCKS=() +BLOCK_SIZE_MB=64 +BLOCKS_TO_ALLOCATE=$(( (MEMORY_MB + BLOCK_SIZE_MB - 1) / BLOCK_SIZE_MB )) +for i in $(seq 1 $BLOCKS_TO_ALLOCATE); do + MEM_BLOCKS+=( $(python3 -c "a = ['x'*1024*1024 for _ in range($BLOCK_SIZE_MB)]; input()") ) +done + +echo "CPU+Memory stress running. Stop manually by killing background jobs or closing terminal." +``` + +Run: + +```bash +chmod +x spike_vm.sh +./spike_vm.sh 45 1024 +``` + +--- + +### Windows – PowerShell Users (`spike_vm.ps1`) + +```powershell +# Set CPU threads and memory allocation +$cpuThreads = [int](Get-CimInstance Win32_ComputerSystem).NumberOfLogicalProcessors +$memoryMB = 1024 + +Write-Host "`nStarting CPU spike with $cpuThreads threads and allocating $memoryMB MB of RAM..." + +# Start CPU jobs +$jobs = for ($i=1; $i -le $cpuThreads; $i++) { + Start-Job -ScriptBlock { + while ($true) { 1..200000 | ForEach-Object { [math]::Sqrt($_) } > $null } + } +} + +# Allocate memory +try { + $global:memBlocks = @() + $blockSizeMB = 64 + $toAllocate = [int]([math]::Ceiling($memoryMB / $blockSizeMB)) + for ($i=0; $i -lt $toAllocate; $i++) { + $b = New-Object Byte[] ($blockSizeMB * 1MB) + for ($j=0; $j -lt $b.Length; $j += 4096) { $b[$j] = 0x1 } + $global:memBlocks += ,$b + } + Write-Host "Memory allocation succeeded." +} catch { + Write-Warning "Memory allocation failed or reached system limit: $_" +} + +Write-Host "`nCPU+Memory stress running. To stop run the STOP block shown below." +``` + +Run: + +```powershell +Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force +.\spike_vm.ps1 -Duration 45 +``` + +--- + +## Run Agents During Stress + +Immediately after starting the spike: + +```bash +python test_anomaly.py +# or +python run_orchestrator.py +``` + +* **Anomaly Detector Agent** should detect high CPU/memory. +* **Resource Optimizer Agent** may suggest scaling or other resolutions. +* **Alert Manager Agent** may log or simulate alerts. + +--- + +## Verify Logs + +```powershell +# On Windows +Get-Content .\agent_log.txt -Wait + +# On Linux/macOS +tail -f agent_log.txt +``` + +Expected entries: + +``` +[2025-10-11 15:22:00] Anomaly Detected: CPU = 98% +[2025-10-11 15:22:05] Resolution Applied: Suggested VM scale-up +``` + +--- + +## Stop the Stress Script + +**Linux/macOS:** + +```bash +pkill -f 'md5sum' # stops CPU loops +``` + +**Windows PowerShell:** + +```powershell +Get-Job | Where-Object { $_.State -eq 'Running' } | ForEach-Object { Stop-Job -Job $_; Remove-Job -Job $_ } +Remove-Variable memBlocks -ErrorAction SilentlyContinue -Scope Global +[GC]::Collect(); [GC]::WaitForPendingFinalizers() +Write-Host "Stress jobs stopped and memory released." +``` + +--- + +## Success Criteria + +* Appropriate spike script in your repo (`spike_vm.sh` or `spike_vm.ps1`) +* Logs showing baseline and spike detection +* Optional screenshot of agent alerts or Streamlit dashboard + +--- + +🔹 **Coach-Only Troubleshooting Guide** + +If agents fail to detect or respond to the spike: + +* **Verify Environment Variables:** + Ensure `.env` includes all required Azure credentials (`AZURESUBSCRIPTIONID`, `AZURERESOURCEGROUP`, etc.). +* **Check Agent Registration:** + Run `python -m azure.ai.foundry list-agents` to confirm `anomaly-detector`, `resource-optimizer`, and `alert-manager` are registered. +* **Inspect Thread Flow:** + Add print statements or use logging to verify message propagation between agents in shared threads. +* **Validate Log Permissions:** + Confirm `agent_log.txt` exists and the process has write access. +* **Simulate Manual Alerts:** + Send a test message directly to `alert-manager`: + + ```bash + python -c "from azure.ai.foundry import AgentClient; c=AgentClient(); t=c.create_thread(); c.send_message(t.id, '⚠️ Manual test alert', agent_name='alert-manager')" + ``` +* **Check VM Monitoring Limits:** + If Azure Monitor metrics are delayed, manually confirm with: + + ```bash + az monitor metrics list --resource --metric "Percentage CPU" + ``` +* **Restart Agents:** + Occasionally agents hold stale threads; restarting clears cached state. + +--- + +All sections marked with `🔹 STUDENT MISSING SECTION` are **what students were expected to implement themselves** in the student guide. Coaches can reference these for solution verification. diff --git a/xxx-AgenticAIApps/Coach/Solutions/.gitkeep b/xxx-AgenticAIApps/Coach/Solutions/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/xxx-AgenticAIApps/Student/Challenge-00.md b/xxx-AgenticAIApps/Student/Challenge-00.md new file mode 100644 index 0000000000..39212f9e61 --- /dev/null +++ b/xxx-AgenticAIApps/Student/Challenge-00.md @@ -0,0 +1,77 @@ +# Challenge 00 - Azure AI Foundry Onboarding & Environment Prep + +**[Home](../README.md)** - [Next Challenge >](./Challenge-01.md) + +## Pre-requisites + +- Active Azure Subscription +- Python 3.7 or higher (Python 3.13 preferred) +- Pip (Python package installer) +- GitHub account with access to the Agentic AI Apps repository + +*This challenge assumes you have completed the What The Hack onboarding and have access to GitHub Codespaces.* + +--- + +## Introduction + +In this challenge, you will set up your development environment for Azure AI Foundry. You will learn how to: + +- Create Azure resources necessary for agent development +- Launch GitHub Codespaces for a cloud-hosted development environment +- Prepare a VM to test agent workloads +- Authenticate your Codespaces session with Azure + +Completing this challenge ensures you have a fully functional workspace for building and running intelligent agents in subsequent challenges. + +--- + +## Description + +Your goal is to prepare an environment capable of running the Azure AI Foundry agents. This includes: + +- Creating an Azure AI Foundry resource in your subscription +- Setting up GitHub Codespaces connected to your Azure account +- Installing required Python SDKs and dependencies +- Provisioning a Linux VM (`agentic-vm-test`) with contributor permissions to allow for read/ write operations +- Verifying your environment can run Python scripts and connect to Azure services + +> **Note:** This challenge focuses on environment preparation. You are not yet building agents. + +--- + +## Learning Resources + +- [Azure AI Foundry Overview](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-azure-ai-foundry) +- [GitHub Codespaces Documentation](https://docs.github.com/en/codespaces/about-codespaces/what-are-codespaces) +- [Azure CLI Documentation](https://learn.microsoft.com/en-us/cli/azure/) +- [Python `pip` Documentation](https://pip.pypa.io/en/stable/) + +--- + +## Tips + +- Ensure you keep your `.env` and Foundry configuration secure — you will reuse them in all subsequent challenges +- Codespaces automatically installs dependencies; if something fails, check your terminal for installation errors +- Use SSH keys carefully when configuring the VM for secure access + +--- + +## Success Criteria + +To complete this challenge successfully, you should be able to: + +- Verify you can authenticate to Azure from GitHub Codespaces using `az login` +- Show that Python and required packages (`azure-ai-projects`, `azure-identity`) are installed +- Demonstrate that the VM is deployed, accessible via SSH, and has contributor permissions +- Confirm that your Codespaces terminal can interact with Azure AI Foundry resources + +--- + +## Advanced Challenges (Optional) + +If you want to go beyond the baseline setup: + +- Experiment with different VM sizes and regions +- Enable additional managed identities and role assignments for advanced testing +- Configure the Codespace to mount external repositories for agent collaboration diff --git a/xxx-AgenticAIApps/Student/Challenge-01.md b/xxx-AgenticAIApps/Student/Challenge-01.md new file mode 100644 index 0000000000..9f1c10d08b --- /dev/null +++ b/xxx-AgenticAIApps/Student/Challenge-01.md @@ -0,0 +1,88 @@ +# Challenge 01 - Semantic Kernel Setup & Configuration + +[< Previous Challenge](./Challenge-00.md) - **[Home](./README.md)** - [Next Challenge >](./Challenge-02.md) + +--- + +## Pre-requisites + +- Completion of **Challenge 00 – Azure AI Foundry Onboarding & Environment Prep** +- Active **Azure AI Foundry** resource +- **GitHub Codespaces** environment ready +- `.env` file configured with your **Azure OpenAI** keys + +--- + +## Introduction + +In this challenge, you will set up **Semantic Kernel** inside your GitHub Codespaces environment. +Semantic Kernel provides the **cognitive layer** for your AI agents, enabling them to interpret instructions, generate structured plans, and execute actions. + +You’ll configure your environment to connect to Azure OpenAI services and prepare to create your first **agent skills**. +Later, these skills will be extended to work with live Azure telemetry data. + +--- + +## Description + +Your goal is to configure **Semantic Kernel** and establish the foundation for skill development. +This includes: + +- Initializing the kernel with **Azure OpenAI** credentials +- Testing a simple **prompt** to confirm connectivity +- Creating a `skills/` folder for skill development +- Preparing a skeleton for a **live Azure Monitor skill** (students implement core functionality) + +> **Note:** Some code sections are intentionally left incomplete for you to implement. Follow the hints and references below to complete the skill. + +--- + +### Skeleton Example (`azure_monitor_skill.py`) + +```python +# students complete building this section + +class AzureMonitorSkill: + def __init__(self): + # TODO: Initialize Azure credentials and MetricsQueryClient + pass + + def get_vm_cpu(self) -> str: + # TODO: Query Azure Monitor for VM CPU usage and return a string + pass +```` + +--- + + +## Learning Resources + +* [Semantic Kernel Documentation](https://learn.microsoft.com/en-us/semantic-kernel/overview) +* [Azure Monitor Metrics Query SDK](https://learn.microsoft.com/en-us/python/api/overview/azure/monitor-query-readme) +* [Azure Identity Python SDK](https://learn.microsoft.com/en-us/python/api/overview/azure/identity-readme) +* [GitHub Codespaces Basics](https://docs.github.com/en/codespaces/getting-started/quickstart) + +--- + +## Tips + +* Ensure your `.env` file has **no extra spaces or quotes** around values +* Test prompts incrementally to confirm **connectivity** before implementing skills +* Use the learning resources to guide your **Azure Monitor queries** +* Keep your class methods small, modular, and focused for easier debugging + +--- + +## Success Criteria + +To complete this challenge successfully, you should be able to: + +1. Validate that **Semantic Kernel** initializes correctly with Azure OpenAI credentials +2. Verify that a **test prompt** returns a meaningful response +3. Demonstrate that the `skills/` folder exists and contains at least one skill skeleton (`AzureMonitorSkill`) +4. Explain how the kernel can be extended to pull **live telemetry** from Azure + + +[< Previous Challenge](./Challenge-00.md) - **[Home](./README.md)** - [Next Challenge >](./Challenge-02.md) + +``` diff --git a/xxx-AgenticAIApps/Student/Challenge-02.md b/xxx-AgenticAIApps/Student/Challenge-02.md new file mode 100644 index 0000000000..52cd464ccd --- /dev/null +++ b/xxx-AgenticAIApps/Student/Challenge-02.md @@ -0,0 +1,181 @@ +# Challenge 02 - Build the Anomaly Detector Agent (Real Azure Metrics) + +**[Home](./README.md)** - [Next Challenge >](./Challenge-03.md) + +--- + +## Introduction + +In this challenge, you’ll build your first **intelligent agent** — the **Anomaly Detector Agent**. This agent will use **Semantic Kernel** to analyze **live Azure Monitor metrics** and detect when your virtual machine experiences performance anomalies (for example, high CPU or memory usage). + +By the end of this challenge, you’ll have a functional AI-driven process that monitors your Azure resources and flags abnormal behavior — forming the foundation for your next, self-healing agent. + +--- + +## Description + +You will extend your existing environment (from Challenge 01) by creating a new skill and agent capable of: + +- Reading **real telemetry data** (CPU, Memory, Disk I/O) from your Azure VM +- Comparing metric values to defined thresholds +- Reporting an **anomaly detected** message when metrics exceed limits + +This challenge focuses on **logic building**, **skill registration**, and **data reasoning** using Semantic Kernel. + +--- + + +### Confirm Your Setup + +Before building your agent: + +- Ensure your `.env` file includes your Azure credentials. +- Confirm that your **Azure Monitor Skill** from Challenge 01 works and returns live metrics. + +You can quickly test it by running: + +```bash +python test_kernel.py +```` + +✅ You should see something like: + +``` +Current CPU usage: 23.54% +``` + +--- + +### Create the Anomaly Detector Skill + +In the `skills/` folder, create a new file named `anomaly_detector_skill.py`. + +Inside this file, you will: + +* Define a class called `AnomalyDetectorSkill` +* Set threshold values for CPU and Memory +* Add a function called `detect_anomaly()` that checks for high usage and returns a message + +Start with the following structure and fill in the logic where marked: + +```python +from semantic_kernel.skill_definition import sk_function + +class AnomalyDetectorSkill: + def __init__(self, cpu_threshold: float = 80.0, memory_threshold: float = 85.0): + self.cpu_threshold = cpu_threshold + self.memory_threshold = memory_threshold + + @sk_function(name="detect_anomaly", description="Detect if system metrics exceed normal thresholds") + def detect_anomaly(self, cpu_usage: float, memory_usage: float) -> str: + """ + TODO: Compare metric values against thresholds. + If CPU or memory usage exceeds their threshold, + return a message describing the anomaly. + Otherwise, return a message that the system is normal. + """ +``` + +--- + +### Create the Anomaly Detector Agent + +Now, in the `agents/` folder, create a file called `anomaly_detector_agent.py`. + +This agent will: + +* Initialize the Semantic Kernel +* Register both the `AzureMonitorSkill` and your new `AnomalyDetectorSkill` +* Retrieve CPU and memory data +* Pass it into your anomaly detection skill and print the result + +Use this as your starter template: + +```python +import asyncio +from semantic_kernel import Kernel +from skills.azure_monitor_skill import AzureMonitorSkill +from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion + +# TODO: Import your new AnomalyDetectorSkill here + +async def main(): + kernel = Kernel() + kernel.add_service( + AzureChatCompletion( + service_id="chatcompletion", + deployment_name="your-deployment", + endpoint="your-endpoint", + api_key="your-api-key" + ) + ) + + kernel.import_skill(AzureMonitorSkill(), "azure_monitor") + + # TODO: + # 1. Import and register the AnomalyDetectorSkill. + # 2. Retrieve live metrics using the Azure Monitor skill. + # 3. Pass the metrics to your anomaly detection function. + # 4. Print the result. + +if __name__ == "__main__": + asyncio.run(main()) +``` + +--- + +### Test Your Agent + +Run your agent script: + +```bash +python agents/anomaly_detector_agent.py +``` + +✅ Expected Output: + +``` +CPU anomaly detected: 91.3% exceeds 80.0% +``` + +or + +``` +System metrics are within normal range. +``` + +--- + +### Learning Resources + +These resources will help you complete the challenge: + +* [Semantic Kernel Documentation](https://learn.microsoft.com/en-us/semantic-kernel/) +* [Azure Monitor Python SDK](https://learn.microsoft.com/en-us/python/api/overview/azure/monitor-query-readme) +* [Anomaly Detection in Azure](https://learn.microsoft.com/en-us/azure/ai-services/anomaly-detector/overview) +* [AsyncIO in Python](https://docs.python.org/3/library/asyncio.html) + +--- + +## Success Criteria + +To successfully complete Challenge 02, you should be able to: + +- Verify that the **Anomaly Detector Agent** initializes without errors. +- Confirm that live metrics from your Azure VM (CPU, Memory, Disk I/O) are retrieved correctly. +- Demonstrate that the agent **detects anomalies** when metrics exceed defined thresholds. +- Show that the agent prints appropriate messages for both normal and anomalous states. +- Ensure that the skill and agent are **registered and callable** via Semantic Kernel. + + +--- + +## Next Steps + +Proceed to **[Challenge 03 – Build the Resource Optimizer Agent](./Challenge-03.md)** to: + +* Respond to detected anomalies with remediation actions +* Enable multi-agent communication (Agent-to-Agent protocol) +* Begin orchestrating self-healing AI systems in Azure + +``` diff --git a/xxx-AgenticAIApps/Student/Challenge-03.md b/xxx-AgenticAIApps/Student/Challenge-03.md new file mode 100644 index 0000000000..5e951c241e --- /dev/null +++ b/xxx-AgenticAIApps/Student/Challenge-03.md @@ -0,0 +1,173 @@ +# Challenge 03 - Build the Resource Optimizer Agent (Real Azure Integration) + +[< Previous Challenge](./Challenge-02.md) - **[Home](./README.md)** - [Next Challenge >](./Challenge-04.md) + +--- + +## Pre-requisites + +- Completion of **Challenge 02 – Anomaly Detection Agent** +- Active **Azure subscription** with access to a **Virtual Machine (VM)** +- `.env` file configured with your Azure details +- Working **Semantic Kernel setup** from previous challenges + +--- + +## Introduction + +In this challenge, you will build a **Resource Optimizer Agent** capable of analyzing telemetry data (like CPU, memory, and disk usage) and performing **real optimization actions** in Azure using the **Azure Management SDK**. + +Your agent will listen for anomaly alerts and intelligently recommend or perform optimizations (like scaling VMs or restarting services). + +This challenge introduces real-world **Azure SDK integration** — connecting the AI layer (Semantic Kernel) with the **Azure Compute Management API**. + +--- + +## Description + +You’ll create and test a **Resource Optimizer Agent** that: +- Receives alerts about CPU, memory, or disk usage +- Determines an appropriate optimization strategy +- Executes the optimization using the **Azure SDK** + +> ⚠️ **Note:** Parts of the code are intentionally left incomplete. +> Fill in the missing functions to make your agent operational. + +--- + +### Environment Setup + +Install required SDKs: + +```bash +pip install azure-mgmt-compute azure-identity python-dotenv +```` + +Update your `.env` file with your Azure resource details: + +```env +AZURESUBSCRIPTIONID=your-subscription-id +AZURERESOURCEGROUP=your-resource-group +AZUREVMNAME=your-vm-name +``` + +--- + +### Create `resource_optimizer.py` + +```python +import os +from azure.identity import DefaultAzureCredential +from azure.mgmt.compute import ComputeManagementClient +from azure.ai.foundry import Agent, Message, Thread +from dotenv import load_dotenv + +load_dotenv() + +class ResourceOptimizerAgent(Agent): + def init(self): + super().init(name="resource-optimizer") + + # TODO: Initialize Azure credentials and compute client + # Hint: Use DefaultAzureCredential() and ComputeManagementClient() + self.subscription_id = os.getenv("AZURESUBSCRIPTIONID") + self.resource_group = os.getenv("AZURERESOURCEGROUP") + self.vm_name = os.getenv("AZUREVMNAME") + pass + + def run(self, thread: Thread, message: Message): + print("Optimizer received:", message.content) + response = "" + + # TODO: Parse the message and decide what optimization to perform + # Example: if "CPU" in message.content → call self.scale_vm("Standard_DS2_v2") + + thread.send_message(Message(content=response, role="agent")) + + def scale_vm(self, new_size): + # TODO: Implement VM scaling logic using Azure SDK + # Hint: Retrieve the VM, modify its hardware profile, and use begin_create_or_update() + pass +``` + +--- + +### Register the Agent + +Create a new file named `register_optimizer.py`: + +```python +from azure.ai.foundry import AgentClient +from resource_optimizer import ResourceOptimizerAgent + +client = AgentClient() +agent = ResourceOptimizerAgent() +client.register_agent(agent) +``` + +Run the registration script: + +```bash +python register_optimizer.py +``` + +--- + +### Test the Agent + +Create a new test file named `test_optimizer.py`: + +```python +from azure.ai.foundry import AgentClient + +client = AgentClient() +thread = client.create_thread() +client.send_message(thread.id, "⚠️ Anomaly detected: Percentage CPU = 92", agent_name="resource-optimizer") +``` + +Then execute: + +```bash +python test_optimizer.py +``` + +--- + +## Learning Resources + +* [Azure SDK for Python Documentation](https://learn.microsoft.com/en-us/python/api/overview/azure/) +* [Azure Compute Management Client](https://learn.microsoft.com/en-us/python/api/overview/azure/compute) +* [Azure Identity SDK](https://learn.microsoft.com/en-us/python/api/overview/azure/identity-readme) +* [Semantic Kernel Overview](https://learn.microsoft.com/en-us/semantic-kernel/overview) +* [Anomaly Detector Overview](https://learn.microsoft.com/en-us/azure/ai-services/anomaly-detector/overview) + +--- + +## Tips + +* If you encounter authentication issues, ensure **Azure CLI** is logged in (`az login`). +* Start by **printing** messages before implementing full scaling logic. +* Use **try/except** around Azure SDK calls to handle errors gracefully. +* You can safely simulate optimization responses before executing real operations. + +--- + +## Success Criteria + +To successfully complete Challenge 03, you should be able to: + +- Register and initialize the **Resource Optimizer Agent** without errors. +- Receive and display incoming anomaly messages correctly. +- Demonstrate that the agent can parse telemetry and respond (either by executing or simulating optimization). +- Confirm the agent is connected to **Semantic Kernel** and the **Azure SDK**. + +--- + +## Next Steps + +Once your **Resource Optimizer Agent** is working, move to **Challenge 04**, where you’ll build an **Alert Manager Agent** that coordinates notifications and alert responses across your system. + +[< Previous Challenge](./Challenge-02.md) - **[Home](./README.md)** - [Next Challenge >](./Challenge-04.md) + +``` + diff --git a/xxx-AgenticAIApps/Student/Challenge-04.md b/xxx-AgenticAIApps/Student/Challenge-04.md new file mode 100644 index 0000000000..dbb8515d0b --- /dev/null +++ b/xxx-AgenticAIApps/Student/Challenge-04.md @@ -0,0 +1,171 @@ +# Challenge 04 - Build the Alert Manager Agent (Live Azure Integration) + +[< Previous Challenge](./Challenge-03.md) - **[Home](./README.md)** - [Next Challenge >](./Challenge-05.md) + +## Pre-requisites + +- Completion of Challenge 03 – Resource Optimizer Agent +- Active Azure subscription with Monitor and Action Groups access +- `.env` file updated with your Azure subscription, resource group, and action group name +- Installed dependencies: + + ```bash + pip install azure-monitor-query azure-identity azure-mgmt-monitor python-dotenv + ``` + +--- + +## Introduction + +In this challenge, you’ll create the **Alert Manager Agent**, responsible for notifying stakeholders when anomalies or optimization events occur. +This agent integrates with **Azure Monitor** and **Action Groups**, allowing your system to deliver real-time alerts about critical events. + +You’ll implement alerting logic, test it in a safe “simulation” mode, and prepare it to handle live alerts in later challenges. + +--- + +## Description + +Your goal is to build an agent that listens for incoming messages about anomalies or optimization results, and sends alerts using Azure Monitor or your chosen notification service. + +You’ll: + +* Create the **Alert Manager Agent** +* Detect when an anomaly or optimization event occurs +* Send (or simulate sending) alerts +* Ensure alerts appear in the terminal or Azure Action Group log + +> **Note:** Some code sections are intentionally left incomplete — you’ll implement the core alert logic and message handling yourself. + +--- + +### Create the Agent + +Create a new file called `alert_manager.py`: + +```python +import os +from azure.identity import DefaultAzureCredential +from azure.mgmt.monitor import MonitorManagementClient +from azure.ai.foundry import Agent, Message, Thread +from dotenv import load_dotenv + +load_dotenv() + +class AlertManagerAgent(Agent): + def init(self): + super().init(name="alert-manager") + self.subscription_id = os.getenv("AZURESUBSCRIPTIONID") + self.resource_group = os.getenv("AZURERESOURCEGROUP") + + # TODO: Initialize the Azure Monitor client here + # Example: + # self.monitor_client = MonitorManagementClient( + # credential=DefaultAzureCredential(), + # subscription_id=self.subscription_id + # ) + + def run(self, thread: Thread, message: Message): + print("Alert Manager received:", message.content) + + # TODO: Detect anomaly or optimization message + # if "Anomaly" in message.content or "Optimization" in message.content: + # alert_msg = f"🚨 Alert triggered: {message.content}" + # thread.send_message(Message(content=alert_msg, role="agent")) + # print("Sending alert to Azure Monitor action group…") + # self.send_alert(alert_msg) + + def send_alert(self, alert_msg): + # TODO: Implement your alert-sending logic (can be simulated for testing) + # print(f"Simulated alert sent: {alert_msg}") + pass +``` + +--- + +### Register the Agent + +Create a file named `register_alert.py`: + +```python +from azure.ai.foundry import AgentClient +from alert_manager import AlertManagerAgent + +client = AgentClient() +agent = AlertManagerAgent() +client.register_agent(agent) +``` + +Run the registration: + +```bash +python register_alert.py +``` + +--- + +### Test the Agent + +Create a file named `test_alert.py`: + +```python +from azure.ai.foundry import AgentClient + +client = AgentClient() +thread = client.create_thread() + +# Simulate a message from the optimizer or anomaly agent +client.send_message( + thread.id, + "⚠️ Optimization failed due to high CPU usage", + agent_name="alert-manager" +) +``` + +Run the test: + +```bash +python test_alert.py +``` + + **Expected Output Example:** + +``` +Alert Manager received: ⚠️ Optimization failed due to high CPU usage +🚨 Alert triggered: ⚠️ Optimization failed due to high CPU usage +Simulated alert sent: 🚨 Alert triggered: ⚠️ Optimization failed due to high CPU usage +``` + +--- + +## Learning Resources + +* [Azure Monitor Overview](https://learn.microsoft.com/en-us/azure/azure-monitor/overview) +* [Azure Monitor Action Groups](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/action-groups) +* [Azure Identity Python SDK](https://learn.microsoft.com/en-us/python/api/overview/azure/identity-readme) +* [Semantic Kernel Python Docs](https://learn.microsoft.com/en-us/semantic-kernel/overview/) + +--- + +## Tips + +* Keep your `.env` file clean (no quotes or extra spaces). +* You can safely test alerts by printing them to the terminal before enabling live alerts. +* Once verified, you can extend `send_alert()` to send real alerts through Azure Monitor’s **Action Groups** or webhooks. + +--- + +## Success Criteria + +To complete this challenge successfully, you should: + +* Create and register an `AlertManagerAgent` class +* Implement message detection for anomalies or optimizations +* Simulate or send an alert through `send_alert()` +* Verify + +## Next Steps + +Proceed to **Challenge 05** to build the **Agent-to-Agent Communication Layer**, enabling collaboration and orchestration between all agents. + +``` diff --git a/xxx-AgenticAIApps/Student/Challenge-05.md b/xxx-AgenticAIApps/Student/Challenge-05.md new file mode 100644 index 0000000000..d0ad83ef2a --- /dev/null +++ b/xxx-AgenticAIApps/Student/Challenge-05.md @@ -0,0 +1,129 @@ +# Challenge 05 - Orchestrate Agent-to-Agent Communicatio + +[< Previous Challenge](./Challenge-04.md) - **[Home](./README.md)** - [Next Challenge >](./Challenge-06.md) + +## Introduction + +In this challenge, you will connect all of your agents—**Anomaly Detector**, **Resource Optimizer**, and **Alert Manager**—into a unified communication system using an **Agent Orchestrator**. + +This orchestrator will serve as the bridge that enables agents to pass messages, share context, and execute tasks in sequence. + +You will explore: +- How agents communicate through threads using the Azure AI Foundry SDK +- How to design message routing between independent components +- The foundations of semantic coordination for intelligent multi-agent workflows + +By completing this challenge, you’ll be able to design scalable, modular agent architectures where autonomous components work together in real time. + +--- + +## Description + +Your task is to **implement the Agent Orchestrator** that manages the communication between your existing agents. + +## Learning Resources + + +You will create two files: +- `agent_orchestrator.py` — defines the orchestration logic +- `run_orchestrator.py` — runs the orchestrator to test communication between agents + +The orchestrator should: +- Create a shared communication thread +- Trigger the **Anomaly Detector Agent** to check system metrics +- Trigger the **Resource Optimizer Agent** to respond to detected issues +- Trigger the **Alert Manager Agent** to notify stakeholders +- Display console messages confirming each step + +Below is the incomplete code you will build upon: + +```python +from azure.ai.foundry import AgentClient, Thread +from dotenv import load_dotenv +import os + +load_dotenv() + +class AgentOrchestrator: + def __init__(self): + self.client = AgentClient() + self.agents = { + "anomaly": "anomaly-detector", + "optimizer": "resource-optimizer", + "alert": "alert-manager" + } + + def create_thread(self): + # TODO: Create and return a new Thread + pass + + def send_to_agent(self, thread: Thread, agent_key: str, message: str): + # TODO: Send a message to a specific agent using the client + pass + + def orchestrate(self): + # TODO: Implement the orchestration flow: + # 1. Trigger anomaly detector + # 2. Trigger resource optimizer + # 3. Trigger alert manager + pass +```` + +To execute your orchestrator, create a new script called `run_orchestrator.py`: + +```python +from agent_orchestrator import AgentOrchestrator + +orchestrator = AgentOrchestrator() +orchestrator.orchestrate() +``` + +When you run this file, your output should look similar to: + +``` + Step 1: Trigger Anomaly Detector + Step 2: Trigger Resource Optimizer + Step 3: Trigger Alert Manager + Orchestration complete. +``` + +--- + + +## Learning Resources + +* [Azure AI Foundry Overview](https://learn.microsoft.com/en-us/azure/ai-services/) +* [Azure Anomaly Detector Overview](https://learn.microsoft.com/en-us/azure/ai-services/anomaly-detector/overview) +* [Microsoft Semantic Kernel Documentation](https://learn.microsoft.com/en-us/semantic-kernel/) +* [Threading in Python (Real Python)](https://realpython.com/intro-to-python-threading/) +* [Introduction to Multi-Agent Systems (Microsoft Learn)](https://learn.microsoft.com/en-us/azure/ai-services/) + +--- + +## Tips + +* Ensure your previous agents (Anomaly Detector, Resource Optimizer, Alert Manager) are correctly registered +* Test each message exchange individually before running the full orchestration +* Use logging statements to visualize the flow of messages between agents +* If you encounter threading errors, print the thread ID after creation to confirm proper initialization + +--- + +## Success Criteria + +To complete this challenge successfully, you should be able to: + +* Validate that the orchestrator successfully creates a thread +* Verify that each agent receives and processes its assigned message +* Demonstrate that the console output confirms all three agent triggers +* Optionally, extend the orchestrator with a planning mechanism to dynamically decide which agent to trigger next + +--- + +## Next Steps + +After completing the Agent Orchestrator, you are ready to move on to **Challenge 06**, where you will implement **multi-agent planning and dynamic task scheduling** using Semantic Kernel. + +This next challenge will build on your orchestrator to enable agents to make intelligent decisions, prioritize tasks, and collaborate autonomously based on real-time data. + +``` diff --git a/xxx-AgenticAIApps/Student/Challenge-06.md b/xxx-AgenticAIApps/Student/Challenge-06.md new file mode 100644 index 0000000000..0b1b2d1266 --- /dev/null +++ b/xxx-AgenticAIApps/Student/Challenge-06.md @@ -0,0 +1,114 @@ +# Challenge 06 - Enable Agent-to-Agent Communication (A2A) + +[< Previous Challenge](./Challenge-05.md) - **[Home](../README.md)** - [Next Challenge >](./Challenge-07.md) + +## Introduction + +In this challenge, you will enhance your multi-agent system by enabling **direct communication between agents**. + +Your agents—**Anomaly Detector**, **Resource Optimizer**, and **Alert Manager**—will now share context and coordinate actions dynamically through a **shared thread**. + +This step transforms your system from a static orchestration sequence into a **fully agentic network**, allowing agents to collaborate intelligently and make decisions based on previous outputs. + +You will also explore optional **Semantic Kernel integration** for dynamic planning and goal-driven agent behavior. + +--- + +## Description + +Your task is to extend the orchestrator from Challenge 05 to enable **agent-to-agent communication**. + +You will: + +- Update `agent_orchestrator.py` to implement dynamic routing through shared threads. +- Ensure agents can read messages from the thread, respond appropriately, and pass results to the next agent. +- Optionally integrate Semantic Kernel for intelligent, goal-based agent planning. +- Modify `app.py` (if using a UI) to call the new dynamic orchestrator method. + +Below is a partial skeleton for your orchestrator logic. Complete the missing functionality: + +```python +def orchestratedynamic(self, user_input): + thread = self.create_thread() + + # Step 1: Anomaly Detector + self.send_to_agent(thread, "anomaly", user_input) + + # Step 2: Read anomaly message + messages = self.get_thread_messages(thread) + anomaly_msg = next((m.content for m in messages if "Anomaly" in m.content), None) + + # Step 3: Resource Optimizer + if anomaly_msg: + self.send_to_agent(thread, "optimizer", anomaly_msg) + + # Step 4: Read optimization message + messages = self.get_thread_messages(thread) + optimization_msg = next((m.content for m in messages if "🛠️" in m.content), None) + + # Step 5: Alert Manager + if optimization_msg: + self.send_to_agent(thread, "alert", optimization_msg) + + return self.get_thread_messages(thread) +```` + +### Optional: Semantic Kernel Planning + +You may optionally add **goal-driven orchestration**: + +```python +from semantickernel import Kernel + +kernel = Kernel() +plan = kernel.create_plan("Detect and respond to system anomalies") +for step in plan.steps: + orchestrator.send_to_agent(thread, step.plugin_name, step.description) +``` + +This enables your orchestrator to decide dynamically which agent to call next based on the context. + +--- + + +## Learning Resources + +* [Azure AI Foundry Overview](https://learn.microsoft.com/en-us/azure/ai-services/) +* [Python Threading & Concurrency](https://realpython.com/intro-to-python-threading/) +* [Introduction to Multi-Agent Systems](https://learn.microsoft.com/en-us/azure/architecture/guide/ai/design-multi-agent-systems) +* [Empowering Multi-Agent Apps with the Open Agent2Agent (A2A) Protocol](https://www.microsoft.com/en-us/microsoft-cloud/blog/2025/05/07/empowering-multi-agent-apps-with-the-open-agent2agent-a2a-protocol/?utm_source=chatgpt.com) + +--- + +## Tips + +* Test each agent individually before running the full orchestrator. +* Use logging statements to visualize message flow in the shared thread. +* Make sure thread messages are correctly tagged with agent names to aid debugging. +* Start simple: first pass static messages, then add dynamic routing logic. + + +--- + +## Success Criteria + +To complete this challenge successfully, you should be able to: + +* Verify that all three agents communicate through a shared thread. +* Confirm that messages from one agent are correctly routed to the next. +* Demonstrate console output showing step-by-step interactions: + +``` +anomaly-detector: Anomaly detected: CPU = 92% +resource-optimizer: Scaling VM to Standard_DS2_v2 +alert-manager: Alert sent: VM scaled successfully +``` + +* Optionally, show dynamic routing with Semantic Kernel if implemented. +--- + +## Next Steps + +Proceed to **Challenge 07** to implement **memory persistence**, long-term knowledge storage, and context-aware planning to make your agents even more autonomous and intelligent. + +``` diff --git a/xxx-AgenticAIApps/Student/Challenge-07.md b/xxx-AgenticAIApps/Student/Challenge-07.md new file mode 100644 index 0000000000..fe9efb0c6f --- /dev/null +++ b/xxx-AgenticAIApps/Student/Challenge-07.md @@ -0,0 +1,155 @@ +# Challenge 07 - Build the Anomaly & Resolution Tracker + +[< Previous Challenge](./Challenge-06.md) - **[Home](./README.md)** - [Next Challenge >](./Challenge-08.md) + +## Introduction + +In this challenge, you will build a **tracking system** to log anomalies detected by your **Anomaly Detector Agent** and resolutions applied by your **Resource Optimizer Agent**. + +This system will help you visualize events in real time and optionally integrate with dashboards like **Streamlit**, **Power BI**, or **Azure Workbooks**. + +You will explore: +- Logging and storing agent actions +- Structuring log data for clarity +- Visualizing agent activity locally or in the cloud +- Optional integration with Azure storage services for persistence + +--- + +## Description + +Your task is to **implement anomaly and resolution tracking** for your agent system. + +Key goals: +- Create logging for both anomaly detection and resolution events +- Maintain a **consistent log format** for easy parsing and visualization +- Optionally build a **Streamlit dashboard** to view logs interactively +- Optionally store logs in **Azure Table Storage** or **Cosmos DB** for cloud-based tracking + +Skeleton example for logging: + +### Anomaly Detector Agent + +```python +import logging + +logging.basicConfig(filename='agent_log.txt', level=logging.INFO, format='[%(asctime)s] %(message)s') + +def log_anomaly(metric, value): + # TODO: Call this function whenever an anomaly is detected + logging.info(f"Anomaly Detected: {metric} = {value}") +```` + +### Resource Optimizer Agent + +```python +def log_resolution(action): + # TODO: Call this function after performing a resolution + logging.info(f"Resolution Applied: {action}") +``` + +--- + +### Log Format Example + +``` +[2025-08-21 14:32:10] Anomaly Detected: CPU = 92% +[2025-08-21 14:32:15] Resolution Applied: Scaled VM to Standard_DS2_v2 +``` + +> **Tip:** Using timestamps helps track and visualize event sequences effectively. + +--- + +### Optional — Streamlit Dashboard + +Create **`dashboard.py`**: + +```python +import streamlit as st + +st.title("🔍 Anomaly & Resolution Tracker") + +with open("agent_log.txt") as f: + logs = f.readlines() + +for line in logs: + st.text(line.strip()) +``` + +Run the dashboard: + +```bash +streamlit run dashboard.py +``` + +--- + +### Optional — Azure Storage Integration + +**Azure Table Storage** + +```bash +pip install azure-data-tables +``` + +```python +from azure.data.tables import TableServiceClient +from datetime import datetime +import os + +service = TableServiceClient.from_connection_string(conn_str=os.getenv("AZURE_STORAGE_CONNECTION_STRING")) +table_client = service.get_table_client(table_name="AgentLogs") + +def log_to_table(event_type, detail): + entity = { + "PartitionKey": "AgentLogs", + "RowKey": str(datetime.utcnow().timestamp()), + "EventType": event_type, + "Detail": detail + } + table_client.create_entity(entity) +``` + +**Azure Cosmos DB** can also be used to store structured JSON logs for advanced analytics. + +--- + +## Success Criteria + +To complete this challenge successfully, you should be able to: + +* Validate that the **Anomaly Detector Agent** logs anomalies +* Validate that the **Resource Optimizer Agent** logs resolutions +* Demonstrate that logs are readable and follow a consistent format +* Optionally show the **Streamlit dashboard** displaying live logs +* Optionally store and retrieve logs from **Azure Table Storage** or **Cosmos DB** + +--- + +## Learning Resources + +* [Python Logging Module](https://docs.python.org/3/library/logging.html) – Learn how to log messages with timestamps +* [Streamlit Documentation](https://docs.streamlit.io/) – Guide to building interactive dashboards +* [Azure Data Tables](https://learn.microsoft.com/en-us/azure/storage/tables/table-storage-overview) – Overview of Azure Table Storage +* [Azure Cosmos DB Python SDK](https://learn.microsoft.com/en-us/python/api/overview/azure/cosmos-db?view=azure-python) – Learn to store JSON documents in Cosmos DB + +--- + +## Tips + +* Start by logging to a local file before moving to cloud storage +* Keep log formats consistent for easier visualization +* Use small sample data to verify the Streamlit dashboard works before scaling + +--- + +## Next Steps + +Proceed to **Challenge 08** to extend your tracking system with: + +* Persistent memory across agent sessions +* Advanced analytics for anomaly trends +* Automated reporting using Azure AI Foundry + +``` diff --git a/xxx-AgenticAIApps/Student/Challenge-08.md b/xxx-AgenticAIApps/Student/Challenge-08.md new file mode 100644 index 0000000000..7604922ad2 --- /dev/null +++ b/xxx-AgenticAIApps/Student/Challenge-08.md @@ -0,0 +1,141 @@ +# Challenge 08 - Spike VM Resources & Test Agent Detection + +[< Previous Challenge](./Challenge-07.md) - **[Home](./README.md)** + +## Introduction + +In this challenge, you will temporarily **spike CPU and memory** on the Azure VM you have been maintaining since the initial challenges. + +The goal is to **test your agents** — Anomaly Detector, Resource Optimizer, and Alert Manager — and observe how they respond in real time. + +You will use the **provided test scripts** to generate the resource spike, so you do not need to write any additional agent code for this challenge. + +> **Important:** You must be connected to Azure using `az login` before starting this challenge, so your agents can access the VM telemetry and management APIs. + +--- + +## Description + +Students are expected to: + +- Use the provided stress scripts (`spike_vm.sh` for Linux/macOS or `spike_vm.ps1` for Windows) to create a temporary load on the VM. +- Run your agents using the provided orchestrator or test scripts (`test_anomaly.py` or `run_orchestrator.py`). +- Verify that your agents detect the anomalies and log or respond appropriately. +- Meet the success criteria to complete the What The Hack challenge. + +> **Important:** The VM used should be the same one you kept active from the initial challenges. This ensures continuity of testing and monitoring. + +--- + +## Learning Resources + +To help you complete this challenge and work with the VM: + +* [Connect to an Azure VM using SSH](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/ssh-from-windows) – Step-by-step guide for connecting to Linux VMs from your terminal. +* [Bash Basics for Beginners](https://www.gnu.org/software/bash/manual/bash.html) – Introduction to Bash scripting and commands. +* [Linux Command Line Tutorial](https://ryanstutorials.net/linuxtutorial/) – Learn basic Linux commands and navigation. +* [Azure CLI Documentation](https://learn.microsoft.com/en-us/cli/azure/) – How to interact with Azure resources using `az login` and CLI commands. + +--- + +### Establish a Baseline + +Before spiking resources, confirm your agents report **no anomalies**: + +```bash +python test_anomaly.py +# or +python run_orchestrator.py +```` + +This establishes the baseline for detecting changes. + +--- + +### Run the Stress Script + +**Linux/macOS – `spike_vm.sh`** + +```bash +chmod +x spike_vm.sh +./spike_vm.sh 45 1024 +``` + +**Windows – `spike_vm.ps1`** + +```powershell +Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force +.\spike_vm.ps1 -Duration 45 +``` + +These scripts will temporarily increase CPU and memory usage on the VM. + +--- + +### Run Agents During Spike + +Immediately after starting the spike: + +```bash +python test_anomaly.py +# or +python run_orchestrator.py +``` + +* **Anomaly Detector Agent** should detect high CPU/memory. +* **Resource Optimizer Agent** may suggest scaling or other resolutions. +* **Alert Manager Agent** may log or simulate alerts. + +--- + +### Verify Logs + +```bash +# Linux/macOS +tail -f agent_log.txt + +# Windows PowerShell +Get-Content .\agent_log.txt -Wait +``` + +Expected entries: + +``` +[2025-10-11 15:22:00] Anomaly Detected: CPU = 98% +[2025-10-11 15:22:05] Resolution Applied: Suggested VM scale-up +``` + +--- + +### Stop the Stress Script + +**Linux/macOS:** + +```bash +pkill -f 'md5sum' +``` + +**Windows PowerShell:** + +```powershell +Get-Job | Where-Object { $_.State -eq 'Running' } | ForEach-Object { Stop-Job -Job $_; Remove-Job -Job $_ } +Remove-Variable memBlocks -ErrorAction SilentlyContinue -Scope Global +[GC]::Collect(); [GC]::WaitForPendingFinalizers() +Write-Host "Stress jobs stopped and memory released." +``` + +--- + +## Success Criteria + +To successfully complete this challenge (and the What The Hack challenge), students must: + +* Run the **provided spike script** on the maintained VM. +* Show that all agents detect anomalies during the spike. +* Demonstrate that resolutions or recommendations are logged correctly. +* Optionally, provide screenshots of agent alerts or Streamlit dashboard updates. + +> **Completion of this step successfully indicates that your agents are functioning correctly and the challenge is complete.** + +--- + diff --git a/xxx-AgenticAIApps/Student/Challenge-09.md b/xxx-AgenticAIApps/Student/Challenge-09.md new file mode 100644 index 0000000000..8f01390dc7 --- /dev/null +++ b/xxx-AgenticAIApps/Student/Challenge-09.md @@ -0,0 +1,99 @@ +# Challenge 09 - + +[< Previous Challenge](./Challenge-08.md) - **[Home](../README.md)** + +***This is a template for a single challenge. The italicized text provides hints & examples of what should or should NOT go in each section. You should remove all italicized & sample text and replace with your content.*** + +## Pre-requisites (Optional) + +*Your hack's "Challenge 0" should cover pre-requisites for the entire hack, and thus this section is optional and may be omitted. If you wish to spell out specific previous challenges that must be completed before starting this challenge, you may do so here.* + +## Introduction + +*This section should provide an overview of the technologies or tasks that will be needed to complete the this challenge. This includes the technical context for the challenge, as well as any new "lessons" the attendees should learn before completing the challenge.* + +*Optionally, the coach or event host is encouraged to present a mini-lesson (with a PPT or video) to set up the context & introduction to each challenge. A summary of the content of that mini-lesson is a good candidate for this Introduction section* + +*For example:* + +When setting up an IoT device, it is important to understand how 'thingamajigs' work. Thingamajigs are a key part of every IoT device and ensure they are able to communicate properly with edge servers. Thingamajigs require IP addresses to be assigned to them by a server and thus must have unique MAC addresses. In this challenge, you will get hands on with a thingamajig and learn how one is configured. + +## Description + +*This section should clearly state the goals of the challenge and any high-level instructions you want the students to follow. You may provide a list of specifications required to meet the goals. If this is more than 2-3 paragraphs, it is likely you are not doing it right.* + +***NOTE:** Do NOT use ordered lists as that is an indicator of 'step-by-step' instructions. Instead, use bullet lists to list out goals and/or specifications.* + +***NOTE:** You may use Markdown sub-headers to organize key sections of your challenge description.* + +*Optionally, you may provide resource files such as a sample application, code snippets, or templates as learning aids for the students. These files are stored in the hack's `Student/Resources` folder. It is the coach's responsibility to package these resources into a Resources.zip file and provide it to the students at the start of the hack.* + +***NOTE:** Do NOT provide direct links to files or folders in the What The Hack repository from the student guide. Instead, you should refer to the Resource.zip file provided by the coach.* + +***NOTE:** As an exception, you may provide a GitHub 'raw' link to an individual file such as a PDF or Office document, so long as it does not open the contents of the file in the What The Hack repo on the GitHub website.* + +***NOTE:** Any direct links to the What The Hack repo will be flagged for review during the review process by the WTH V-Team, including exception cases.* + +*Sample challenge text for the IoT Hack Of The Century:* + +In this challenge, you will properly configure the thingamajig for your IoT device so that it can communicate with the mother ship. + +You can find a sample `thingamajig.config` file in the `/ChallengeXX` folder of the Resources.zip file provided by your coach. This is a good starting reference, but you will need to discover how to set exact settings. + +Please configure the thingamajig with the following specifications: +- Use dynamic IP addresses +- Only trust the following whitelisted servers: "mothership", "IoTQueenBee" +- Deny access to "IoTProxyShip" + +You can view an architectural diagram of an IoT thingamajig here: [Thingamajig.PDF](/Student/Resources/Architecture.PDF?raw=true). + +## Success Criteria + +*Success criteria goes here. The success criteria should be a list of checks so a student knows they have completed the challenge successfully. These should be things that can be demonstrated to a coach.* + +*The success criteria should not be a list of instructions.* + +*Success criteria should always start with language like: "Validate XXX..." or "Verify YYY..." or "Show ZZZ..." or "Demonstrate you understand VVV..."* + +*Sample success criteria for the IoT sample challenge:* + +To complete this challenge successfully, you should be able to: +- Verify that the IoT device boots properly after its thingamajig is configured. +- Verify that the thingamajig can connect to the mothership. +- Demonstrate that the thingamajic will not connect to the IoTProxyShip + +## Learning Resources + +_List of relevant links and online articles that should give the attendees the knowledge needed to complete the challenge._ + +*Think of this list as giving the students a head start on some easy Internet searches. However, try not to include documentation links that are the literal step-by-step answer of the challenge's scenario.* + +***Note:** Use descriptive text for each link instead of just URLs.* + +*Sample IoT resource links:* + +- [What is a Thingamajig?](https://www.bing.com/search?q=what+is+a+thingamajig) +- [10 Tips for Never Forgetting Your Thingamajic](https://www.youtube.com/watch?v=dQw4w9WgXcQ) +- [IoT & Thingamajigs: Together Forever](https://www.youtube.com/watch?v=yPYZpwSpKmA) + +## Tips + +*This section is optional and may be omitted.* + +*Add tips and hints here to give students food for thought. Sample IoT tips:* + +- IoTDevices can fail from a broken heart if they are not together with their thingamajig. Your device will display a broken heart emoji on its screen if this happens. +- An IoTDevice can have one or more thingamajigs attached which allow them to connect to multiple networks. + +## Advanced Challenges (Optional) + +*If you want, you may provide additional goals to this challenge for folks who are eager.* + +*This section is optional and may be omitted.* + +*Sample IoT advanced challenges:* + +Too comfortable? Eager to do more? Try these additional challenges! + +- Observe what happens if your IoTDevice is separated from its thingamajig. +- Configure your IoTDevice to connect to BOTH the mothership and IoTQueenBee at the same time. diff --git a/xxx-AgenticAIApps/Student/Resources/.gitkeep b/xxx-AgenticAIApps/Student/Resources/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/xxx-AgenticAIApps/Student/Resources/requirements.txt b/xxx-AgenticAIApps/Student/Resources/requirements.txt new file mode 100644 index 0000000000..4963271651 --- /dev/null +++ b/xxx-AgenticAIApps/Student/Resources/requirements.txt @@ -0,0 +1,20 @@ +azure-ai-agents==1.0.2 +azure-ai-projects==1.0.0 +azure-core==1.35.0 +azure-identity==1.23.1 +azure-storage-blob==12.26.0 +certifi==2025.8.3 +cffi==1.17.1 +charset-normalizer==3.4.2 +cryptography==45.0.5 +idna==3.10 +isodate==0.7.2 +msal==1.33.0 +msal-extensions==1.3.1 +pycparser==2.22 +PyJWT==2.10.1 +requests==2.32.4 +six==1.17.0 +typing_extensions==4.14.1 +urllib3==2.5.0 +azure-monitor-query==1.0.0b4 \ No newline at end of file