# google-a2a/a2a-samples architecture

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

- Interactive diagram: https://gitdiagram.com/google-a2a/a2a-samples
- Repository: https://github.com/google-a2a/a2a-samples

## Overview

##### Project type and purpose
- This is a Python “multi-agent” sample demonstrating the Agent2Agent (A2A) Protocol, specifically the A2A Multi-Agent Coordination Pattern (MCP) example.
- It shows how multiple agents (defined by JSON “agent_cards”) coordinate via an MCP server and client, persisting state in a SQLite DB (travel_agency.db).

##### File structure under samples/python/agents/a2a_mcp
- agent_cards/
- Static JSON files defining each agent’s capabilities, prompts, and metadata.
- src/a2a_mcp/
- common/ – shared utilities, types, base classes (agent_executor, runner, workflow).
- mcp/client.py – the client library for agents to register, send tasks, and receive responses.
- mcp/server.py – the MCP server orchestrating requests between agents and persisting history.
- agents/ – entry points for each agent (adk_travel_agent.py, orchestrator_agent.py, planner_agent.py).
- travel_agency.db
- SQLite database used by the MCP server to store task history, agent state, and routing information.

##### README for additional insights
- The sample is meant to run without extra frameworks: you launch the MCP server, then run each agent’s __main__ which uses the MCP client to register and communicate.

##### Main components and interactions (to appear
a. agent_cards
– JSON definitions loaded by each agent at startup.
b. Agents (Python processes)
– Orchestrator Agent
– Planner Agent
– ADK Travel Agent
They each:
- Load their card
- Use the MCP client to register with the server
- Send/receive tasks (via JSON-RPC over HTTP or in-memory transport)
c. MCP Client (embedded in each agent)
– Provides send_task(), get_task(), subscribe() interfaces.
d. MCP Server
– Listens for JSON-RPC requests from clients
– Routes messages between agents according to the protocol
– Persists messages and task state in travel_agency.db
e. SQLite DB travel_agency.db
– Tables for task_queue, agent_registry, history
f. common utilities
– Shared code for serializing messages, managing workflows, caching, etc.

##### Relationships and data flow
- Agent process → (loads JSON card) → MCP Client
- MCP Client ↔ (JSON-RPC / HTTP / in-memory) ↔ MCP Server
- MCP Server → (reads/writes) → travel_agency.db
- MCP Server → (routes requests) → target Agent process via its MCP Client
- common modules are imported by both server and clients for shared logic (types, serialization)

##### Architectural patterns and design principles
- Microservice-style: each agent is an independent process, communicating over a protocol.
- Pub/Sub / request-response mix: agents subscribe to task updates.
- Persistence layer clearly separated (SQLite).
- Clear separation of concerns: agents (business logic), client (protocol implementation), server (orchestration), common (utilities).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Resource
    AC["agent_cards/"]:::resource
    click AC "https://github.com/google-a2a/a2a-samples/tree/main/samples/python/agents/a2a_mcp/agent_cards/"

    %% Agents
    subgraph "Agents" 
        direction TB
        OR["Orchestrator Agent"]:::agent
        PL["Planner Agent"]:::agent
        ADK["ADK Travel Agent"]:::agent
    end
    click OR "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/agents/orchestrator_agent.py"
    click PL "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/agents/langgraph_planner_agent.py"
    click ADK "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/agents/adk_travel_agent.py"

    %% Entry CLI
    CLI["Agents CLI Entry (__main__.py)"]:::agent
    click CLI "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/agents/__main__.py"

    %% Client & Server
    CLIENT["MCP Client"]:::clientserver
    click CLIENT "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/mcp/client.py"
    SERVER["MCP Server"]:::clientserver
    click SERVER "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/mcp/server.py"

    %% Database
    DB["travel_agency.db"]:::db
    click DB "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/travel_agency.db"

    %% Common Utilities
    subgraph "Common Utilities" 
        direction TB
        CE["agent_executor.py"]:::common
        CR["agent_runner.py"]:::common
        BA["base_agent.py"]:::common
        PR["prompts.py"]:::common
        TY["types.py"]:::common
        UT["utils.py"]:::common
        WF["workflow.py"]:::common
    end
    click CE "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/common/agent_executor.py"
    click CR "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/common/agent_runner.py"
    click BA "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/common/base_agent.py"
    click PR "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/common/prompts.py"
    click TY "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/common/types.py"
    click UT "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/common/utils.py"
    click WF "https://github.com/google-a2a/a2a-samples/blob/main/samples/python/agents/a2a_mcp/src/a2a_mcp/common/workflow.py"

    %% Connections
    AC -->|loads JSON| OR
    AC -->|loads JSON| PL
    AC -->|loads JSON| ADK

    OR -->|"register()/send_task()"| CLIENT
    PL -->|"register()/send_task()"| CLIENT
    ADK -->|"register()/send_task()"| CLIENT
    CLI -->|starts agents| OR
    CLI -->|starts agents| PL
    CLI -->|starts agents| ADK

    CLIENT -->|"JSON-RPC"| SERVER
    SERVER -->|"store/read"| DB
    SERVER -->|"deliver task"| CLIENT

    CLIENT -->|uses| CE
    CLIENT -->|uses| CR
    CLIENT -->|uses| BA
    CLIENT -->|uses| PR
    CLIENT -->|uses| TY
    CLIENT -->|uses| UT
    CLIENT -->|uses| WF

    SERVER -->|uses| CE
    SERVER -->|uses| CR
    SERVER -->|uses| BA
    SERVER -->|uses| PR
    SERVER -->|uses| TY
    SERVER -->|uses| UT
    SERVER -->|uses| WF

    %% Styling
    classDef agent fill:#D5E8D4,stroke:#333,stroke-width:1px;
    classDef clientserver fill:#FFE6CC,stroke:#333,stroke-width:1px;
    classDef db fill:#FFF2CC,stroke:#333,stroke-width:1px;
    classDef common fill:#E1D5E7,stroke:#333,stroke-width:1px;
    classDef resource fill:#F8CECC,stroke:#333,stroke-width:1px;
```
