# theailanguage/a2a_samples architecture

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

- Interactive diagram: https://gitdiagram.com/theailanguage/a2a_samples
- Repository: https://github.com/theailanguage/a2a_samples

## Overview

##### Project type and purpose
- This is a sample-repo of four progressive implementations of Google’s A2A (Agent-to-Agent) protocol. Each version is a standalone microservice demo:
- version_1_simple: basic Flask HTTP client/server
- version_2_adk_agent: single ADK (Agent Development Kit) agent with JSON-RPC
- version_3_multi_agent: multi-agent orchestration (OrchestratorAgent + child agents + registry)
- version_4_multi_agent_mcp: distributed multi-agent + MCP (Model Context Protocol) integration

##### File structure
- Top-level “version_n…” directories each contain:
- agents/ (1 or more agent implementations)
- app/cmd/ (CLI entrypoint)
- client/ (client module or CLI)
- models/ (Pydantic or JSON-RPC schema)
- server/ (server and TaskManager)
- utilities/ (discovery, registry, MCP connectors in v3/v4)
- pyproject.toml (build/config)

##### README insights
- Each version README calls out its architecture:
- v1: simple REST endpoints
- v2: uses ADK runners & Gemini LLM under the hood
- v3: uses a registry (agent_registry.json) + OrchestratorAgent
- v4: adds MCP discovery/config (mcp_config.json) and dynamic MCP connectors

