# raflfaisal/a2a architecture

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

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

## Overview

##### Project type and purpose
- From the README and file tree, this is an open‐source protocol implementation (“Agent2Agent Protocol A2A”) plus reference clients, servers, demos, and sample agents in both Python and JavaScript.
- Purpose: define, demonstrate, and test an HTTP‐based, multi‐agent communication protocol (discovery, task management, streaming, push notifications).

##### File structure
Top‐level directories:
- specification/ – JSON schema of the protocol
- samples/ – language‐specific reference implementations (Python and JS): clients, servers, agents, CLI, common libraries
- demo/ – a multi‐agent web UI showcasing A2A in action
- tests/ – unit and integration tests validating the spec and in‐memory implementations

Key components under demo/ui:
- ui/pages & ui/components – React‐style UI modules
- ui/service/server & ui/service/client – local in‐browser A2A server and client managers
- ui/state & ui/utils – application state management and helpers

Under samples/python and samples/js:
- common/client & common/server – shared client/server libraries implementing the protocol
- hosts/ & agents/ – sample agent and host frameworks showing ADK usage
- cli – command‐line interfaces

##### README for additional insights
– The protocol revolves around Agent Cards, A2A Client, A2A Server, Tasks, Messages, Parts, Artifacts, Streaming (SSE), and Push Notifications.
– Typical flow: discovery → initiation → processing (streaming or batch) → optional input → completion.
– References to JSON specification, technical docs, and sample code.

