Merge pull request #9 from MicrosoftCloudEssentials-LearningHub/A2A-protocol

A2A protocol

Author: brown9804

.gitignore

@@ -9,6 +9,7 @@ deploy.log
 __pycache__
 *.log 
 *agents_state.json
+.env.example
 
 # .tfstate files
 *.tfstate

README.md

@@ -1,11 +1,11 @@
-# Demo: Zava AI Shopping Assistant <br/> Multi-Agent Architecture - Overview
+# Demo: Zava AI Shopping Assistant <br/> Multi-Agent Architecture with A2A Protocol - Overview
 
 Costa Rica
 
 [![GitHub](https://img.shields.io/badge/--181717?logo=github&logoColor=ffffff)](https://github.com/)
 [brown9804](https://github.com/brown9804)
 
-Last updated: 2025-11-12
+Last updated: 2025-12-03
 
 ----------
 
@@ -16,36 +16,77 @@ Last updated: 2025-11-12
 
 > [!IMPORTANT]
 > The deployment process typically takes 15-20 minutes
+>
 > 1. Adjust [terraform.tfvars](./terraform-infrastructure/terraform.tfvars) values 
 > 2. Initialize terraform with `terraform init`. Click here to [understand more about the deployment process](./terraform-infrastructure/README.md)
 > 3. Run `terraform apply`, you can also leverage `terraform apply -auto-approve`. 
 
 ## Key Features
 
-- **Multi-Agent Architecture**: Few specialized AI agents working in concert:
-  - **Cora (Shopper)**: Front-facing assistant for general queries.
-  - **Inventory Manager**: Checks stock availability.
-  - **Customer Loyalty**: Manages rewards and discounts.
-  - **Cart Manager**: Handles shopping cart operations.
-- **Real Azure AI Agents**: Integrates with **Azure AI Foundry** to create and host persistent agents (not just local simulations).
-- **Zero-Touch Deployment**: A single [terraform apply](./terraform-infrastructure/README.md) command handles the entire lifecycle from infrastructure to application code.
-- **Intelligent Routing**: A dedicated Handoff Service classifies user intent and routes messages to the appropriate specialist agent.
-- **Data Pipeline Automation**: Automatically ingests product catalogs into Cosmos DB and builds Vector Search indexes.
+- **A2A Protocol Implementation**: Complete Agent-to-Agent communication framework with standardized messaging, event handling, and task coordination
+- **Multi-Agent Architecture**: Specialized AI agents working through A2A protocol:
+  - **Cora (Shopper)**: Front-facing assistant for general queries
+  - **Inventory Manager**: Checks stock availability via A2A requests
+  - **Customer Loyalty**: Manages rewards and discounts through agent coordination
+  - **Cart Manager**: Handles shopping cart operations with inter-agent communication
+- **Real Azure AI Agents**: Integrates with **Azure AI Foundry** to create and host persistent agents (not just local simulations)
+- **Zero-Touch Deployment**: A single [terraform apply](./terraform-infrastructure/README.md) command handles the entire lifecycle including A2A framework deployment
+- **A2A Intelligent Routing**: Enhanced Handoff Service that supports both traditional routing and A2A protocol agent discovery
+- **Data Pipeline Automation**: Automatically ingests product catalogs with A2A event notifications and coordination
+
+## About A2A Protocol
+
+`A2A (Agent-to-Agent) Protocol is a standardized communication framework that enables multiple AI agents to collaborate and coordinate tasks seamlessly.`
+
+> 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 Queue System**: Handles inter-agent communication (`src/a2a/server/events/`)
+- **Task Management**: Coordinates work between agents (`src/a2a/server/tasks.py`)
+- **Request Handlers**: Processes agent-to-agent requests (`src/a2a/server/request_handlers.py`)
+- **Coordinator Agent**: Orchestrates multi-agent workflows (`src/a2a/agent/coordinator.py`)
+- **API Endpoints**: RESTful and WebSocket APIs for 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
 
 ## Architecture
 
 ```mermaid
 graph TD
     User[User] <--> UI[Chat Interface]
     UI <--> App[FastAPI Application]
-    App <--> Handoff[Handoff Service]
-    Handoff -->|Classifies Intent| Router{Router}
+    App <--> A2A[A2A Protocol Server]
+    A2A <--> EventQueue[Event Queue]
+    A2A <--> Coordinator[A2A Coordinator]
+    
+    Coordinator -->|A2A Protocol| Router{Agent Router}
+    Router -->|Task Delegation| Cora[Cora Agent]
+    Router -->|Design Tasks| Design[Interior Design Agent]
+    Router -->|Inventory Events| Inventory[Inventory Agent]
+    Router -->|Loyalty Tasks| Loyalty[Loyalty Agent]
+    Router -->|Cart Events| Cart[Cart Agent]
     
-    Router -->|General| Cora[Cora Agent]
-    Router -->|Design| Design[Interior Design Agent]
-    Router -->|Stock| Inventory[Inventory Agent]
-    Router -->|Rewards| Loyalty[Loyalty Agent]
-    Router -->|Checkout| Cart[Cart Agent]
+    subgraph "A2A Communication"
+        EventQueue <--> Cora
+        EventQueue <--> Design
+        EventQueue <--> Inventory
+        EventQueue <--> Loyalty
+        EventQueue <--> Cart
+    end
     
     Inventory -->|Query| Search[Azure AI Search]
     Inventory -->|Lookup| Cosmos[Cosmos DB]
@@ -57,32 +98,40 @@ graph TD
 
 1. **Infrastructure Provisioning**:
    - Creates Resource Group, Cosmos DB, Azure AI Foundry, AI Search, Storage Account, Key Vault, and Container Registry (ACR).
-   - Deploys AI Models (`gpt-4o-mini`, `text-embedding-3-small`). 
+   - Deploys AI Models (`gpt-4o-mini`, `text-embedding-3-small`).
+   - Sets up A2A protocol infrastructure including event queues and monitoring.
 
        <img width="1859" height="900" alt="image" src="https://github.com/user-attachments/assets/cd24ab7f-5ddd-46de-b266-0d0a24c45803" />
 
-2. **Data Pipeline Execution**:
+2. **A2A Framework Deployment**:
+   - Initializes the Agent-to-Agent protocol server components.
+   - Sets up event queue system for inter-agent communication.
+   - Configures agent discovery and registration services.
+   - Deploys A2A monitoring and automation frameworks.
+
+3. **Data Pipeline Execution**:
    - Sets up a Python virtual environment.
-   - Ingests `product_catalog.csv` into Cosmos DB.
+   - Ingests `product_catalog.csv` into Cosmos DB with A2A event notifications.
 
         <https://github.com/user-attachments/assets/41bf0976-0ca8-47fe-a2fa-8750bcc6f848>
 
-   - Creates and populates an Azure AI Search index with vector embeddings.
+   - Creates and populates an Azure AI Search index with vector embeddings through A2A coordination.
 
         <https://github.com/user-attachments/assets/37c4a8cd-73e1-4392-8755-fb018481d8cb>
 
-3. **Agent Creation**:
+4. **Agent Creation & A2A Registration**:
    - Installs the `azure-ai-projects` SDK.
    - Connects to Azure AI Foundry.
-   - Provisions 5 real agents with specific instructions and tool definitions
-   - Saves the unique Agent IDs to the `.env` file.
+   - Provisions 5 real agents with A2A protocol integration and specific instructions.
+   - Registers agents with the A2A discovery service.
+   - Saves the unique Agent IDs and A2A endpoints to the `.env` file.
 
       <img width="1907" height="990" alt="image" src="https://github.com/user-attachments/assets/4234ead4-16e0-4bec-bbfd-3b8891d113b0" />
 
-4. **Application Deployment**:
-   - Builds the Docker container in the cloud (ACR Build).
-   - Configures the Azure Web App with the generated Agent IDs and credentials.
-   - Deploys the container and restarts the app.
+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.
 
 ## Verification
 
@@ -91,25 +140,31 @@ graph TD
 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.
+   - You should see the Zava chat interface with A2A protocol support.
 
        <https://github.com/user-attachments/assets/a1139528-6b37-4ac2-a1cb-771788ff45a4>
 
-2. **Verify Agents**:
+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`
+
+3. **Verify Agents**:
    - Go to the [Azure AI Foundry Portal](https://ai.azure.com).
    - Navigate to your project -> **Build** -> **Agents**.
-   - You should see all 5 agents listed.
+   - You should see all 5 agents listed with A2A protocol integration.
 
       <https://github.com/user-attachments/assets/3c562ccd-cff3-4a30-b9f8-44111fb71113>
 
-3. **Test Interactions**: For example:
-   - **General**: "Hi, who are you?" (Handled by Cora)
-   - **Inventory**: "Do you have the classic leather sofa in stock?" (Handled by Inventory Agent)
-   - **Design**: "What colors of green paint do you have?"
+4. **Test A2A Interactions**: 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)
+   - **Multi-Agent**: "Find a sofa and check my loyalty points" (A2A coordination between multiple agents)
 
 <!-- START BADGE -->
 <div align="center">
-  <img src="https://img.shields.io/badge/Total%20views-1611-limegreen" alt="Total views">
+  <img src="https://img.shields.io/badge/Total%20views-1624-limegreen" alt="Total views">
   <p>Refresh Date: 2025-12-03</p>
 </div>
 <!-- END BADGE -->

TROUBLESHOOTING.md

@@ -347,7 +347,7 @@ terraform apply
 
 <!-- START BADGE -->
 <div align="center">
-  <img src="https://img.shields.io/badge/Total%20views-1611-limegreen" alt="Total views">
+  <img src="https://img.shields.io/badge/Total%20views-1624-limegreen" alt="Total views">
   <p>Refresh Date: 2025-12-03</p>
 </div>
 <!-- END BADGE -->

run_a2a_server.py

@@ -0,0 +1,76 @@
+"""
+A2A Protocol Test Runner
+
+This script provides an easy way to test and run the A2A (Agent-to-Agent) protocol
+server for development and validation purposes.
+
+Key frameworks and technologies used:
+- Uvicorn: ASGI web server implementation with support for HTTP/1.1 and WebSockets,
+  designed for high-performance async Python web applications
+- AsyncIO: Python's asynchronous I/O framework enabling concurrent execution
+  without threading, perfect for handling multiple agent communications
+- Python Logging: Built-in logging system for monitoring server startup and operations
+- Pathlib: Modern object-oriented filesystem path handling library
+"""
+import uvicorn
+import asyncio
+import logging
+from pathlib import Path
+
+from src.a2a.config import load_config, A2AMode
+from src.a2a.main import create_app
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+async def test_a2a_protocol():
+    """Test the A2A protocol implementation"""
+    try:
+        # Load configuration
+        config = load_config()
+        logger.info(f"Loaded configuration with mode: {config.a2a.mode}")
+        
+        # Create the application
+        app = create_app()
+        logger.info("✅ Application created successfully")
+        
+        # Test agent initialization
+        if hasattr(app.state, 'coordinator'):
+            coordinator = app.state.coordinator
+            agents = coordinator.get_available_agents()
+            logger.info(f"✅ Available agents: {list(agents.keys())}")
+            
+            # Test each agent
+            for agent_id, agent_info in agents.items():
+                logger.info(f"  - {agent_id}: {agent_info.get('description', 'No description')}")
+        
+        # Start server for testing
+        config_obj = uvicorn.Config(
+            app=app,
+            host="localhost",
+            port=8000,
+            log_level="info",
+            reload=False
+        )
+        server = uvicorn.Server(config_obj)
+        
+        logger.info("🚀 Starting A2A protocol server on http://localhost:8000")
+        logger.info("   - A2A Chat: http://localhost:8000/a2a/chat")
+        logger.info("   - A2A API: http://localhost:8000/a2a/api/docs")
+        logger.info("   - Legacy Chat: http://localhost:8000/chat")
+        logger.info("   - Health: http://localhost:8000/health")
+        
+        await server.serve()
+        
+    except Exception as e:
+        logger.error(f"❌ Error testing A2A protocol: {e}")
+        import traceback
+        logger.error(traceback.format_exc())
+        raise
+
+if __name__ == "__main__":
+    asyncio.run(test_a2a_protocol())