# google/adk-java architecture

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

- Interactive diagram: https://gitdiagram.com/google/adk-java
- Repository: https://github.com/google/adk-java

## Overview

##### Main components
- **Core Library (core module)**
- Agent abstractions (BaseAgent, LlmAgent, LoopAgent, etc.)
- Tool & plugin framework (BaseTool, PluginManager)
- Session, memory, artifact, event services
- LLM connectors (Gemini, OpenAI, Vertex)
- **A2A Integration (a2a + a2a/webservice modules)**
- `A2AClient`, converters, send/receive executor
- Remote Webservice (Spring Boot-style `A2ARemoteController` + `A2ARemoteService`)
- **Development UI (dev module + dev/browser assets)**
- Backend: `AdkWebServer`, controllers, WebSocket handler
- Frontend: static JS/CSS served to browser for live debugging
- **Maven Plugin (maven_plugin module)**
- `WebMojo`, `AgentLoader`, `ConfigAgentWatcher` for build-time code generation and hot-reload
- **Samples & Tutorials (contrib, tutorials modules)**
- Example agent code illustrating usage patterns – not part of the runtime product
- **External Services**
- Google Cloud (GCS for artifacts, Vertex AI for LLM & speech)
- Third-party LLM APIs (Gemini, OpenAI, Anthropic, Ollama)

##### Component interactions and data flows
- **Build‐time**: Developer invokes Maven; maven_plugin hooks generate support code → compiles into deployable JAR.
- **Runtime – Agent Execution**:
- Agent code ← linked against core library.
- Core invokes LLM connectors → external LLM APIs.
- Core persists/retrieves state via in-memory or GCS artifact & session services.
- Agents call tools → may invoke code executors or external HTTP services.
- **Runtime – A2A**: Local agent ↔ remote agent communication via A2AClient ↔ A2ARemoteController over HTTP.
- **Runtime – Dev UI**: Browser UI ↔ AdkWebServer REST/WebSocket endpoints ↔ live agent instance for stepping, inspection, telemetry.

