a2a-hybrid-app

# A2A Protocol Hybrid Server/Client [](https://nextjs.org/) [](https://www.typescriptlang.org/) [](https://reactjs.org/) [](https://azure.microsoft.com/en-us/products/ai-services/openai-service) [](https://tailwindcss.com/) [](LICENSE) A comprehensive implementation of the [A2A Protocol v0.3.0](https://a2a-protocol.org/dev/specification/) specification, featuring intelligent agent-to-agent communication powered by Azure OpenAI GPT-4. This hybrid solution provides both server and client capabilities for building autonomous AI agent networks. ## 🎯 What This Solution Does ### For Everyone (High School Level) Imagine you have different AI assistants that need to talk to each other and work together on tasks. This project creates a standardized way for AI agents to communicate, similar to how people use phones or email to coordinate work. **Key Features:** - **AI Agent Communication**: Different AI programs can send messages and share information with each other - **Smart Task Management**: AI agents can assign work to each other and track progress automatically - **Real-time Updates**: See live progress as AI agents work on tasks and collaborate - **Web Interface**: Easy-to-use website where you can interact with AI agents and see their conversations - **Intelligent Responses**: Powered by GPT-4, so the AI agents give helpful, context-aware answers **Real-world Example**: You could have one AI agent that's good at research, another that's good at writing, and a third that's good at data analysis. They can work together on a project by automatically sharing information and coordinating their efforts. ### For Technical Experts (PhD Level) This implementation provides a production-ready A2A (Agent-to-Agent) Protocol v0.3.0 server and client with enterprise-grade features and Azure OpenAI integration. **Architecture & Implementation:** - **Protocol Compliance**: Full implementation of A2A specification including agent discovery, message routing, task lifecycle management, and streaming capabilities - **Transport Layer**: JSON-RPC 2.0 over HTTP with Server-Sent Events for real-time communication - **AI Integration**: Azure OpenAI GPT-4 service with conversation context management, intent analysis, and artifact generation - **Type Safety**: Comprehensive TypeScript type system covering all protocol objects and API interfaces - **Microservices Architecture**: Modular design with separation of concerns between agent cards, task management, streaming, and AI services - **Security**: Environment-based configuration management with proper secret handling and authentication hooks **Technical Capabilities:** - Agent card discovery and capability negotiation - Asynchronous task execution with state management - Real-time streaming updates via SSE - Conversation context preservation across interactions - Extensible plugin architecture for custom task processors - Production-ready error handling and logging ## 🚀 Technology Stack | Component | Version | Purpose | |-----------|---------|---------| | **Next.js** | 15.5.4 | Full-stack React framework with App Router | | **TypeScript** | 5.x | Type-safe development and protocol compliance | | **React** | 19.1.0 | Modern UI components and state management | | **Azure OpenAI** | GPT-4.1 | Advanced language model for intelligent responses | | **Tailwind CSS** | 4.x | Utility-first CSS framework for responsive design | | **OpenAI SDK** | 6.2.0 | Azure OpenAI service integration | | **UUID** | 13.0.0 | Unique identifier generation for protocol compliance | | **ESLint** | 9.x | Code quality and consistency enforcement | ## � Visual Walkthrough: A2A Protocol in Action Experience the complete agent interaction workflow through this step-by-step visual journey: ### 1. 🔍 Agent Discovery Hub *Your starting point for exploring the AI agent ecosystem* <div align="center"> <a href="./public/assets/discover_agent.png" target="_blank"> <img src="./public/assets/discover_agent.png" alt="Agent Discovery Homepage" width="600" style="border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15); margin: 10px 0;"/> </a> <p><em>The homepage provides an intuitive interface to discover available AI agents and understand their capabilities.</em></p> </div> --- ### 2. 🤖 Available Agents Directory *Browse and select from intelligent AI agents ready to assist* <div align="center"> <a href="./public/assets/discovered_agents.png" target="_blank"> <img src="./public/assets/discovered_agents.png" alt="Discovered Agents List" width="600" style="border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15); margin: 10px 0;"/> </a> <p><em>View detailed agent cards showing capabilities, skills, and specializations powered by Azure OpenAI GPT-4.</em></p> </div> --- ### 3. 💬 Interactive Agent Communication *Engage in intelligent conversations with AI-powered responses* <div align="center"> <a href="./public/assets/agent_chat.png" target="_blank"> <img src="./public/assets/agent_chat.png" alt="Agent Chat Interface" width="600" style="border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15); margin: 10px 0;"/> </a> <p><em>Real-time chat interface with context-aware AI responses, conversation history, and seamless message flow.</em></p> </div> --- ### 4. 📋 Task Management & Progress Tracking *Monitor and manage AI agent tasks with real-time updates* <div align="center"> <a href="./public/assets/agent_tasks.png" target="_blank"> <img src="./public/assets/agent_tasks.png" alt="Agent Task Management" width="600" style="border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15); margin: 10px 0;"/> </a> <p><em>Comprehensive task tracking with status updates, progress indicators, and artifact management.</em></p> </div> --- ### 🚀 The Complete User Journey **Step 1: Discovery** → Start at the homepage to understand available AI agents and their unique capabilities **Step 2: Selection** → Browse the agent directory to find specialists that match your needs (research, analysis, writing, etc.) **Step 3: Interaction** → Engage in natural conversations with GPT-4 powered agents that understand context and provide intelligent responses **Step 4: Task Management** → Assign complex tasks to agents and monitor progress in real-time with automatic status updates This workflow demonstrates how the A2A Protocol enables seamless agent-to-agent communication while providing an intuitive human interface for orchestrating AI collaboration. ## �🔒 Security & Environment Setup **CRITICAL**: Before working with this project, ensure you properly configure environment variables: 1. Copy `.env.example` to `.env.local`: ```bash cp .env.example .env.local ``` 2. Add your Azure OpenAI credentials to `.env.local`: ```bash AZURE_OPENAI_API_KEY=your_api_key_here AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/ AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4 AZURE_OPENAI_API_VERSION=2024-06-01 ``` 3. **⚠️ NEVER commit `.env.local` or any files containing secrets!** ### Security Checklist - ✅ `.env.local` is in `.gitignore` - ✅ No API keys are hardcoded in source files - ✅ All sensitive files are properly ignored - ⚠️ Always double-check before committing: `git status --ignored` ## 🛠️ Getting Started ### Prerequisites - Node.js 18+ - npm, yarn, pnpm, or bun - Azure OpenAI service account and API key ### Installation & Development 1. **Clone the repository:** ```bash git clone https://github.com/ushakrishnan/a2a-hybrid-app.git cd a2a-hybrid-app ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Configure environment variables** (see Security section above) 4. **Start the development server:** ```bash npm run dev # or yarn dev # or pnpm dev # or bun dev ``` 5. **Open your browser:** Navigate to [http://localhost:3000](http://localhost:3000) to access the A2A interface ### Build for Production ```bash npm run build npm start ``` ## 📁 Project Structure ``` src/ ├── app/ # Next.js App Router │ ├── api/a2a/v1/ # A2A Protocol API endpoints │ ├── .well-known/ # Agent discovery endpoint │ └── page.tsx # Main UI interface ├── lib/a2a/ # A2A Protocol implementation │ ├── types/ # TypeScript definitions │ ├── server/ # Server-side components │ ├── client/ # Client-side components │ ├── services/ # Azure OpenAI integration │ └── hooks/ # React hooks for A2A operations ``` ## 🔌 API Endpoints | Endpoint | Method | Purpose | |----------|--------|---------| | `/.well-known/agent-card.json` | GET | Agent discovery and capabilities | | `/api/a2a/v1` | POST | JSON-RPC 2.0 protocol endpoint | | `/api/a2a/v1/stream` | GET | Server-Sent Events for real-time updates | ## 🎯 A2A Protocol Methods - **`message/send`** - Send messages between agents with AI-powered responses - **`tasks/get`** - Retrieve task status and results - **`tasks/cancel`** - Cancel running tasks - **`message/stream`** - Real-time streaming communication ## 🤝 Contributing We welcome contributions to improve the A2A Protocol implementation! Here's how to get started: 1. **Fork the repository** on [GitHub](https://github.com/ushakrishnan/a2a-hybrid-app/fork) 2. **Clone your fork:** `git clone https://github.com/YOUR_USERNAME/a2a-hybrid-app.git` 3. **Create a feature branch:** `git checkout -b feature-name` 4. **Make your changes** and add tests if applicable 5. **Commit your changes:** `git commit -m 'Add feature: description'` 6. **Push to the branch:** `git push origin feature-name` 7. **Submit a pull request** on [GitHub](https://github.com/ushakrishnan/a2a-hybrid-app/pulls) ### 🐛 Issues & Bug Reports Found a bug? Have a feature request? Please [open an issue](https://github.com/ushakrishnan/a2a-hybrid-app/issues) on GitHub. ## 📚 Learn More ### A2A Protocol Resources - [A2A Protocol Specification](https://a2a-protocol.org/dev/specification/) - Official protocol documentation - [A2A Protocol Tutorials](https://a2a-protocol.org/dev/tutorials/) - Implementation tutorials and samples - [A2A Common Workflows & Examples](https://a2a-protocol.org/dev/specification/#9-common-workflows-examples) - Protocol usage examples ### Technology Documentation - [Next.js Documentation](https://nextjs.org/docs) - Learn about Next.js features and API - [Azure OpenAI Service](https://docs.microsoft.com/en-us/azure/ai-services/openai/) - Azure OpenAI documentation - [TypeScript Handbook](https://www.typescriptlang.org/docs/) - TypeScript language reference ## 🚀 Deployment ### Vercel (Recommended) Deploy easily on [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme): 1. **Connect GitHub:** Import the [repository](https://github.com/ushakrishnan/a2a-hybrid-app) in your Vercel dashboard 2. **Add environment variables:** Configure Azure OpenAI credentials in Vercel settings 3. **Deploy:** Automatic deployment on every push to main branch ### Other Platforms This Next.js application can be deployed on any platform supporting Node.js: - Netlify - AWS Amplify - Google Cloud Platform - Azure Static Web Apps ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.