- Green for clients/CLI
- Blue for agent servers
- Orange for discovery/registry
- Purple for external LLM/MCP services
- Rectangles for microservices

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Version 1
    subgraph "Version 1: Simple"
        C1["Time Client"]:::client
        S1["Flask Server"]:::agent
        C1 -->|"HTTP Request"| S1
        S1 -->|"HTTP Response"| C1
    end

    %% Version 2
    subgraph "Version 2: ADK Agent"
        C2["Client (CLI/HTTP)"]:::client
        S2["JSON-RPC Server & API"]:::agent
        TM2["TaskManager"]:::agent
        AG2["ADK Agent"]:::agent
        LLM2["Gemini LLM"]:::external
        C2 -->|"JSON-RPC"| S2
        S2 -->|"Dispatch Task"| TM2
        TM2 -->|"Run"| AG2
        AG2 -->|"Call LLM"| LLM2
        LLM2 -->|"Result"| AG2
        AG2 -->|"Task Response"| S2
        S2 -->|"JSON-RPC Response"| C2
    end

    %% Version 3
    subgraph "Version 3: Multi-Agent Orchestration"
        C3["Client (CLI/HTTP)"]:::client
        S3["Server & API"]:::agent
        OR3["OrchestratorAgent Server"]:::agent
        GA3["GreetingAgent"]:::agent
        TA3["TellTimeAgent"]:::agent
        REG3["Discovery & Registry Service"]:::registry
        C3 -->|"JSON-RPC"| S3
        S3 -->|"Forward"| OR3
        OR3 -->|"Lookup"| REG3
        OR3 -->|"Invoke"| GA3
        OR3 -->|"Invoke"| TA3
        GA3 -->|"Response"| OR3
        TA3 -->|"Response"| OR3
        OR3 -->|"Response"| S3
        S3 -->|"JSON-RPC Response"| C3
    end

    %% Version 4
    subgraph "Version 4: Multi-Agent with MCP"
        C4["Client (CLI/HTTP)"]:::client
        S4["Server & API"]:::agent
        OR4["OrchestratorAgent Server"]:::agent
        GA4["GreetingAgent"]:::agent
        TA4["TellTimeAgent"]:::agent
        A2A_DISC["A2A Discovery"]:::registry
        A2A_CONN["A2A Connector"]:::registry
        MCP_DISC["MCP Discovery"]:::registry
        MCP_CONN["MCP Connector"]:::registry
        LLM4["Gemini LLM"]:::external
        MCP_SERV["Anthropic MCP"]:::external
        C4 -->|"JSON-RPC"| S4
        S4 -->|"Forward"| OR4
        OR4 -->|"A2A Lookup"| A2A_DISC
        A2A_DISC -->|"List Agents"| OR4
        OR4 -->|"A2A Connect"| A2A_CONN
        OR4 -->|"Invoke"| GA4
        OR4 -->|"Invoke"| TA4
        OR4 -->|"MCP Lookup"| MCP_DISC
        OR4 -->|"MCP Connect"| MCP_CONN
        OR4 -->|"Call MCP"| MCP_SERV
        GA4 -->|"Response"| OR4
        TA4 -->|"Response"| OR4
        MCP_SERV -->|"Result"| OR4
        OR4 -->|"Response"| S4
        S4 -->|"JSON-RPC Response"| C4
    end

    %% Click Events v1
    click C1 "https://github.com/theailanguage/a2a_samples/blob/main/version_1_simple/client/time_client.py"
    click S1 "https://github.com/theailanguage/a2a_samples/blob/main/version_1_simple/server/tell_time_server.py"

    %% Click Events v2
    click C2 "https://github.com/theailanguage/a2a_samples/blob/main/version_2_adk_agent/client/client.py"
    click S2 "https://github.com/theailanguage/a2a_samples/blob/main/version_2_adk_agent/server/server.py"
    click TM2 "https://github.com/theailanguage/a2a_samples/blob/main/version_2_adk_agent/agents/google_adk/task_manager.py"
    click AG2 "https://github.com/theailanguage/a2a_samples/blob/main/version_2_adk_agent/agents/google_adk/agent.py"
    click LLM2 "https://github.com/theailanguage/a2a_samples/blob/main/version_2_adk_agent/models/json_rpc.py"
    click LLM2 "https://github.com/theailanguage/a2a_samples/blob/main/version_2_adk_agent/models/request.py"
    click LLM2 "https://github.com/theailanguage/a2a_samples/blob/main/version_2_adk_agent/models/task.py"

    %% Click Events v3
    click C3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/client/client.py"
    click S3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/server/server.py"
    click OR3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/agents/host_agent/orchestrator.py"
    click GA3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/agents/greeting_agent/agent.py"
    click TA3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/agents/tell_time_agent/agent.py"
    click REG3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/utilities/discovery.py"
    click REG3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/utilities/agent_registry.json"
    click S3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/server/task_manager.py"
    click GA3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/agents/greeting_agent/task_manager.py"
    click TA3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/agents/tell_time_agent/task_manager.py"
    click S3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/models/json_rpc.py"
    click S3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/models/request.py"
    click S3 "https://github.com/theailanguage/a2a_samples/blob/main/version_3_multi_agent/models/task.py"

    %% Click Events v4
    click C4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/client/client.py"
    click S4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/server/server.py"
    click OR4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/agents/host_agent/orchestrator.py"
    click GA4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/agents/greeting_agent/agent.py"
    click TA4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/agents/tell_time_agent/agent.py"
    click S4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/server/task_manager.py"
    click GA4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/agents/greeting_agent/task_manager.py"
    click TA4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/agents/tell_time_agent/task_manager.py"
    click A2A_DISC "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/utilities/a2a/agent_discovery.py"
    click A2A_CONN "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/utilities/a2a/agent_connect.py"
    click A2A_DISC "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/utilities/a2a/agent_registry.json"
    click MCP_DISC "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/utilities/mcp/mcp_discovery.py"
    click MCP_CONN "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/utilities/mcp/mcp_connect.py"
    click MCP_DISC "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/utilities/mcp/mcp_config.json"
    click S4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/models/json_rpc.py"
    click S4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/models/request.py"
    click S4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/models/task.py"
    click C4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/main.py"
    click C4 "https://github.com/theailanguage/a2a_samples/blob/main/version_4_multi_agent_mcp/pyproject.toml"

    %% Styles
    classDef client fill:#a8f0a5,stroke:#2d6a4f;
    classDef agent fill:#a0c4ff,stroke:#1e3a8a;
    classDef registry fill:#ffddb0,stroke:#c2410c;
    classDef external fill:#e0c3fc,stroke:#6b21a8;
```
