# a2aproject/a2a-samples architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source sample/demo repository illustrating the Agent-to-Agent (A2A) protocol in multiple languages.
- It contains:
– A standalone “Demo UI” (Python backend + JS/TS frontend) for inspecting and orchestrating A2A flows.
– Language-specific sample projects (Go, Java, JavaScript, Python) demonstrating A2A clients and servers.
– Common Python SDK modules and host frameworks under `samples/python/common` and `samples/python/hosts`.
– Notebooks for quickstarts.

##### File structure
- Top-level: CI/config files, README, CONTRIBUTING, license.
- `demo/ui`:
– `components/` + `pages/`: frontend UI components and screens.
– `service/client/` and `service/server/`: client and server implementations of the A2A JSONRPC protocol over HTTP/SSE.
– `state/`: in-memory agent/task state management.
- `samples/go`, `samples/java`, `samples/js`, `samples/python`: each a self-contained microservice or CLI implementing A2A client/server patterns.
- `samples/python/common` & `samples/python/hosts`: shared protocol utilities, host agent frameworks, multi-agent orchestration.
- `notebooks/`: Jupyter quickstart examples.

##### README for additional insights
- Confirms this is a code sample repo for demonstration only.
- Points to the A2A spec, SDK repos, and the “a2a-inspector” UI tool (which the demo UI resembles).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Demo UI Frontend
    subgraph "Demo UI"
        subgraph "Frontend Layer"
            UI_Components["Components"]:::frontend
            UI_Pages["Pages"]:::frontend
        end
        subgraph "UI State Management"
            StateMain["state.py"]:::frontend
            AgentState["agent_state.py"]:::frontend
            HostAgentService["host_agent_service.py"]:::frontend
        end
        subgraph "Backend Layer"
            BackendServer["server.py"]:::backend
            InMem["in_memory_manager.py"]:::backend
            HostMgr["adk_host_manager.py"]:::backend
            AppMgr["application_manager.py"]:::backend
        end
    end

    %% Transport Layer
    subgraph "A2A Transport Layer"
        TransportClient["client.py\n(JSONRPC over HTTP/SSE)"]:::transport
    end

    %% Sample Agents/Servers
    subgraph "Sample Agents/Servers"
        GoClient["Go Client\nclient.go"]:::agent
        GoServer["Go Server\nserver.go"]:::agent
        JavaClient["Java Client\nA2AClient.java"]:::agent
        JavaServer["Java Server\nA2AServer.java"]:::agent
        JSAgents["JS Agents\nsrc/agents/"]:::agent
        JSCLI["JS CLI\ncli.ts"]:::agent
        PythonAgents["Python Agents"]:::agent
    end

    %% Common SDK & Hosts
    subgraph "Common Python SDK & Host Framework"
        SDKClient["client.py"]:::agent
        SDKServer["server.py"]:::agent
        HostCLI["__main__.py"]:::agent
        MultiHost["host_agent.py"]:::agent
    end

    %% Notebooks
    Quickstart["a2a_quickstart.ipynb"]:::external

    %% External Systems
    ExternalLLM["External LLMs / APIs"]:::external

    %% Connections
    UI_Components -->|HTTP fetch / SSE subscribe| TransportClient
    UI_Pages -->|HTTP fetch / SSE subscribe| TransportClient
    TransportClient -->|"HTTP POST JSONRPC / SSE"| BackendServer
    BackendServer --> InMem
    BackendServer --> HostMgr
    BackendServer --> AppMgr

    GoClient -->|"JSONRPC over HTTP"| BackendServer
    GoServer -->|"JSONRPC over HTTP"| BackendServer
    JavaClient -->|"JSONRPC over HTTP"| BackendServer
    JavaServer -->|"JSONRPC over HTTP"| BackendServer
    JSAgents -->|"JSONRPC over HTTP"| BackendServer
    JSCLI -->|"JSONRPC over HTTP"| BackendServer
    PythonAgents -->|"JSONRPC over HTTP"| BackendServer

    Quickstart -->|invokes SDK| SDKClient
    SDKClient -->|"JSONRPC"| BackendServer
    SDKServer -->|"JSONRPC"| BackendServer
    HostCLI -->|"orchestrates multi-agent"| BackendServer
    MultiHost -->|"orchestrates multi-agent"| BackendServer

    BackendServer -->|calls / orchestrates| ExternalLLM

    %% Click Events
    click UI_Components "https://github.com/a2aproject/a2a-samples/tree/main/demo/ui/components/"
    click UI_Pages "https://github.com/a2aproject/a2a-samples/tree/main/demo/ui/pages/"
    click StateMain "https://github.com/a2aproject/a2a-samples/blob/main/demo/ui/state/state.py"
    click AgentState "https://github.com/a2aproject/a2a-samples/blob/main/demo/ui/state/agent_state.py"
    click HostAgentService "https://github.com/a2aproject/a2a-samples/blob/main/demo/ui/state/host_agent_service.py"
    click BackendServer "https://github.com/a2aproject/a2a-samples/blob/main/demo/ui/service/server/server.py"
    click InMem "https://github.com/a2aproject/a2a-samples/blob/main/demo/ui/service/server/in_memory_manager.py"
    click HostMgr "https://github.com/a2aproject/a2a-samples/blob/main/demo/ui/service/server/adk_host_manager.py"
    click AppMgr "https://github.com/a2aproject/a2a-samples/blob/main/demo/ui/service/server/application_manager.py"
    click TransportClient "https://github.com/a2aproject/a2a-samples/blob/main/demo/ui/service/client/client.py"
    click GoClient "https://github.com/a2aproject/a2a-samples/blob/main/samples/go/client/client.go"
    click GoServer "https://github.com/a2aproject/a2a-samples/blob/main/samples/go/server/server.go"
    click JavaClient "https://github.com/a2aproject/a2a-samples/blob/main/samples/java/client/src/main/java/com/google/a2a/client/A2AClient.java"
    click JavaServer "https://github.com/a2aproject/a2a-samples/blob/main/samples/java/server/src/main/java/com/google/a2a/server/A2AServer.java"
    click JSAgents "https://github.com/a2aproject/a2a-samples/tree/main/samples/js/src/agents/"
    click JSCLI "https://github.com/a2aproject/a2a-samples/blob/main/samples/js/src/cli.ts"
    click PythonAgents "https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/"
    click SDKClient "https://github.com/a2aproject/a2a-samples/blob/main/samples/python/common/client/client.py"
    click SDKServer "https://github.com/a2aproject/a2a-samples/blob/main/samples/python/common/server/server.py"
    click HostCLI "https://github.com/a2aproject/a2a-samples/blob/main/samples/python/hosts/cli/__main__.py"
    click MultiHost "https://github.com/a2aproject/a2a-samples/blob/main/samples/python/hosts/multiagent/host_agent.py"
    click Quickstart "https://github.com/a2aproject/a2a-samples/blob/main/notebooks/a2a_quickstart.ipynb"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#0277BD,color:#000
    classDef backend fill:#E8F5E9,stroke:#2E7D32,color:#000
    classDef transport fill:#FFF3E0,stroke:#EF6C00,color:#000
    classDef agent fill:#E1BEE7,stroke:#8E24AA,color:#000
    classDef external fill:#CFD8DC,stroke:#455A64,color:#000
```
