{"id":39825415,"url":"https://github.com/markmdev/a2a-demo-rebuilt","last_synced_at":"2026-01-18T13:04:04.749Z","repository":{"id":319025684,"uuid":"1076545450","full_name":"markmdev/a2a-demo-rebuilt","owner":"markmdev","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-16T17:34:23.000Z","size":93941,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-17T06:59:46.233Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markmdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-15T02:38:42.000Z","updated_at":"2025-10-16T17:34:28.000Z","dependencies_parsed_at":"2025-10-17T20:26:05.673Z","dependency_job_id":null,"html_url":"https://github.com/markmdev/a2a-demo-rebuilt","commit_stats":null,"previous_names":["markmdev/a2a-demo-rebuilt"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/markmdev/a2a-demo-rebuilt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fa2a-demo-rebuilt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fa2a-demo-rebuilt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fa2a-demo-rebuilt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fa2a-demo-rebuilt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markmdev","download_url":"https://codeload.github.com/markmdev/a2a-demo-rebuilt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fa2a-demo-rebuilt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28536688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T10:13:46.436Z","status":"ssl_error","status_checked_at":"2026-01-18T10:13:11.045Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-18T13:04:04.638Z","updated_at":"2026-01-18T13:04:04.737Z","avatar_url":"https://github.com/markmdev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A2A Demo - Agent-to-Agent Communication\n\nA demonstration of the **A2A (Agent-to-Agent) Protocol** using **CopilotKit (AG-UI)**, **Google ADK**, and **Gemini**. This application showcases how AI agents can communicate seamlessly through standardized protocols.\n\n![Demo gif](A2A_Demo.gif)\n\n## What This Demonstrates\n\nThis demo shows a multi-agent system where:\n- An orchestrator agent (AG-UI Protocol) coordinates with specialized agents\n- Specialized agents (A2A Protocol) provide domain-specific capabilities\n- The A2A Middleware bridges the two protocols seamlessly\n- Real-time event tracking visualizes agent communication\n\n### Features\n\n- **Multi-Agent Architecture**: Orchestrator + 3 specialized agents working together\n- **Protocol Bridging**: Seamless communication between AG-UI and A2A protocols\n- **Real-Time Visualization**: Watch agents communicate in real-time\n- **Event Tracking**: Monitor all A2A calls and responses\n- **Modern UI**: Glass-morphism design with smooth animations\n- **Dynamic Agent Registration**: Add/remove agents at runtime\n\n## Prerequisites\n\n- **Node.js** 18+ (for the Next.js frontend)\n- **Python** 3.10+ (for ADK agents)\n- **[Google API Key](https://aistudio.google.com/app/apikey)** (for Gemini models)\n- **[CopilotKit License Key](https://cloud.copilotkit.ai/)** (free for AG-UI integration)\n\n## Quick Start\n\n### 1. Clone and Install Dependencies\n\n```bash\n# Install frontend dependencies\nnpm install\n\n# Install Python dependencies\ncd agents\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\npip install -r requirements.txt\ncd ..\n```\n\n### 2. Configure Environment\n\n```bash\n# Copy the example environment files\ncp .env.example .env\ncp agents/.env.example agents/.env\n\n# Edit both files and add your API keys\n# .env.local - for Next.js frontend\n# agents/.env - for Python agents\n```\n\n**Required API Keys:**\n\n1. **Google API Key** (for Gemini models)\n   - Get yours at: https://aistudio.google.com/app/apikey\n   - Add to `agents/.env` only\n\n2. **CopilotKit License Key** (for AG-UI integration)\n   - Get your free key at: https://cloud.copilotkit.ai/\n   - Add to `.env` only\n\n### 3. Start the Application\n\n```bash\n# Start all agents and UI (single command)\nnpm run dev\n```\n\nThis starts:\n- **UI** on `http://localhost:3000`\n- **Orchestrator** on `http://localhost:9000` (AG-UI Protocol)\n- **Weather Agent** on `http://localhost:9005` (A2A Protocol)\n- **Activities Agent** on `http://localhost:9006` (A2A Protocol)\n- **Weekend Planner** on `http://localhost:9007` (A2A Protocol)\n\n### 4. Register Agents\n\n1. Open `http://localhost:3000` in your browser\n2. Navigate to the \"Agents\" page\n3. Click \"Add Agent\" and quick-add the three specialized agents\n4. Return to \"Conversations\" and start chatting!\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                  Next.js Frontend (React 19)                     │\n│                                                                   │\n│  ┌────────────────────────────────────────────────────────────┐ │\n│  │ CopilotChat Component                                      │ │\n│  │ - User sends message                                       │ │\n│  │ - Displays assistant responses                             │ │\n│  │ - Visualizes A2A calls (green) and responses (blue)       │ │\n│  └────────────────────────────────────────────────────────────┘ │\n└────────────────────────┬─────────────────────────────────────────┘\n                         │\n                         │ CopilotKit (AG-UI Protocol)\n                         │\n┌────────────────────────▼─────────────────────────────────────────┐\n│     Next.js API Route: /api/copilotkit                           │\n│                                                                   │\n│  ┌────────────────────────────────────────────────────────────┐ │\n│  │ A2AMiddlewareAgent (TypeScript)                            │ │\n│  │ - Wraps orchestrator agent                                 │ │\n│  │ - Injects \"send_message_to_a2a_agent\" tool                │ │\n│  │ - Routes A2A calls to specialized agents                  │ │\n│  │ - Returns results back to orchestrator                     │ │\n│  └────────────────────────────────────────────────────────────┘ │\n└────────────────────────┬─────────────────────────────────────────┘\n                         │\n                         │ HTTP POST (AG-UI Protocol)\n                         │\n┌────────────────────────▼─────────────────────────────────────────┐\n│   Orchestrator Agent (Python ADK, Port 9000)                     │\n│   Model: Gemini 2.5 Flash                                        │\n│                                                                   │\n│  - Receives user messages via AG-UI Protocol                     │\n│  - Determines which specialized agents to call                   │\n│  - Uses \"send_message_to_a2a_agent\" tool                        │\n│  - Synthesizes responses for the user                            │\n└────────────┬────────────────┬────────────────┬───────────────────┘\n             │                │                │\n             │ A2A Protocol   │ A2A Protocol   │ A2A Protocol\n             │ (JSON/HTTP)    │ (JSON/HTTP)    │ (JSON/HTTP)\n             │                │                │\n┌────────────▼─────────┐  ┌───▼──────────────┐  ┌─▼──────────────────┐\n│  Weather Agent       │  │  Activities      │  │  Weekend Planner   │\n│  (Port 9005)         │  │  Agent           │  │  (Port 9007)       │\n│                      │  │  (Port 9006)     │  │                    │\n│  - Gemini 2.5 Flash  │  │                  │  │  - Gemini 2.5      │\n│  - Forecasts for     │  │  - Gemini 2.5    │  │    Flash           │\n│    destinations      │  │    Flash         │  │  - Synthesizes     │\n│  - Travel advice     │  │  - Suggests      │  │    weather +       │\n│  - Best days for     │  │    activities    │  │    activities      │\n│    activities        │  │    based on      │  │    into day plans  │\n│                      │  │    weather       │  │                    │\n└──────────────────────┘  └──────────────────┘  └────────────────────┘\n```\n\n## How It Works\n\n### 1. Protocols\n\n**AG-UI Protocol** (Frontend ↔ Orchestrator)\n- Used by CopilotKit to communicate with the orchestrator\n- Supports streaming responses, tool calls, and conversation state\n- Orchestrator speaks AG-UI natively via ADK's FastAPI integration\n\n**A2A Protocol** (Orchestrator ↔ Specialized Agents)\n- Standardized JSON-based protocol for agent-to-agent communication\n- Each specialized agent exposes an agent card at `/.well-known/agent-card.json`\n- Messages are sent as structured JSON with roles and content\n\n### 2. A2A Middleware\n\nThe `A2AMiddlewareAgent` is the key innovation:\n\n1. **Wraps** the orchestrator agent\n2. **Fetches** agent cards from all registered A2A agents\n3. **Injects** the `send_message_to_a2a_agent` tool into the orchestrator's toolkit\n4. **Intercepts** tool calls destined for A2A agents\n5. **Routes** messages via A2A Protocol\n6. **Returns** results back to the orchestrator\n\nThis creates a seamless bridge where the orchestrator can call A2A agents as if they were native tools.\n\n### 3. Message Flow\n\n```\nUser: \"Plan my weekend in San Francisco\"\n  ↓\nOrchestrator receives message via AG-UI\n  ↓\nOrchestrator decides to call Weather Agent\n  ↓\nA2A Middleware intercepts tool call\n  ↓\nA2A Middleware routes to Weather Agent (A2A Protocol)\n  ↓\nWeather Agent returns forecast\n  ↓\nOrchestrator receives result\n  ↓\nOrchestrator calls Activities Agent\n  ↓\n... (similar flow)\n  ↓\nOrchestrator synthesizes response\n  ↓\nUser sees complete weekend plan\n```\n\n## Available Scripts\n\n- `npm run dev` - Start all services (UI + all agents)\n- `npm run dev:ui` - Start only the Next.js UI\n- `npm run dev:orchestrator` - Start only the orchestrator\n- `npm run dev:weather` - Start only the weather agent\n- `npm run dev:activities` - Start only the activities agent\n- `npm run dev:weekend` - Start only the weekend planner\n- `npm run build` - Build for production\n- `npm run start` - Start production server\n- `npm run lint` - Run ESLint\n\n## Key Technologies\n\n### Frontend\n- **Next.js 15** with App Router\n- **React 19** with hooks\n- **TypeScript** (strict mode)\n- **TailwindCSS** for styling\n- **CopilotKit** for AG-UI integration\n\n### Backend\n- **Google ADK** (Agent Development Kit)\n- **Gemini 2.5 Flash** models\n- **FastAPI** for serving agents\n- **A2A Protocol** for agent communication\n\n## Troubleshooting\n\n### Agents not connecting?\n- Verify all agents are running (`npm run dev` should start all)\n- Check that ports 9000, 9005, 9006, 9007 are available\n- Ensure GOOGLE_API_KEY is set in both `.env.local` AND `agents/.env`\n- Check Python virtual environment is activated (`source agents/.venv/bin/activate`)\n\n### UI not loading?\n- Make sure you ran `npm install`\n- Check that port 3000 is available\n- Verify Next.js is running without errors\n\n### Python errors?\n- Activate the virtual environment: `source agents/.venv/bin/activate`\n- Reinstall dependencies: `pip install -r agents/requirements.txt`\n- Verify Python version is 3.10+\n\n### Agents not appearing in the UI?\n1. Make sure all agent servers are running\n2. Go to the \"Agents\" page\n3. Click \"Add Agent\" and quick-add each agent\n4. Check agent status in the UI\n\n## Learn More\n\n- **[AG-UI Protocol](https://docs.ag-ui.com)** - Agent-UI communication standard\n- **[A2A Protocol](https://github.com/agent-matrix/a2a)** - Agent-to-agent communication\n- **[Google ADK](https://google.github.io/adk-docs/)** - Agent Development Kit\n- **[CopilotKit](https://docs.copilotkit.ai)** - React framework for AI copilots\n- **[Next.js](https://nextjs.org/docs)** - React framework\n- **[Gemini API](https://ai.google.dev/)** - Google's AI models\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmdev%2Fa2a-demo-rebuilt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkmdev%2Fa2a-demo-rebuilt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmdev%2Fa2a-demo-rebuilt/lists"}