A2A + MCP Workshop

Build production-ready multi-agent systems from scratch — two complete, runnable use cases wired with the A2A protocol and MCP.

This workshop teaches you how to design and wire a multi-agent system where agents communicate over the A2A protocol and access tools through MCP. You get two fully working use cases, each with its own agents, MCP server, tests, and a one-command start script.

Every system in this repo follows the same pattern: a user message reaches an Orchestrator, which reads each agent's Agent Card, scores keyword matches, and forwards the request to the right specialist Remote Agent. That agent calls tools on the MCP Server and streams back a response.

flowchart LR
    User["User / CLI / Tests / UI"]
    Orch["Orchestrator Agent\n(keyword routing via Agent Cards)"]
    RA1["Remote Agent A"]
    RA2["Remote Agent B"]
    RA3["Remote Agent C"]
    MCP["MCP Server\n(tools + data)"]

    User -->|"A2A send_message"| Orch
    Orch -->|"A2A send_message"| RA1
    Orch -->|"A2A send_message"| RA2
    Orch -->|"A2A send_message"| RA3
    RA1 -->|"MCP call_tool"| MCP
    RA2 -->|"MCP call_tool"| MCP
    RA3 -->|"MCP call_tool"| MCP

See docs/architecture.md for detailed sequence diagrams and internal agent anatomy.

A trip-planning assistant. Ask about weather, activities, packing, or local tips — the orchestrator routes to the right specialist agent.

Prerequisites: Python 3.11+, Azure OpenAI credentials, internet access (Open-Meteo + Nominatim geocoding).

cd use_cases/travel_activity_planner
pip install -e .
cp .env.example .env    # add Azure OpenAI credentials
.\start_all.ps1

Full README · Architecture · Troubleshooting

An offline learning assistant. Explain topics, run quizzes, track progress, and build personalized study plans — no API key required for the agents.

No API key required for agents. Only the Orchestrator uses Azure OpenAI. All three remote agents and every MCP test run 100% offline.

cd use_cases/personalized_learning
pip install -e .
cp .env.example .env    # only needed to run the Orchestrator
.\start_all.ps1

Full README · Architecture · Exercises · Extending

Google Colab: open workshop_colab.ipynb — no local setup required.

New to A2A or MCP? Here is what every term means and where to find it in the code.

See docs/glossary.md for the full glossary with analogies and code examples.

# 1. Clone the repo
git clone <repo-url>
cd a2a_mcp_workshop

# 2. Choose a use case
cd use_cases/personalized_learning   # no API key needed
# or
cd use_cases/travel_activity_planner # requires Azure OpenAI + internet

# 3. Install
pip install -e .

# 4. Configure environment
cp .env.example .env
# Edit .env with your Azure OpenAI credentials (travel: required; learning: Orchestrator only)

# 5. Start all services
.\start_all.ps1          # MCP server + all agents
.\start_all.ps1 -UI      # also opens Streamlit MCP Playground on :8504
.\start_all.ps1 -Stop    # stop everything

# 6. Run tests
python tests/run_all_tests.py --skip-agents   # fast: MCP only, no agents needed
python tests/run_all_tests.py                 # full suite (all services must be running)

See docs/quickstart.md for a detailed walkthrough including health checks and the interactive CLI client.

a2a_mcp_workshop/
├── docs/                              # Shared documentation
│   ├── glossary.md                    # A2A + MCP terminology guide
│   ├── architecture.md                # System-wide Mermaid diagrams
│   └── quickstart.md                  # Step-by-step setup guide
│
└── use_cases/
    ├── travel_activity_planner/       # LLM agents + live weather API
    │   ├── a2a_agents/                # Orchestrator + 3 remote agents
    │   ├── mcp/                       # FastMCP server + tools + local data
    │   ├── tests/                     # MCP, agent, multi-turn test suites
    │   ├── ui/                        # Streamlit MCP Playground
    │   ├── docs/                      # Architecture + troubleshooting
    │   ├── start_all.ps1              # One-command startup
    │   └── pyproject.toml
    │
    └── personalized_learning/         # 100% offline — no API key for agents
        ├── a2a_agents/                # Orchestrator + 3 rule-based remote agents
        ├── mcp/                       # FastMCP server + 8 tools + local JSON data
        ├── tests/                     # MCP, agent, memory, e2e test suites
        ├── ui/                        # Streamlit MCP Playground
        ├── docs/                      # Architecture, exercises, extending, troubleshooting
        ├── workshop_colab.ipynb       # Google Colab entry point
        ├── start_all.ps1              # One-command startup
        └── pyproject.toml

# Fast path — MCP tools only, no agents or API key needed
python tests/run_all_tests.py --skip-agents

# Full suite — all services must be running
python tests/run_all_tests.py --verbose

# Individual groups (learning use case example)
python tests/run_all_tests.py --only mcp
python tests/run_all_tests.py --only topic
python tests/run_all_tests.py --only e2e