##### Detail level
- Don’t simply lump everything into “frontend” and “backend.” Instead, break out:
- Protocol Spec
- Client SDKs (Python, JS)
- Server SDKs (Python, JS)
- Sample Agents & Hosts
- Demo UI (Pages / Components / State / Service layers)
- Infrastructure channels (HTTP, SSE, Webhooks)
- Both synchronous (tasks/send) and asynchronous (tasks/sendSubscribe + SSE + Webhook) paths.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Protocol Specification
    subgraph "Protocol Specification"
        Spec["Agent2Agent Protocol Specification"]:::data
    end
    click Spec "https://github.com/raflfaisal/a2a/blob/main/specification/json/a2a.json"

    %% Client SDKs
    subgraph "Client SDKs"
        subgraph Python
            PyClient["A2A Client Library"]:::frontend
            click PyClient "https://github.com/raflfaisal/a2a/blob/main/samples/python/common/client/client.py"
            PyCard["Client Card Resolver"]:::frontend
            click PyCard "https://github.com/raflfaisal/a2a/blob/main/samples/python/common/client/card_resolver.py"
        end
        subgraph JavaScript
            JSClient["A2A Client Library"]:::frontend
            click JSClient "https://github.com/raflfaisal/a2a/blob/main/samples/js/src/client/client.ts"
        end
    end

    %% Server SDKs
    subgraph "Server SDKs"
        subgraph Python
            PyServer["A2A Server Library"]:::frontend
            click PyServer "https://github.com/raflfaisal/a2a/blob/main/samples/python/common/server/server.py"
            PyTM["Task Manager"]:::frontend
            click PyTM "https://github.com/raflfaisal/a2a/blob/main/samples/python/common/server/task_manager.py"
            PyCache["In-Memory Cache Utility"]:::frontend
            click PyCache "https://github.com/raflfaisal/a2a/blob/main/samples/python/common/utils/in_memory_cache.py"
            PyAuth["Push Notification Auth Utility"]:::frontend
            click PyAuth "https://github.com/raflfaisal/a2a/blob/main/samples/python/common/utils/push_notification_auth.py"
        end
        subgraph JavaScript
            JSServer["A2A Server Library"]:::frontend
            click JSServer "https://github.com/raflfaisal/a2a/blob/main/samples/js/src/server/server.ts"
            Handler["Server Handler"]:::frontend
            click Handler "https://github.com/raflfaisal/a2a/blob/main/samples/js/src/server/handler.ts"
            Store["Server Store"]:::frontend
            click Store "https://github.com/raflfaisal/a2a/blob/main/samples/js/src/server/store.ts"
            ErrorDef["Error Definitions"]:::frontend
            click ErrorDef "https://github.com/raflfaisal/a2a/blob/main/samples/js/src/server/error.ts"
            UtilsJS["Server Utils"]:::frontend
            click UtilsJS "https://github.com/raflfaisal/a2a/blob/main/samples/js/src/server/utils.ts"
        end
    end

    %% Sample Agents - Python
    subgraph "Sample Agents - Python"
        GAAgent["Google ADK Agent"]:::frontend
        click GAAgent "https://github.com/raflfaisal/a2a/blob/main/samples/python/agents/google_adk/agent.py"
        GATM["Google ADK Task Manager"]:::frontend
        click GATM "https://github.com/raflfaisal/a2a/blob/main/samples/python/agents/google_adk/task_manager.py"
        CrewA["CrewAI Agent"]:::frontend
        click CrewA "https://github.com/raflfaisal/a2a/blob/main/samples/python/agents/crewai/agent.py"
        CrewTM["CrewAI Task Manager"]:::frontend
        click CrewTM "https://github.com/raflfaisal/a2a/blob/main/samples/python/agents/crewai/task_manager.py"
        LGAgent["LangGraph Agent"]:::frontend
        click LGAgent "https://github.com/raflfaisal/a2a/blob/main/samples/python/agents/langgraph/agent.py"
        LGTM["LangGraph Task Manager"]:::frontend
        click LGTM "https://github.com/raflfaisal/a2a/blob/main/samples/python/agents/langgraph/task_manager.py"
    end

    %% Sample Agents - JS
    subgraph "Sample Agents - JS"
        CoderA["Coder Agent"]:::frontend
        click CoderA "https://github.com/raflfaisal/a2a/blob/main/samples/js/src/agents/coder/index.ts"
        MovieA["Movie Agent"]:::frontend
        click MovieA "https://github.com/raflfaisal/a2a/blob/main/samples/js/src/agents/movie-agent/index.ts"
    end

    %% Sample Hosts - Python
    subgraph "Sample Hosts - Python"
        CLIHost["CLI Host"]:::frontend
        click CLIHost "https://github.com/raflfaisal/a2a/blob/main/samples/python/hosts/cli/__main__.py"
        PushList["Push Listener"]:::frontend
        click PushList "https://github.com/raflfaisal/a2a/blob/main/samples/python/hosts/cli/push_notification_listener.py"
        MultiHost["Multiagent Host"]:::frontend
        click MultiHost "https://github.com/raflfaisal/a2a/blob/main/samples/python/hosts/multiagent/host_agent.py"
        MultiHost1["Agent Entry"]:::frontend
        click MultiHost1 "https://github.com/raflfaisal/a2a/blob/main/samples/python/hosts/multiagent/agent.py"
        MultiHost2["Remote Agent Connection"]:::frontend
        click MultiHost2 "https://github.com/raflfaisal/a2a/blob/main/samples/python/hosts/multiagent/remote_agent_connection.py"
    end

    %% Sample Hosts - JS
    subgraph "Sample Hosts - JS"
        CLIJS["JS CLI Host"]:::frontend
        click CLIJS "https://github.com/raflfaisal/a2a/blob/main/samples/js/src/cli.ts"
    end

    %% Demo UI
    subgraph "Demo UI"
        subgraph Pages
            Home["Home Page"]:::frontend
            click Home "https://github.com/raflfaisal/a2a/blob/main/demo/ui/pages/home.py"
            ListP["Agent List Page"]:::frontend
            click ListP "https://github.com/raflfaisal/a2a/blob/main/demo/ui/pages/agent_list.py"
        end
        subgraph Components
            UIComp["UI Components"]:::frontend
            click UIComp "https://github.com/raflfaisal/a2a/blob/main/demo/ui/components/agent_list.py"
        end
        subgraph Services
            UIClient["Client Service Manager"]:::frontend
            click UIClient "https://github.com/raflfaisal/a2a/blob/main/demo/ui/service/client/client.py"
            UIServer["Core Server Service"]:::frontend
            click UIServer "https://github.com/raflfaisal/a2a/blob/main/demo/ui/service/server/server.py"
            InMemMgr["In-Memory Manager"]:::frontend
            click InMemMgr "https://github.com/raflfaisal/a2a/blob/main/demo/ui/service/server/in_memory_manager.py"
            ADKMgr["ADK Host Manager"]:::frontend
            click ADKMgr "https://github.com/raflfaisal/a2a/blob/main/demo/ui/service/server/adk_host_manager.py"
            AppMgr["Application Manager"]:::frontend
            click AppMgr "https://github.com/raflfaisal/a2a/blob/main/demo/ui/service/server/application_manager.py"
            TestImg["Test Image Loader"]:::frontend
            click TestImg "https://github.com/raflfaisal/a2a/blob/main/demo/ui/service/server/test_image.py"
        end
        subgraph State
            StateApp["App State"]:::frontend
            click StateApp "https://github.com/raflfaisal/a2a/blob/main/demo/ui/state/state.py"
        end
        subgraph Utils
            CardUtil["Agent Card Utility"]:::frontend
            click CardUtil "https://github.com/raflfaisal/a2a/blob/main/demo/ui/utils/agent_card.py"
        end
    end

    %% Data Artifacts
    AgentCard["Agent Card"]:::data
    Task["Task"]:::data
    Message["Message"]:::data

    %% Event Streams
    SSE["SSE Stream"]:::event
    Webhook["Webhook"]:::event

    %% Relationships
    Spec -->|references| PyClient
    Spec -->|references| JSClient
    PyClient -->|GET /.well-known/agent.json| AgentCard
    AgentCard -->|served by| PyServer
    PyClient -->|POST tasks/send| PyServer
    PyClient -->|POST tasks/sendSubscribe| PyServer
    PyServer -->|process via| PyTM
    PyServer -->|use cache| PyCache
    PyServer -->|auth push| PyAuth
    PyTM -->|invoke| GAAgent
    PyTM -->|invoke| CoderA
    PyServer -->|stream| SSE
    SSE -->|to| PyClient
    PyServer -->|push| Webhook
    PyClient -->|in-demo| UIClient

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px
    classDef event fill:#FFA500,stroke:#333,stroke-width:1px
```
