From 181e2d2434f27ec5df68944a789451a4bc1d2826 Mon Sep 17 00:00:00 2001 From: Timna Brown <24630902+brown9804@users.noreply.github.com> Date: Mon, 2 Feb 2026 10:50:11 -0600 Subject: [PATCH 1/9] Update troubleshooting details and badge information --- TROUBLESHOOTING.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index 80d611f..ad87a55 100644 --- a/TROUBLESHOOTING.md +++ b/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 @@ -347,7 +353,7 @@ terraform apply
- Total views -

Refresh Date: 2026-02-02

+ Total views +

Refresh Date: 2026-01-30

From cec9cfa8215f8cc748d8e53e5a9768c9bd89943a Mon Sep 17 00:00:00 2001 From: Timna Brown <24630902+brown9804@users.noreply.github.com> Date: Mon, 2 Feb 2026 10:51:29 -0600 Subject: [PATCH 2/9] Update README with latest information and enhancements Updated last modified date and badge information in README.md. Enhanced agent creation details and deployment instructions. --- README.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 83a6270..d2fe48c 100644 --- a/README.md +++ b/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 ---------- @@ -150,15 +150,15 @@ graph TD 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` @@ -170,26 +170,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://.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://.azurecontainerapps.io`. + - You should see the Zava chat interface with multi-agent routing enabled. > E.g `Classic UI` 2. **Verify A2A Protocol Endpoints**: - - Check A2A Chat API: `https://.azurewebsites.net/a2a/chat` - - Check A2A Server API: `https://.azurewebsites.net/a2a/api/docs` - - Verify agent discovery: `https://.azurewebsites.net/a2a/server/agents` + - Check A2A Chat API: `https://.azurecontainerapps.io/a2a/chat` + - Check A2A Server API: `https://.azurecontainerapps.io/a2a/api/docs` + - Verify agent discovery: `https://.azurecontainerapps.io/a2a/server/agents` 3. **Verify Enhanced Agent Architecture**: - Go to the [MSFT Foundry Portal](https://ai.azure.com). @@ -213,7 +213,7 @@ graph TD
- Total views -

Refresh Date: 2026-02-02

+ Total views +

Refresh Date: 2026-01-30

From c893417e4c09e4f862985c5afe233e3cde34bd17 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Feb 2026 16:51:59 +0000 Subject: [PATCH 3/9] Update visitor count --- README.md | 4 ++-- TROUBLESHOOTING.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d2fe48c..7ff3d3b 100644 --- a/README.md +++ b/README.md @@ -213,7 +213,7 @@ graph TD
- Total views -

Refresh Date: 2026-01-30

+ Total views +

Refresh Date: 2026-02-02

diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index ad87a55..4f09a20 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -353,7 +353,7 @@ terraform apply
- Total views -

Refresh Date: 2026-01-30

+ Total views +

Refresh Date: 2026-02-02

From 5cd855752a648d51aebe7b965c4bb95d3cda7286 Mon Sep 17 00:00:00 2001 From: Timna Brown <24630902+brown9804@users.noreply.github.com> Date: Mon, 2 Feb 2026 10:59:38 -0600 Subject: [PATCH 4/9] Revise multi-agent routing examples in README Updated the section on multi-agent routing to clarify roles and improve examples. --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 7ff3d3b..7894d4f 100644 --- a/README.md +++ b/README.md @@ -202,15 +202,15 @@ graph TD -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) +
Total views From d33914fa9e180154f466587da685cbd75bae2c56 Mon Sep 17 00:00:00 2001 From: Timna Brown <24630902+brown9804@users.noreply.github.com> Date: Mon, 2 Feb 2026 12:12:08 -0600 Subject: [PATCH 5/9] Enhance README with Container and Web App visuals Added images and descriptions for Container App and Web App approaches. --- terraform-infrastructure/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/terraform-infrastructure/README.md b/terraform-infrastructure/README.md index 9b19cf5..9b831bc 100644 --- a/terraform-infrastructure/README.md +++ b/terraform-infrastructure/README.md @@ -11,6 +11,14 @@ Last updated: 2026-01-29 > 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`: + +image + +image + +> When `Web App approach`: +
Centered Image
From b6d1e2a3ca55ecc6c241e3ba50b877566668e785 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Feb 2026 18:12:20 +0000 Subject: [PATCH 6/9] Update last modified date in Markdown files --- terraform-infrastructure/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/terraform-infrastructure/README.md b/terraform-infrastructure/README.md index 9b831bc..91d6cc4 100644 --- a/terraform-infrastructure/README.md +++ b/terraform-infrastructure/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 ---------- From c81da93e534f6effa6adb26810178b3e4cfbd376 Mon Sep 17 00:00:00 2001 From: Timna Brown <24630902+brown9804@users.noreply.github.com> Date: Mon, 2 Feb 2026 12:49:22 -0600 Subject: [PATCH 7/9] Revise README for A2A protocol details and formatting Updated README to enhance clarity on A2A protocol features and components, including improved formatting and additional details on agent roles. --- README.md | 92 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 52 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 7894d4f..940cf31 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,10 @@ Last updated: 2026-02-02 > E.g -image - +
+ image +
+ > [!IMPORTANT] > The deployment process typically takes 15-20 minutes > @@ -32,51 +34,61 @@ Last updated: 2026-02-02 ## 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 - -> A2A Components in This Project: - -- **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/`) - -> A2A vs Traditional Multi-Agent Systems: - -- **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 +- **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 + +> How this repo implements multi-agent collaboration (default deployment) + +- **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 components included in this repo (optional server) + +- **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 From 34021f9d36b16db72a2d762e175a38ea2d97774f Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 2 Feb 2026 18:49:36 +0000 Subject: [PATCH 8/9] Fix Markdown syntax issues --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 940cf31..c748b23 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,7 @@ Last updated: 2026-02-02 `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. @@ -87,6 +88,7 @@ This repo contains **two multi-agent implementations**: > [!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) From 51895d39856412ee1581f9584e5ac47c21190a01 Mon Sep 17 00:00:00 2001 From: Timna Brown <24630902+brown9804@users.noreply.github.com> Date: Mon, 2 Feb 2026 12:51:50 -0600 Subject: [PATCH 9/9] Update examples from 'Classic UI' to 'Web App approach' --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c748b23..cbbdf46 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,7 @@ graph TD - Configures delegation relationships between Product Manager and specialized agents. - 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` image @@ -196,7 +196,7 @@ graph TD - Visit `https://.azurecontainerapps.io`. - You should see the Zava chat interface with multi-agent routing enabled. - > E.g `Classic UI` + > E.g `Web App approach` @@ -212,7 +212,7 @@ 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`