##### Architectural patterns
- **Modular Multi-module Maven Project**: Clear separation of library, protocol, plugin, server, and samples.
- **Builder & Strategy Patterns**: Agent.builder(), pluggable ToolResolver, SessionService strategy.
- **Plugin Architecture**: `PluginManager` loads runtime plugins (e.g., telemetry, replay).
- **MVC/WebSocket for Dev UI**: Controllers (REST + WS) serve static assets + live agent hooks.
- **Protocol Layer**: A2A converters abstract message/part/event translation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build-time flow
    subgraph "Build-time"
        MAVEN["Maven Invoke"]:::build
        PLUGIN["Maven Plugin<br/>(WebMojo, AgentLoader)"]:::plugin
        JAR["Generated Agent JAR"]:::artifact
    end
    MAVEN -->|"executes"| PLUGIN
    PLUGIN -->|"produces"| JAR

    %% Core Library Module
    subgraph "Core Library (core module)" 
        CORE_AGENTS["Agents<br/>(BaseAgent, LlmAgent, LoopAgent)"]:::core
        CORE_TOOLS["Tools & Plugins<br/>(BaseTool, PluginManager)"]:::core
        CORE_SERVICES["Services<br/>(Sessions, Memory, Artifacts, Events)"]:::core
        CORE_MODELS["LLM Connectors<br/>(Gemini, OpenAI, Vertex)"]:::core
    end

    %% A2A Integration
    subgraph "A2A Integration (a2a modules)"
        A2A_CLIENT["A2AClient & Executors"]:::a2a
        A2A_CONV["Converters"]:::a2a
        A2A_REMOTE["Remote Webservice<br/>(Controller, Service)"]:::a2a
    end

    %% Development UI
    subgraph "Development UI (dev module)"
        DEV_SERVER["AdkWebServer & Controllers"]:::ui
        DEV_WS["WebSocket Handler"]:::ui
        DEV_FRONTEND["Browser Frontend Assets"]:::ui
    end

    %% Samples & Tutorials
    subgraph "Samples & Tutorials"
        SAMPLES["Contrib & Tutorials"]:::samples
    end

    %% External Services
    subgraph "External Services"
        LLM_APIS["Third-party LLM APIs<br/>(Gemini, OpenAI, Anthropic, Ollama)"]:::external
        GCS["Google Cloud Storage"]:::external
        VERTEX["Vertex AI & Speech"]:::external
    end

    %% Runtime flows
    JAR -->|"includes Core"| CORE_AGENTS
    CORE_AGENTS -->|"calls"| CORE_MODELS
    CORE_MODELS -->|"uses API"| LLM_APIS
    CORE_SERVICES -->|"stores state"| GCS
    CORE_SERVICES -->|"executes sessions"| VERTEX
    CORE_AGENTS -->|"invokes tools"| CORE_TOOLS
    CORE_TOOLS -->|"calls external"| LLM_APIS
    CORE_AGENTS -->|"exposes endpoints"| DEV_SERVER
    DEV_SERVER -->|"WS comms"| DEV_WS
    DEV_WS -->|"live debugging"| DEV_FRONTEND
    CORE_AGENTS -->|"A2A messages"| A2A_CLIENT
    A2A_CLIENT -->|"HTTP"| A2A_REMOTE

    %% Click Events - Core Module
    click CORE_AGENTS "https://github.com/google/adk-java/tree/main/core/src/main/java/com/google/adk/agents"
    click CORE_TOOLS "https://github.com/google/adk-java/tree/main/core/src/main/java/com/google/adk/tools"
    click CORE_TOOLS "https://github.com/google/adk-java/tree/main/core/src/main/java/com/google/adk/plugins"
    click CORE_SERVICES "https://github.com/google/adk-java/tree/main/core/src/main/java/com/google/adk/sessions"
    click CORE_SERVICES "https://github.com/google/adk-java/tree/main/core/src/main/java/com/google/adk/memory"
    click CORE_SERVICES "https://github.com/google/adk-java/tree/main/core/src/main/java/com/google/adk/artifacts"
    click CORE_SERVICES "https://github.com/google/adk-java/tree/main/core/src/main/java/com/google/adk/events"
    click CORE_MODELS "https://github.com/google/adk-java/tree/main/core/src/main/java/com/google/adk/models"
    click CORE_MODELS "https://github.com/google/adk-java/blob/main/core/src/main/java/com/google/adk/models/GeminiLlmConnection.java"

    %% Click Events - A2A Integration
    click A2A_CLIENT "https://github.com/google/adk-java/blob/main/a2a/src/main/java/com/google/adk/a2a/A2AClient.java"
    click A2A_CLIENT "https://github.com/google/adk-java/blob/main/a2a/src/main/java/com/google/adk/a2a/A2ASendMessageExecutor.java"
    click A2A_CONV "https://github.com/google/adk-java/tree/main/a2a/src/main/java/com/google/adk/a2a/converters"
    click A2A_REMOTE "https://github.com/google/adk-java/blob/main/a2a/webservice/src/main/java/com/google/adk/webservice/A2ARemoteController.java"
    click A2A_REMOTE "https://github.com/google/adk-java/blob/main/a2a/webservice/src/main/java/com/google/adk/webservice/A2ARemoteService.java"

    %% Click Events - Development UI
    click DEV_SERVER "https://github.com/google/adk-java/blob/main/dev/src/main/java/com/google/adk/web/AdkWebServer.java"
    click DEV_SERVER "https://github.com/google/adk-java/tree/main/dev/src/main/java/com/google/adk/web/controller"
    click DEV_WS "https://github.com/google/adk-java/blob/main/dev/src/main/java/com/google/adk/web/websocket/LiveWebSocketHandler.java"
    click DEV_FRONTEND "https://github.com/google/adk-java/blob/main/dev/browser/index.html"
    click DEV_FRONTEND "https://github.com/google/adk-java/tree/main/dev/browser/assets"

    %% Click Events - Maven Plugin
    click PLUGIN "https://github.com/google/adk-java/blob/main/maven_plugin/src/main/java/com/google/adk/maven/WebMojo.java"
    click PLUGIN "https://github.com/google/adk-java/blob/main/maven_plugin/src/main/java/com/google/adk/maven/AgentLoader.java"
    click PLUGIN "https://github.com/google/adk-java/blob/main/maven_plugin/src/main/java/com/google/adk/maven/ConfigAgentWatcher.java"
    click PLUGIN "https://github.com/google/adk-java/blob/main/maven_plugin/src/main/java/com/google/adk/maven/ConfigAgentLoader.java"

    %% Click Events - Samples & Tutorials
    click SAMPLES "https://github.com/google/adk-java/tree/main/contrib/samples"
    click SAMPLES "https://github.com/google/adk-java/blob/main/contrib/langchain4j/src/main/java/com/google/adk/models/langchain4j/LangChain4j.java"
    click SAMPLES "https://github.com/google/adk-java/blob/main/contrib/spring-ai/src/main/java/com/google/adk/models/springai/SpringAI.java"
    click SAMPLES "https://github.com/google/adk-java/tree/main/tutorials"

    %% Click Events - External Services
    click GCS "https://github.com/google/adk-java/blob/main/core/src/main/java/com/google/adk/artifacts/GcsArtifactService.java"
    click VERTEX "https://github.com/google/adk-java/blob/main/core/src/main/java/com/google/adk/codeexecutors/VertexAiCodeExecutor.java"
    click VERTEX "https://github.com/google/adk-java/blob/main/core/src/main/java/com/google/adk/sessions/VertexAiSessionService.java"
    click VERTEX "https://github.com/google/adk-java/blob/main/core/src/main/java/com/google/adk/flows/llmflows/audio/VertexSpeechClient.java"

    %% Styles
    classDef build fill:#ffebcd,stroke:#d2691e,stroke-width:2px
    classDef plugin fill:#ffe4e1,stroke:#ff7f50,stroke-width:2px
    classDef artifact fill:#fafad2,stroke:#bdb76b,stroke-width:2px
    classDef core fill:#e0ffff,stroke:#20b2aa,stroke-width:2px
    classDef a2a fill:#f0f8ff,stroke:#4682b4,stroke-width:2px
    classDef ui fill:#fff0f5,stroke:#db7093,stroke-width:2px
    classDef samples fill:#f5f5dc,stroke:#a0522d,stroke-width:2px
    classDef external fill:#f0fff0,stroke:#32cd32,stroke-width:2px
```
