diff --git a/README.md b/README.md index 83a6270..cbbdf46 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 ---------- @@ -21,8 +21,10 @@ Last updated: 2026-01-29 > E.g -image - +
+ image +
+ > [!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 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` image @@ -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://.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` + > E.g `Web App approach` 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). @@ -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` -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 diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index 80d611f..4f09a20 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 diff --git a/terraform-infrastructure/README.md b/terraform-infrastructure/README.md index 9b19cf5..91d6cc4 100644 --- a/terraform-infrastructure/README.md +++ b/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`: + +image + +image + +> When `Web App approach`: +
Centered Image