# google-a2a/a2a-js architecture

> Architecture diagram of the GitHub repository google-a2a/a2a-js, 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-js
- Repository: https://github.com/google-a2a/a2a-js

## Overview

##### Project Type & Purpose
- It’s a TypeScript SDK for building and interacting with “agentic” applications (A2A Servers).
- Provides:
- A2A Server framework (Express-based, JSON-RPC endpoints, SSE streaming)
- A2A Client library (JSON-RPC over HTTP, SSE support)

A. SDK Consumer (Your Application)
- Imports A2AClient or A2AExpressApp & related types.
B. A2A Client Module (src/client)
- Class: A2AClient
- Handles JSON-RPC calls (`sendMessage`, `getTask`, `cancelTask`)
- Supports standard responses & Server-Sent Events streams.
C. Transport Layer (Client ↔ Server)
- HTTP / JSON-RPC 2.0
- SSE channel for streaming events.
D. A2A Server Module (src/server & index)
1. Entry: A2AExpressApp
- Wraps an Express app and mounts JSON-RPC endpoints (`POST /`, `GET /stream`) and agent metadata route (`/.well-known/agent.json`).
2. JSONRPC Transport Handler (jsonrpc_transport_handler.ts)
- Parses JSON-RPC requests, invokes Request Handlers, serializes responses or SSE streams.
3. Request Handler Layer (default_request_handler.ts & a2a_request_handler.ts)
- DefaultRequestHandler implements `handleSendMessage`, `handleCancelTask`, delegates to AgentExecutor.
4. Agent Execution Subsystem (agent_execution/*.ts)
- Interfaces: AgentExecutor, RequestContext, TaskStore
- AgentExecutor.execute / cancelTask
- Reads RequestContext, interacts with TaskStore (InMemoryTaskStore), publishes events.
5. Event Bus & Queues (events/*.ts)
- ExecutionEventBus: publishes Task, StatusUpdate, ArtifactUpdate events.
- ExecutionEventQueue: buffers events per task.
- ExecutionEventBusManager: manages per-task buses & finishing.
6. Persistence (store.ts & InMemoryTaskStore)
- Stores the latest Task state & history.
7. Result Management (result_manager.ts)
- (Optional) Aggregates final responses.
8. Utilities (utils.ts, error.ts)

##### Relationships & Data Flow
1. SDK Consumer → A2AClient.sendMessage()
2. A2AClient → HTTP POST → A2A Server JSONRPC endpoint
3. JSONRPC Transport → DefaultRequestHandler.handleSendMessage()
4. Handler → AgentExecutor.execute(RequestContext, EventBus)
5. AgentExecutor → ExecutionEventBus.publish(...) → EventQueue
6. Transport layer reads from EventQueue → streams via SSE back to client
7. Client receives streamed events → delivers to SDK Consumer

For non-streaming calls, block until final event, then HTTP response with aggregated result.

##### Architectural Patterns & Principles
- Modular layering: Transport → Handler → Executor → Store → Event Bus
- Pluggable Executor interface for custom agent logic
- Event-driven execution with publish/subscribe
- JSON-RPC standard + SSE streaming for real-time updates
- In-memory or pluggable TaskStore for stateful tasks

##### Diagramming Details
- Use clear labels for each component (e.g., “A2AExpressApp”, “DefaultRequestHandler”).
- Orange for extension/plugin interfaces (AgentExecutor)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% SDK Consumer and Client
    subgraph "SDK Consumer & Client"
        direction TB
        SDKConsumer["SDK Consumer App"]:::core
        A2AClient["A2AClient"]:::core
    end

    SDKConsumer -->|"import & call sendMessage()"| A2AClient
    click SDKConsumer "https://github.com/google-a2a/a2a-js/blob/main/src/index.ts"
    click A2AClient "https://github.com/google-a2a/a2a-js/blob/main/src/client/client.ts"

    %% Transport Layer (Client → Server)
    A2AClient -->|"HTTP POST / JSON-RPC\nSSE subscribe"| JSONRPCTransportHandler

    class JSONRPCTransportHandler transport
    click JSONRPCTransportHandler "https://github.com/google-a2a/a2a-js/blob/main/src/server/transports/jsonrpc_transport_handler.ts"

    %% Server Application Entry
    A2AExpressApp["A2AExpressApp\n(Express Wrapper)"]:::core
    click A2AExpressApp "https://github.com/google-a2a/a2a-js/blob/main/src/server/a2a_express_app.ts"

    JSONRPCTransportHandler -->|"for POST / & GET /stream"| A2AExpressApp

    %% Server Handler & Execution Layers
    subgraph "Server Core Modules"
        direction TB
        DefaultRequestHandler["DefaultRequestHandler"]:::core
        A2ARequestHandler["A2ARequestHandler\n(interface)"]:::interface
        AgentExecutor["AgentExecutor & RequestContext"]:::interface
        TaskStore["TaskStore\n(store.ts)"]:::optional
        EventBus["ExecutionEventBus"]:::core
        EventQueue["ExecutionEventQueue"]:::core
        EventBusMgr["ExecutionEventBusManager"]:::core
        ResultManager["ResultManager"]:::optional
        Utils["Utils & Error"]:::optional
    end

    A2AExpressApp -->|"delegate to transport handler"| JSONRPCTransportHandler
    JSONRPCTransportHandler -->|"invoke methods"| DefaultRequestHandler
    DefaultRequestHandler -->|"implements A2ARequestHandler"| A2ARequestHandler
    DefaultRequestHandler -->|"handleSendMessage()/cancelTask()"| AgentExecutor
    click DefaultRequestHandler "https://github.com/google-a2a/a2a-js/blob/main/src/server/request_handler/default_request_handler.ts"
    click A2ARequestHandler "https://github.com/google-a2a/a2a-js/blob/main/src/server/request_handler/a2a_request_handler.ts"
    click AgentExecutor "https://github.com/google-a2a/a2a-js/blob/main/src/server/agent_execution/agent_executor.ts"
    click AgentExecutor "https://github.com/google-a2a/a2a-js/blob/main/src/server/agent_execution/request_context.ts"

    AgentExecutor -->|"execute()/cancelTask()"| TaskStore
    click TaskStore "https://github.com/google-a2a/a2a-js/blob/main/src/server/store.ts"
    AgentExecutor -->|"publish events"| EventBus
    click EventBus "https://github.com/google-a2a/a2a-js/blob/main/src/server/events/execution_event_bus.ts"
    EventBus --> EventQueue
    click EventQueue "https://github.com/google-a2a/a2a-js/blob/main/src/server/events/execution_event_queue.ts"
    EventBusMgr --> EventBus
    click EventBusMgr "https://github.com/google-a2a/a2a-js/blob/main/src/server/events/execution_event_bus_manager.ts"
    click ResultManager "https://github.com/google-a2a/a2a-js/blob/main/src/server/result_manager.ts"
    click Utils "https://github.com/google-a2a/a2a-js/blob/main/src/server/utils.ts"
    click Utils "https://github.com/google-a2a/a2a-js/blob/main/src/server/error.ts"

    %% Response Streaming
    EventQueue -->|"SSE stream"| A2AClient
    A2AClient -->|"deliver events to SDK Consumer"| SDKConsumer

    %% Shared Types
    Types["Shared Types & Responses"]:::optional
    click Types "https://github.com/google-a2a/a2a-js/blob/main/src/types.ts"
    click Types "https://github.com/google-a2a/a2a-js/blob/main/src/a2a_response.ts"

    %% Styles
    classDef transport fill:#cfe2f3,stroke:#0b5394,color:#0b5394;
    classDef core fill:#d9ead3,stroke:#38761d,color:#38761d;
    classDef interface fill:#fce5cd,stroke:#f79646,color:#e69138;
    classDef optional fill:#eeeeee,stroke:#999999,color:#555555,stroke-dasharray: 5 5;
    class SDKConsumer,Types core
    class A2AClient,DefaultRequestHandler,EventBus,EventQueue,EventBusMgr core
    class A2ARequestHandler,AgentExecutor interface
    class TaskStore,ResultManager,Utils optional
```
