Merge pull request #20 from MicrosoftCloudEssentials-LearningHub/md-improved

markdowns improved

Author: brown9804

README.md

@@ -5,7 +5,7 @@ Costa Rica
 [![GitHub](https://img.shields.io/badge/--181717?logo=github&logoColor=ffffff)](https://github.com/)
 [brown9804](https://github.com/brown9804)
 
-Last updated: 2026-01-29
+Last updated: 2026-02-02
 
 ----------
 
@@ -21,8 +21,10 @@ Last updated: 2026-01-29
 
 > E.g 
 
-<img width="1905" height="1086" alt="image" src="https://github.com/user-attachments/assets/5cd2776f-4606-45c2-9482-53ff2d4df74e" />
-
+<div align="center">
+  <img width="950" alt="image" src="https://github.com/user-attachments/assets/886cca9f-9630-4d5f-aca1-b4d37a42fa2d" style="border: 2px solid #4CAF50; border-radius: 5px; padding: 5px;"/>
+</div>
+  
 > [!IMPORTANT]
 > The deployment process typically takes 15-20 minutes
 >
@@ -32,51 +34,63 @@ Last updated: 2026-01-29
 
 ## Key Features
 
-- **Enhanced A2A Protocol**: Agent-to-Agent communication with delegation patterns, specialized agent coordination, and factual data integration
-- **6-Agent Architecture**: Specialized AI agents with proper delegation through A2A protocol:
+- **Multi-agent chat orchestration (default runtime)**: WebSocket `/ws` chat app orchestrates multiple agents in a single conversation flow (routing + multi-step handoffs)
+- **6-Agent Architecture (real Azure AI Foundry agents)**:
   - **Cora (Shopper)**: Front-facing assistant for general customer queries
-  - **Interior Design Specialist**: Design expertise and style recommendations  
-  - **Inventory Manager**: Stock availability and product lookup coordination
-  - **Customer Loyalty**: Rewards management and discount optimization
-  - **Cart Manager**: Shopping cart operations and checkout coordination
-  - **Product Management Specialist**: Coordinates with Marketing Agent, Ranker Agent, and Product Information Plugin for comprehensive product services
-- **Specialized Agent Delegation**: Product Manager delegates marketing tasks to Marketing Agent and ranking tasks to Ranker Agent as appropriate
-- **Factual Data Plugin**: Product Information Plugin provides accurate product catalog data from predefined sources
-- **Real MSFT Foundry Agents**: Integrates with **MSFT Foundry** to create and host persistent agents with proper delegation patterns
-- **Zero-Touch Deployment**: A single [terraform apply](./terraform-infrastructure/README.md) command handles the entire lifecycle including enhanced A2A framework deployment
-- **A2A Task Coordination**: Advanced inter-agent task delegation with specialized expertise routing
-- **Data Pipeline Automation**: Automatically ingests product catalogs with comprehensive A2A event coordination
+  - **Interior Design Specialist**: Design expertise and style recommendations
+  - **Inventory Manager**: Stock availability + product lookup coordination
+  - **Customer Loyalty**: Rewards and discount-related queries
+  - **Cart Manager**: Cart operations and checkout-oriented help
+  - **Product Management Specialist**: Handles product-centric workflows and coordinates lookups across services
+- **Intent routing + handoff planning**: Classifies user intent and plans a multi-step sequence of agent calls (instead of a single “one agent answers everything” flow)
+- **Factual data integration**: Uses **Azure AI Search** (vector/keyword retrieval) and **Azure Cosmos DB** (catalog/state) during workflows
+- **Real persistent agents**: Uses Azure AI Foundry Agents with saved runtime IDs (OpenAI-style `asst_*`) provisioned during deployment
+- **Zero-touch deployment**: `terraform apply` provisions infra, ingests data, creates/updates agents, wires secrets/config, and deploys the Container Apps revision
+- **UI-visible diagnostics**: Correlated `error_id` responses and optional tracebacks via `A2A_DEBUG=true` for faster troubleshooting
+- **Optional A2A server included**: `src/a2a/` contains an A2A-style server framework, but it is not the default Container Apps entrypoint unless you deploy it explicitly
 
 ## About A2A Protocol
 
-`A2A (Agent-to-Agent) Protocol is a standardized communication framework that enables multiple AI agents to collaborate and coordinate tasks seamlessly.`
+`A2A (Agent-to-Agent) Protocol is a standardized communication framework that enables multiple AI agents to collaborate and coordinate tasks seamlessly.` Like a communication pattern for coordinating multiple agents through structured messages, delegation, and (optionally) event-driven workflows.
+
+This repo contains **two multi-agent implementations**:
+
+- **Default deployed chat runtime (what the Dockerfile runs)**: WebSocket `/ws` in `src/chat_app_multi_agent.py`, which routes requests and orchestrates **real Azure AI Foundry Agents** in a multi-step handoff sequence.
+- **Optional A2A server implementation**: an A2A-style server under `src/a2a/` (routers, coordinator, event/task framework). Use this only if you deploy/run that entrypoint.
 
 > What is A2A Protocol?
 
-- **Agent-to-Agent Communication**: Structured messaging between multiple AI agents
-- **Task Coordination**: Agents can delegate tasks to specialized agents
-- **Event-Driven Architecture**: Real-time event handling for agent interactions
-- **Agent Discovery**: Automatic detection and registration of available agents
-- **Protocol Standardization**: Consistent API for inter-agent communication
+- **Agent-to-Agent Communication**: structured messaging between multiple agents
+- **Task Coordination**: agents can delegate tasks to specialized agents
+- **Event-Driven Architecture (optional)**: event handling for asynchronous workflows
+- **Agent Discovery (optional)**: enumerate/register available agents
+- **Protocol Standardization**: consistent message formats and APIs
 
-> A2A Components in This Project:
+> How this repo implements multi-agent collaboration (default deployment)
 
-- **Agent Execution Framework**: Manages multiple agent instances (`src/a2a/server/agent_execution.py`)
-- **Event System**: Handles inter-agent communication and delegation (`src/a2a/server/events/`)
-- **Task Coordination**: Advanced task delegation between specialized agents (`src/a2a/server/tasks.py`)
-- **Request Handlers**: Processes agent-to-agent requests with delegation routing (`src/a2a/server/request_handlers.py`)
-- **Coordinator Agent**: Orchestrates complex multi-agent workflows (`src/a2a/agent/coordinator.py`)
-- **Specialized Agents**: Marketing Agent, Ranker Agent with delegation patterns (`src/app/agents/`)
-- **Product Information Plugin**: Factual data source for product catalog (`src/app/agents/product_information_plugin.py`)
-- **API Endpoints**: RESTful and WebSocket APIs for enhanced agent communication (`src/a2a/api/`)
+- **WebSocket chat interface**: `/ws` endpoint served by `src/chat_app_multi_agent.py`
+- **Intent routing**: classifies the user request and selects the primary domain (`src/services/handoff_service.py`)
+- **Handoff planning**: builds a multi-step sequence of which agents to call (`src/chat_app_multi_agent.py`)
+- **Remote agent execution**: calls Azure AI Foundry Agents using the saved `asst_*` IDs (`src/app/agents/agent_processor.py`)
+- **Factual lookups**: uses Azure AI Search and Cosmos DB during workflows (called from the app runtime)
 
-> A2A vs Traditional Multi-Agent Systems:
+> A2A components included in this repo (optional server)
 
-- **Standardized Protocol**: Uses consistent message formats and APIs
-- **Scalable Architecture**: Easily add new agents without modifying existing ones
-- **Real-time Communication**: WebSocket support for instant agent interactions
-- **Event-Driven**: Asynchronous event handling for better performance
-- **Infrastructure Integration**: Full Terraform deployment with monitoring and automation
+- **A2A server entrypoint**: `src/a2a/main.py`
+- **A2A API routers**: `src/a2a/api/`
+- **Agent execution framework**: `src/a2a/server/agent_execution.py`
+- **Event system**: `src/a2a/server/events/`
+- **Task coordination**: `src/a2a/server/tasks.py`
+- **Request handlers**: `src/a2a/server/request_handlers.py`
+- **Coordinator**: `src/a2a/agent/coordinator.py`
+- **Agent implementations (examples)**: `src/app/agents/`
+- **Product catalog helper/plugin (if used)**: `src/app/agents/product_information_plugin.py`
+
+> [!IMPORTANT]
+> A2A vs the default deployed chat runtime
+>
+> - **A2A server path**: event/task oriented framework under `src/a2a/` (only available if you deploy/run that server)
+> - **Default path**: `/ws` WebSocket chat + routing + sequential handoffs to real Foundry agents (no event queue required for the default flow)
 
 ## Architecture
 
@@ -150,17 +164,17 @@ graph TD
         <https://github.com/user-attachments/assets/37c4a8cd-73e1-4392-8755-fb018481d8cb>
 
 4. **Enhanced Agent Creation & A2A Registration**:
-   - Installs the `azure-ai-projects` SDK and Microsoft Agent Framework.
-   - Connects to MSFT Foundry for agent hosting.
-   - Provisions 6 specialized agents with enhanced A2A protocol integration:
+   - Installs the Azure AI SDKs (`azure-ai-projects` + `azure-ai-agents`) and authenticates via Entra ID.
+   - Connects to MSFT Foundry / Agents API for agent hosting.
+   - Provisions 6 specialized agents with enhanced A2A-style routing:
      - Core shopping agents (5) plus Product Management Specialist
      - Marketing Agent and Ranker Agent with delegation patterns
      - Product Information Plugin with predefined catalog data
    - Registers all agents with the enhanced A2A discovery service.
    - Configures delegation relationships between Product Manager and specialized agents.
-   - Saves the unique Agent IDs, delegation endpoints, and A2A configuration to the `.env` file.
+   - Saves the unique runtime Agent IDs (OpenAI-style `asst_*`), endpoints, and configuration to the `.env` file.
 
-      > E.g `Classic UI`
+      > E.g `Web App approach`
       
       <img width="1881" height="1000" alt="image" src="https://github.com/user-attachments/assets/59a9dcaf-9291-403c-b8b0-1195c1375aac" />
 
@@ -170,26 +184,26 @@ graph TD
 
 5. **Application Deployment**:
    - Builds the Docker container with A2A protocol support in the cloud (ACR Build).
-   - Configures the Azure Web App with the generated Agent IDs, A2A endpoints, and credentials.
-   - Deploys the container with A2A server components and restarts the app.
+   - Deploys the container to Azure Container Apps (default) with the generated Agent IDs, endpoints, and credentials.
+   - Updates the running revision so the app picks up the latest agent IDs and configuration.
 
 ## Verification
 
 > After deployment completes, verify the system:
 
-1. **Check the Web App**:
-   - The Terraform output will provide the `application_url`.
-   - Visit `https://<your-app-name>.azurewebsites.net`.
-   - You should see the Zava chat interface with A2A protocol support.
+1. **Check the App**:
+   - The Terraform output will provide the `chat_application_url`.
+   - Visit `https://<your-app-name>.azurecontainerapps.io`.
+   - You should see the Zava chat interface with multi-agent routing enabled.
 
-      > E.g `Classic UI`
+      > E.g `Web App approach`
       
        <https://github.com/user-attachments/assets/a1139528-6b37-4ac2-a1cb-771788ff45a4>
 
 2. **Verify A2A Protocol Endpoints**:
-   - Check A2A Chat API: `https://<your-app-name>.azurewebsites.net/a2a/chat`
-   - Check A2A Server API: `https://<your-app-name>.azurewebsites.net/a2a/api/docs`
-   - Verify agent discovery: `https://<your-app-name>.azurewebsites.net/a2a/server/agents`
+   - Check A2A Chat API: `https://<your-app-name>.azurecontainerapps.io/a2a/chat`
+   - Check A2A Server API: `https://<your-app-name>.azurecontainerapps.io/a2a/api/docs`
+   - Verify agent discovery: `https://<your-app-name>.azurecontainerapps.io/a2a/server/agents`
 
 3. **Verify Enhanced Agent Architecture**:
    - Go to the [MSFT Foundry Portal](https://ai.azure.com).
@@ -198,19 +212,19 @@ graph TD
      - Core agents: Cora, Interior Design, Inventory, Loyalty, Cart Manager
      - Product Management Specialist with delegation capabilities
 
-      > E.g `Classic UI`
+      > E.g `Web App approach`
       
       <https://github.com/user-attachments/assets/3c562ccd-cff3-4a30-b9f8-44111fb71113>
 
-4. **Test Enhanced A2A Interactions**: `Adjust as needed, this is just a base`. For example:
-   - **General**: "Hi, who are you?" (Handled by Cora via A2A protocol)
-   - **Inventory**: "Do you have the classic leather sofa in stock?" (Routed through A2A to Inventory Agent)
-   - **Design**: "What colors of green paint do you have?" (A2A task delegation to Design Agent)
-   - **Product Recommendations**: "Recommend modern furniture for my living room" (Product Manager delegates to Marketing Agent)
-   - **Product Comparisons**: "Compare sectional sofas" (Product Manager delegates to Ranker Agent)
-   - **Product Details**: "What are the specifications of product SOFA-001?" (Product Manager uses Product Information Plugin)
-   - **Multi-Agent**: "Find a sofa, check reviews, and verify my loyalty points" (Complex A2A coordination across multiple specialized agents)
-
+4. **Test Multi-Agent Routing (UI)**: `Adjust as needed, this is just a base`. For example:
+    - **General**: “Hi, who are you?” (Routed to **Cora**)
+    - **Inventory**: “Do you have the classic leather sofa in stock?” (Routed to **Inventory Manager**)
+    - **Design**: “What colors of green paint do you have?” (Routed to **Interior Design Specialist**)
+    - **Product Recommendations**: “Recommend modern furniture for my living room” (Routed to **Product Management Specialist**; may consult catalog/search depending on its prompt/tools)
+    - **Product Comparisons**: “Compare sectional sofas” (Routed to **Product Management Specialist**; comparison is handled within that agent)
+    - **Product Details**: “What are the specifications of product SOFA-001?” (Routed to **Product Management Specialist**; details are handled within that agent)
+    - **Multi-Agent**: “Find a sofa, then verify my loyalty points, and add it to my cart” (Coordinated across **Product Management → Customer Loyalty → Cart Manager** via the app’s multi-step routing)
+      
 <!-- START BADGE -->
 <div align="center">
   <img src="https://img.shields.io/badge/Total%20views-1416-limegreen" alt="Total views">

TROUBLESHOOTING.md

@@ -308,6 +308,12 @@ $env:AZURE_LOG_LEVEL = "DEBUG"
 python pipelines/script.py
 ```
 
+**App (UI error details)**: Include traceback details in WebSocket error payloads.
+
+```powershell
+$env:A2A_DEBUG = "true"
+```
+
 **Terraform**:
 
 ```bash

terraform-infrastructure/README.md

@@ -5,12 +5,20 @@ Costa Rica
 [![GitHub](https://img.shields.io/badge/--181717?logo=github&logoColor=ffffff)](https://github.com/)
 [brown9804](https://github.com/brown9804)
 
-Last updated: 2026-01-29
+Last updated: 2026-02-02
 
 ----------
 
 > This approach focuses on `setting up the required infrastructure via Terraform`. It allows for source control of not only the solution code, connections, and setups `but also the infrastructure itself`.
 
+> When `Container App approach`:
+
+<img width="1911" height="989" alt="image" src="https://github.com/user-attachments/assets/6aec05ba-f9ea-4c95-86a8-c8e41d54331d" />
+
+<img width="1520" height="748" alt="image" src="https://github.com/user-attachments/assets/625710b8-c23f-4c0d-9ba2-32d3c8d807ed" />
+
+> When `Web App approach`:
+
 <div align="center">
   <img src="https://github.com/user-attachments/assets/77546e62-0cbe-4bb3-9581-1c2d8cfb4f70" alt="Centered Image" style="border: 2px solid #4CAF50; border-radius: 5px; padding: 5px;"/>
 </div>