# tsadoq/a2a-mcp-tutorial architecture

> Architecture diagram of the GitHub repository tsadoq/a2a-mcp-tutorial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsadoq/a2a-mcp-tutorial
- Repository: https://github.com/tsadoq/a2a-mcp-tutorial

## Overview

##### Project type and purpose
- This is not a traditional web app but a distributed, microservice-style agent pipeline.
- It uses two complementary open protocols:
– Agent2Agent (A2A) for peer-to-peer agent coordination
– Model Context Protocol (MCP) for tool/resource access by agents
- It’s structured as a set of Python services: MCP servers, A2A servers (host + sub-agents), and helper libraries.

##### File structure
Top-level dirs & their roles:
- a2a_servers/agent_servers: three A2A HTTP servers (host_agent, google_search_agent, stock_report_agent)
- a2a_servers/agents: ADKAgent implementation bridging ADK → A2A
- a2a_servers/common: shared A2A client/server, task manager, types, utils
- a2a_servers/hosts/cli: a CLI client for local testing
- mcp_server: two MCP servers—stdio transport and SSE transport—for search & stocks
- services/search_engine_service & services/stocks_service: wrappers around Serper.dev & Finnhub APIs
- adk_agents_testing: scripts to spin up MCP clients and test pipelines

##### Key README insights
- Two MCP servers (crawler = SerperDevService, stock retriever = FinHubService), each exposed over STDIO or SSE
- An ADK “Runner” that spawns an LlmAgent (root + sub-agents) and wires in MCP tools
- A hierarchical ADK crew and a peer-to-peer A2A crew, each running as standalone HTTP servers
- Starlette/Uvicorn used to host MCP SSE servers and A2A servers

##### Components
A. User / CLI Client
– Represents host_cli or any local client in a2a_servers/hosts/cli
B. Host Agent (A2A HTTP Server)
– Exposes /.well-known/agent.json and /host_agent endpoint
– Coordinates tasks, holds AgentCard for sub-agents
C. Sub-Agents (A2A HTTP Servers)
– google_search_agent and stock_report_agent
– Each exposes its own AgentCard and /<agent> endpoint
D. Agent Library Layers
– a2a_servers/common: A2A Request/Response types, TaskManager, RemoteAgentConnection
– a2a_servers/agents/adk_agent.py: ADKAgent adapter bridging LLM + tools → A2A protocol
E. Runner / Session / Artifact Services
– InMemorySessionService, InMemoryArtifactService, Runner in README
F. MCP Tool Servers
– search_server.py (stdio & SSE transports)
– stocks_server.py (stdio & SSE transports)
G. External Services
– Serper.dev (Google Search + scraper)
– Finnhub (stock data)

##### Relationships & Interactions
- User → CLI → Host Agent: HTTP POST tasks/sendSubscribe
- Host Agent ↔ Sub-Agents: A2A JSON-RPC over HTTP, tasks delegation
- Agents → MCP Servers:
– STDIO: subprocess stdin/stdout JSON-RPC
– SSE: HTTP POST to /sse and Server-Sent Events on /messages/
- MCP Servers → External APIs: REST calls to Serper.dev or Finnhub
- Responses flow back up the chain, with each layer enriching context/artifacts

##### Architectural patterns & design principles
- Microservices: each agent and MCP server is its own deployable service
- Protocol layering: A2A on top of HTTP/JSON-RPC, MCP on top of STDIO or SSE
- Separation of concerns:
– Agents focus on LLM orchestration & delegation
– MCP servers focus on tool abstraction
– services/* focus on external API integration
- Async I/O everywhere (asyncio, Starlette, Uvicorn)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Client
    subgraph "Layer 1: Client"
        U["User / CLI Client"]:::client
    end

    %% Layer 2: A2A Host
    subgraph "Layer 2: A2A Host"
        HA["Host Agent\n(Starlette/Uvicorn)"]:::agent
    end

    %% Layer 2b: A2A Libraries & ADK
    subgraph "A2A Libraries & ADK"
        CL["A2A Common Library"]:::lib
        ADK["ADKAgent Adapter"]:::lib
        RAC["RemoteAgentConnection"]:::lib
    end

    %% Testing Scripts
    subgraph "Testing Scripts"
        HIER["Hierarchical Agent Test\n(ADK Runner)"]:::client
        SINGLE["Single-Agent MCP Test"]:::client
    end

    %% Layer 3: A2A Sub-Agents
    subgraph "Layer 3: A2A Sub-Agents"
        GA["Google Search Agent\n(Starlette/Uvicorn)"]:::agent
        SA["Stock Report Agent\n(Starlette/Uvicorn)"]:::agent
    end

    %% Layer 4: MCP Tool Servers
    subgraph "Layer 4: MCP Tool Servers"
        subgraph "STDIO Transport"
            SS["Search Server\n(STDIO)"]:::mcp
            STKS["Stocks Server\n(STDIO)"]:::mcp
        end
        subgraph "SSE Transport"
            SS2["Search Server\n(SSE)"]:::mcp
            STKS2["Stocks Server\n(SSE)"]:::mcp
        end
    end

    %% Layer 5: External APIs
    subgraph "Layer 5: External APIs"
        E1["Serper.dev"]:::external
        E2["Finnhub"]:::external
    end

    %% Connections
    U -->|"POST /tasks/sendSubscribe\n(JSON-RPC HTTP)"| HA
    HA -->|"A2A JSON-RPC\nHTTP POST"| GA
    HA -->|"A2A JSON-RPC\nHTTP POST"| SA
    GA -->|"delegates to\nMCP STDIO"| SS
    GA -->|"delegates to\nMCP SSE"| SS2
    SA -->|"delegates to\nMCP STDIO"| STKS
    SA -->|"delegates to\nMCP SSE"| STKS2
    SS -->|"REST API"| E1
    SS2 -->|"REST API"| E1
    STKS -->|"REST API"| E2
    STKS2 -->|"REST API"| E2

    %% Click Events
    click U "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/a2a_servers/hosts/cli/__main__.py"
    click HA "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/a2a_servers/agent_servers/host_agent_server.py"
    click GA "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/a2a_servers/agent_servers/gsearch_report_agent_server.py"
    click SA "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/a2a_servers/agent_servers/stock_report_agent_server.py"
    click CL "https://github.com/tsadoq/a2a-mcp-tutorial/tree/main/a2a_servers/common/"
    click ADK "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/a2a_servers/agents/adk_agent.py"
    click RAC "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/a2a_servers/agents/utils/remote_agent_connection.py"
    click HIER "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/adk_agents_testing/hierarchical_agents.py"
    click SINGLE "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/adk_agents_testing/single_agent_search_mcp.py"
    click SS "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/mcp_server/stdio/search_server.py"
    click STKS "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/mcp_server/stdio/stocks_server.py"
    click SS2 "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/mcp_server/sse/search_server.py"
    click STKS2 "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/mcp_server/sse/stocks_server.py"
    click E1 "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/services/search_engine_service/serper_dev_service.py"
    click E2 "https://github.com/tsadoq/a2a-mcp-tutorial/blob/main/services/stocks_service/finhub_service.py"

    %% Styles
    classDef client fill:#FFA500,stroke:#333,stroke-width:1px
    classDef agent fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef lib fill:#9370DB,stroke:#333,stroke-width:1px
    classDef mcp fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
