# google-a2a/a2a-python architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source Python SDK (“a2a-sdk”) that implements the Agent2Agent (A2A) protocol.
- It provides both a client library (to call A2A servers) and a server framework (to host agentic applications).
- Key use case: allow developers to build “agent servers” and invoke them via gRPC or JSON-RPC transports.

##### File structure
- Top-level “src/a2a” contains five main packages:
- auth – user authentication models
- client – A2A client classes and helpers
- grpc – generated protobuf stubs and gRPC wiring
- server – server framework (subpackages for apps, agent execution, events, request handlers, and tasks)
- utils – shared utilities (artifact, telemetry, proto conversions)
- Configuration & build: buf.gen.yaml for Protobuf codegen, pyproject.toml / noxfile.py for packaging and testing.
- Tests exercise every submodule and integration flows.

##### README for additional insights
- Confirms dual client/server nature.
- Examples show a remote agent running a server, and a client invoking it.
- Underlying transports: gRPC and JSON-RPC (via FastAPI/Starlette).

##### Don’t over-complicate—capture essential elements
- Them in the order a request flows.
- Abstract interfaces vs. default (in-memory) implementations.
- Call out external dependencies (e.g., replaceable queues, DBs, telemetry sinks).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% A2A Client Layer
    subgraph "A2A Client Layer"
        direction TB
        ClientAPI["Client API<br/>(client.py)"]:::client
        GRPCClient["gRPC Client<br/>(grpc_client.py)"]:::client
        ClientHelpers["Client Helpers<br/>(helpers.py)"]:::client
        ClientErrors["Client Errors<br/>(errors.py)"]:::client
    end

    %% Transport Layer
    subgraph "Transport Layers" 
        direction TB
        GRPCLayer["gRPC Transport<br/>(a2a_pb2*.py)"]:::transport
        JSONRPCApp["JSON-RPC App<br/>(jsonrpc_app.py)"]:::transport
        FastAPIApp["FastAPI Adapter<br/>(fastapi_app.py)"]:::transport
        StarletteApp["Starlette Adapter<br/>(starlette_app.py)"]:::transport
    end

    %% Server Framework Core
    subgraph "Server Framework Core"
        direction TB
        subgraph "Request Handlers"
            direction TB
            RequestHandler["RequestHandler<br/>(request_handler.py)"]:::core
            DefaultHandler["DefaultRequestHandler<br/>(default_request_handler.py)"]:::core
            GRPCHandler["gRPC Handler<br/>(grpc_handler.py)"]:::core
            JSONRPCHandler["JSON-RPC Handler<br/>(jsonrpc_handler.py)"]:::core
            ResponseHelpers["Response Helpers<br/>(response_helpers.py)"]:::core
        end
        subgraph "Agent Execution Engine"
            direction TB
            AgentExecutor["AgentExecutor<br/>(agent_executor.py)"]:::core
            Context["Context<br/>(context.py)"]:::core
            RequestContextBuilder["RequestContextBuilder<br/>(request_context_builder.py)"]:::core
            SimpleRequestContextBuilder["SimpleRequestContextBuilder<br/>(simple_request_context_builder.py)"]:::core
        end
        subgraph "Task Subsystem"
            direction TB
            TaskManager["TaskManager<br/>(task_manager.py)"]:::storage
            TaskStore["TaskStore<br/>(task_store.py)"]:::storage
            InMemoryTaskStore["InMemoryTaskStore<br/>(inmemory_task_store.py)"]:::storage
            ResultAggregator["ResultAggregator<br/>(result_aggregator.py)"]:::storage
            PushNotifier["PushNotifier<br/>(push_notifier.py)"]:::storage
            InMemoryPushNotifier["InMemoryPushNotifier<br/>(inmemory_push_notifier.py)"]:::storage
            TaskUpdater["TaskUpdater<br/>(task_updater.py)"]:::storage
        end
        subgraph "Event Subsystem"
            direction TB
            EventQueue["EventQueue<br/>(event_queue.py)"]:::storage
            QueueManager["QueueManager<br/>(queue_manager.py)"]:::storage
            InMemoryQueueManager["InMemoryQueueManager<br/>(in_memory_queue_manager.py)"]:::storage
            EventConsumer["EventConsumer<br/>(event_consumer.py)"]:::storage
        end
    end

    %% Shared Utilities
    subgraph "Shared Utilities"
        direction TB
        AuthUser["Auth User<br/>(user.py)"]:::util
        Artifact["Artifact Utils<br/>(artifact.py)"]:::util
        Telemetry["Telemetry<br/>(telemetry.py)"]:::util
        ProtoUtils["Proto Conversions<br/>(proto_utils.py)"]:::util
        UtilsHelpers["Common Helpers<br/>(helpers.py)"]:::util
        MessageUtil["Message Utils<br/>(message.py)"]:::util
        UtilsErrors["Utilities Errors<br/>(errors.py)"]:::util
        TaskUtil["Task Utils<br/>(task.py)"]:::util
    end

    %% Data Flow
    ClientAPI -->|"SubmitRequest"| GRPCLayer
    ClientAPI -->|"SubmitRequest"| JSONRPCApp
    GRPCClient -->|"Invoke"| GRPCLayer
    ClientHelpers --> ClientAPI
    ClientErrors --> ClientAPI

    GRPCLayer -->|"gRPC Call"| GRPCHandler
    JSONRPCApp -->|"HTTP Request"| JSONRPCHandler
    FastAPIApp --> JSONRPCApp
    StarletteApp --> JSONRPCApp

    GRPCHandler --> RequestContextBuilder
    JSONRPCHandler --> RequestContextBuilder
    DefaultHandler --> RequestContextBuilder
    ResponseHelpers --> DefaultHandler

    RequestContextBuilder --> AgentExecutor
    SimpleRequestContextBuilder --> AgentExecutor
    Context --> AgentExecutor

    AgentExecutor --> TaskManager
    AgentExecutor --> EventQueue

    TaskManager --> TaskStore
    TaskManager --> ResultAggregator
    TaskManager --> PushNotifier
    TaskManager --> TaskUpdater
    TaskStore --> InMemoryTaskStore
    PushNotifier --> InMemoryPushNotifier

    EventQueue --> QueueManager
    QueueManager --> InMemoryQueueManager
    EventQueue --> EventConsumer

    EventConsumer -->|"EventProcessed"| DefaultHandler
    ResultAggregator -->|"ResultsReady"| DefaultHandler
    PushNotifier -->|"PushResult"| ClientAPI
    DefaultHandler -->|"Response"| ClientAPI

    %% Click Events
    click ClientAPI "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/client/client.py"
    click GRPCClient "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/client/grpc_client.py"
    click ClientHelpers "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/client/helpers.py"
    click ClientErrors "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/client/errors.py"
    click GRPCLayer "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/grpc/a2a_pb2.py"
    click GRPCLayer "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/grpc/a2a_pb2_grpc.py"
    click JSONRPCApp "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/apps/jsonrpc/jsonrpc_app.py"
    click FastAPIApp "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/apps/jsonrpc/fastapi_app.py"
    click StarletteApp "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/apps/jsonrpc/starlette_app.py"
    click RequestHandler "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/request_handlers/request_handler.py"
    click DefaultHandler "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/request_handlers/default_request_handler.py"
    click GRPCHandler "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/request_handlers/grpc_handler.py"
    click JSONRPCHandler "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/request_handlers/jsonrpc_handler.py"
    click ResponseHelpers "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/request_handlers/response_helpers.py"
    click AgentExecutor "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/agent_execution/agent_executor.py"
    click Context "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/agent_execution/context.py"
    click RequestContextBuilder "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/agent_execution/request_context_builder.py"
    click SimpleRequestContextBuilder "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/agent_execution/simple_request_context_builder.py"
    click TaskManager "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/tasks/task_manager.py"
    click TaskStore "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/tasks/task_store.py"
    click PushNotifier "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/tasks/push_notifier.py"
    click ResultAggregator "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/tasks/result_aggregator.py"
    click TaskUpdater "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/tasks/task_updater.py"
    click InMemoryTaskStore "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/tasks/inmemory_task_store.py"
    click InMemoryPushNotifier "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/tasks/inmemory_push_notifier.py"
    click EventQueue "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/events/event_queue.py"
    click QueueManager "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/events/queue_manager.py"
    click InMemoryQueueManager "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/events/in_memory_queue_manager.py"
    click EventConsumer "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/server/events/event_consumer.py"
    click AuthUser "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/auth/user.py"
    click Artifact "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/utils/artifact.py"
    click Telemetry "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/utils/telemetry.py"
    click ProtoUtils "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/utils/proto_utils.py"
    click UtilsHelpers "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/utils/helpers.py"
    click MessageUtil "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/utils/message.py"
    click TaskUtil "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/utils/task.py"
    click UtilsErrors "https://github.com/google-a2a/a2a-python/blob/main/src/a2a/utils/errors.py"

    %% Styles
    classDef client fill:#D6EFFF,stroke:#333,stroke-width:1px
    classDef transport fill:#B3D1FF,stroke:#333,stroke-width:1px
    classDef core fill:#DBFFD6,stroke:#333,stroke-width:1px
    classDef storage fill:#FFE4B3,stroke:#333,stroke-width:1px
    classDef util fill:#E0E0E0,stroke:#333,stroke-width:1px
```
