A2A-MCP Server Framework

📘 中文Readme 由于a2a协议升级，以前的task变成了message，conversation的id从metadata也改成了contextId，所以进行了升级。 推荐最新A2A结合ADK和MCP实现更复杂任务的方法: https://github.com/johnson7788/MultiAgentPPT/tree/main/backend

🌟 Overview

A2A-MCP Serer Framework is a robust, production-ready solution that leverages Google’s Agent-to-Agent (A2A) protocol and integrates seamlessly with the Model Context Protocol (MCP). This project is designed for building interoperable single and multi-agent systems with full compatibility with Google’s official A2A code. It offers a clear structure, rich examples, and a full-stack, ready-to-use implementation for developers.

Key highlights:

• 100% A2A Compatibility: Built using Google’s official A2A code for maximum interoperability.
• MCP Integration: First-class support for MCP, enabling agents to access external tools and data sources.
• Clear Structure: Well-organized project with comprehensive examples for single and multi-agent setups.
• Full-Stack Solution: Includes both backend (Python) and frontend (Node.js) components for immediate deployment.
• Rich Examples: Demonstrates practical use cases for both single-agent and multi-agent collaboration.
• Multi-LLM Model Support: Seamlessly integrates and supports various leading language models, including OpenAI, DeepSeek, Anthropic, Ollama, VLLM, Bytedance offering users flexibility and choice.

✨ Why Choose A2A-MCP Server Framework?

• Complete A2A Implementation: Adheres strictly to the official A2A specification.
• Flexible Agent Systems: Supports both single-agent and multi-agent workflows.
• MCP Tooling: Easily integrate external tools via MCP for enhanced agent capabilities.
• Production-Ready: Robust error handling and clear documentation for enterprise use.
• Developer-Friendly: Rich examples, intuitive setup, and minimal dependencies.

📦 Installation

Prerequisites

• Python 3.10+
• Node.js 16+
• pip for Python dependencies
• npm for frontend dependencies

Backend Setup

1. Clone the repository:

git clone https://github.com/johnson7788/A2AServer.git

2. Install backend dependencies:

cd backend/A2AServer
pip install .

🚀 Quick Start

Single-Agent Example

1. Start the A2A Agent

• Agent RAG:

cd backend/AgentRAG
python main.py --port 10005

2. Start the Frontend

cd frontend/single_agent
npm install
npm run dev

Open the frontend in your browser, add the agent, and start interacting through the Q&A interface.

3. UI Example

More UI:

Single Agent Call Flow

graph TD
    A[Frontend] --> B[Agent1]
    B --> E[MCP Tool1]
    B --> F[MCP Tool2]

Reasoning Flow for a Single Agent

Question → Reasoning → MCP Tool 1 → Reasoning → MCP Tool 2 → Reasoning → Answer

graph TD
    A[前端] --> B[Agent1]
    B --> C[Reasoning Text]
    C --> D[MCP Tool1]
    D --> F[Reasoning Text]
    F --> E[MCP Tool2]
    E --> G[Reasoning Text]
    G --> H[Answer]

Multi-Agent Setup

This section demonstrates how to set up a multi-agent system with collaboration between A2A agents.

1. Start Agent 1

• Agent RAG:

cd backend/AgentRAG
python main.py --port 10005

2. Start Agent 2

cd backend/DeepSearch
python main.py --port 10004

3. Start Host Agent

The host agent coordinates multiple A2A agents, manages their states, and decides which agent to use.

cd frontend/hostAgentAPI
pip install -r requirements.txt
python api.py

4. Start Frontend

cd frontend/multiagent_front
npm install
npm run dev

• Open the frontend in your browser, add agents, and start interacting via the Q&A interface.

5. UI Example

Multi-Agent Call Flow

graph TD
    A[Frontend] --> B[HostAgent]
    B --> C[Agent1]
    B --> D[Agent2]
    D --> E[MCP Tool1]
    D --> F[MCP Tool2]
    C --> M[MCP Tool3]

📂 Project Structure

A2AServer
├── backend
│   ├── A2AServer           # A2A server dependencies
│   ├── AgentRAG            # RAG-based A2A agent
│   ├── DeepSearch          # DeepSearch A2A agent example
│   ├── client.py           # A2A client for testing
│   └── hostAgentAPI        # Host agent for multi-agent coordination
├── multiagent_front        # Frontend for multi-agent collaboration
├── single_agent            # Frontend for single-agent interaction
└── README.md               # Project documentation

🛠️ Developing Your Own A2A Server

To create a custom A2A server, follow these steps:

1. Copy the DeepSearch Example:

cp -r backend/DeepSearch backend/MyCustomAgent

2. Directory Structure:

MyCustomAgent
├── .env                # Environment file for model keys
├── main.py             # A2A server startup script
├── mcp_config.json     # MCP server configuration
├── mcpserver           # MCP server code (optional)
│   └── my_tool.py      # Custom MCP tool
└── prompt.txt          # Agent prompt file

3. Configure MCP Tools:

• Ensure tool names in mcp_config.json use camelCase (e.g., MyCustomTool) instead of underscores (e.g., My_Custom_Tool) to avoid lookup issues.
• Example mcp_config.json:

{
  "tools": [
    {
      "name": "MyCustomTool",
      "description": "A custom tool for processing data",
      "script": "mcpserver/my_tool.py"
    }
  ]
}

4. Run Your Server:

cd backend/MyCustomAgent
python main.py --port 10006

Best Practices

• Prompts: Please carefully experiment with your different prompts to achieve the best experience.
• MCP Tools: The naming and description of MCP tools, as well as the docstrings for MCP tool functions, must precisely align with the business logic to make them easy for the LLM to understand.

⚠️ Notes

• Tool Naming: Use camelCase for tool names in mcp_config.json (e.g., SearchTool, RAGTool) to ensure compatibility.
• Environment Variables: Store API keys and sensitive data in the .env file.
• Port Conflicts: Ensure unique ports for each agent to avoid conflicts.

🧩 Core Features

• Single-Agent Interface: Simple, intuitive UI for interacting with a single A2A agent.
• Multi-Agent Collaboration: Host agent coordinates multiple A2A agents for complex tasks.
• MCP Integration: Seamless access to external tools and data via MCP.
• Rich Examples: Comprehensive examples for both single and multi-agent setups.
• Full-Stack: Backend and frontend components for immediate deployment.

🗺️ Use Cases

• AI-Powered Assistants: Build intelligent assistants with single or multi-agent setups.
• Research Tools: Create collaborative agent systems for data analysis or search.
• Enterprise Workflows: Coordinate multiple agents for complex business processes.
• Educational Platforms: Demonstrate agent collaboration for learning purposes.

📖 Contributing

We welcome contributions! To get started:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/my-feature).
3. Commit your changes (git commit -m 'Add my feature').
4. Push to the branch (git push origin feature/my-feature).
5. Open a pull request.

See our contributing guide for more details.

Acknowledgements

This project draws inspiration from and gratefully acknowledges the contributions of the following open-source project:

• Google A2A Project

🤝 Community & Support

• GitHub Issues: Report bugs or request features.
• GitHub Discussions: Ask questions and share ideas.

📄 License

This project is licensed under the MIT License - Free for all.

---

Made with ❤️ by Johnson Guo

WeiChat 微信

johnsongzc