# google/adk-go architecture

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

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

## Overview

##### Project Type and Purpose
- This is a full-stack, code-first Go toolkit (Agent Development Kit, ADK) designed to build, orchestrate, evaluate, and deploy AI agents.
- The repository combines:
- A core Go library (packages under `agent/`, `artifact/`, `model/`, `tool/`, `session/`, `telemetry/`, `internal/…`)
- CLI deployment tooling (`cmd/adkgo`, `cmd/launcher/…`)
- A REST/HTTP server exposing agent APIs (`server/adka2a`, `server/restapi`)
- Example apps demonstrating usage (`examples/…`).

##### High-Level File-Structure Analysis
- Top-Level Components:
- `agent/`, `artifact/`, `model/`, `tool/`: Core domain logic for agents, artifacts, LLM models, and tools.
- `internal/…`: Implementation details (e.g., LLM integration, converters, memory, session internals, HTTP-RR test harness).
- `cmd/`: Two sets of CLIs – the primary `adkgo` (for building/deploying agents) and `launcher` (various runtime entry points: console, web UI, prod, universal).
- `server/`: Two HTTP surfaces – `adka2a` (agent-to-agent orchestration) and `restapi` (CRUD and runtime endpoints for sessions, artifacts, eval).
- `session/`: Session management backends (in-memory, GORM-based database, Vertex AI).
- `examples/`: Sample programs illustrating agent use-cases (A2A, quickstart, workflow agents, web).
- Supporting packages: `memory/`, `runner/`, `util/`, plus CI configs and licensing.

##### README Insights
- The README emphasizes:
- “Modular multi-agent systems”
- “Rich tool ecosystem”
- Model-agnostic (optimized for Gemini but pluggable)
- Deploy anywhere (e.g., Google Cloud Run)

a. Main Components
1. ADK Core Library (grouped into logical subcomponents):
– Agent Engine (`agent/`, `agent/llmagent/`, `agent/workflowagents/`)
– Tool Framework (`tool/`, `internal/toolinternal/`)
– Artifact Service (`artifact/`, `internal/artifact/`)
– Model Abstraction (`model/`, `internal/llminternal/`)
– Session & State Management (`session/`, `internal/sessioninternal/`, `internal/telemetry/`)
– Memory Store (`internal/memory/`)
2. Deployment Surfaces:
– CLI (`cmd/adkgo`, `cmd/launcher/*`)
– REST API Server (`server/adka2a`, `server/restapi/`)
3. External Dependencies:
– LLM Providers (Gemini, Vertex AI, other OpenAI-style endpoints)
– Artifact Storage (GCS via `artifact/gcs/`)
– Session Store (Relational DB via GORM in `session/database/`)
– Cloud Platform (e.g., Google Cloud Run)
4. Supporting Services:
– Logging & Telemetry pipeline
– HTTP-RR test harness

b. Relationships & Data Flows
- CLIs and REST endpoints invoke the Agent Engine in ADK Core.
- The Agent Engine coordinates:
- LLM calls via `model/` and `internal/llminternal/` to external services.
- Tool invocation via `tool/` interfaces.
- Artifact storage & retrieval via `artifact/`.
- Session read/write via `session/` backends.
- Memory operations via `internal/memory/`.
- Agent workflows (sequential, parallel, looping) orchestrate multi-step logic.
- Results, logs, and metrics feed into the telemetry pipeline.

c. Architectural Patterns & Principles
- Package-level modularity, interface abstractions for pluggable LLMs, tools, storage.
- Test-driven structure with HTTP-RR for integration verification.
- Separation of concerns: core library vs. CLIs vs. servers vs. examples.
- Workflow agents implement common orchestration patterns.
- Cloud-native deployment via containerizable CLIs or REST servers.

d. Key Technologies & Frameworks
- Go / Go modules
- GORM (for relational session store)
- HTTP REST (via standard `net/http`)
- Google Cloud Run & GCS clients
- Gemini API / Vertex AI SDK

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interfaces Layer
    subgraph "Interfaces"
        direction TB
        CLI_ADK["CLI: adkgo"]:::interface
        CLI_Launcher["CLI: launcher"]:::interface
        REST_A2A["REST API: A2A Orchestration"]:::interface
        REST_REST["REST API: CRUD & Runtime"]:::interface
    end

    %% Core Library Layer
    subgraph "Core Library"
        direction TB
        AgentEngine["Agent Engine"]:::core
        LLMAgent["LLM Agent"]:::core
        WorkflowAgents["Workflow Agents"]:::core
        RemoteA2AAgent["Remote A2A Agent"]:::core
        ToolFramework["Tool Framework"]:::core
        InternalTool["Tool Internal"]:::core
        ArtifactService["Artifact Service"]:::core
        GCSStorage["Artifact GCS Storage"]:::core
        ModelAbstraction["Model Abstraction"]:::core
        Gemini["Gemini Adapter"]:::core
        LLMInternal["LLM Internals"]:::core
        SessionMgmt["Session Management"]:::core
        SessionDB["Session DB Store"]:::core
        SessionInternal["Session Internals"]:::core
        MemoryStore["Memory Store"]:::core
        Telemetry["Telemetry"]:::core
    end

    %% Examples Sidebar
    Examples["Example Apps"]:::interface

    %% External Systems Layer
    subgraph "External Systems"
        direction TB
        LLMProviders["LLM Providers"]:::external
        RelDB["Relational DB Store"]:::external
        GCS["Google Cloud Storage"]:::external
        CloudRun["Cloud Run"]:::external
        TelemetryPipeline["Logging/Telemetry Pipeline"]:::external
    end

    %% Relationships: Interfaces to Core
    CLI_ADK -->|invokes| AgentEngine
    CLI_Launcher -->|invokes| AgentEngine
    REST_A2A -->|calls| AgentEngine
    REST_REST -->|calls| AgentEngine

    %% Core internal connections
    AgentEngine -->|uses| LLMAgent
    AgentEngine -->|orchestrates| WorkflowAgents
    AgentEngine -->|orchestrates| RemoteA2AAgent
    AgentEngine -->|invokes| ToolFramework
    ToolFramework -->|implements| InternalTool
    AgentEngine -->|stores/retrieves| ArtifactService
    ArtifactService -->|stores in| GCSStorage
    AgentEngine -->|abstracts| ModelAbstraction
    ModelAbstraction -->|adapts| Gemini
    ModelAbstraction -->|integrates| LLMInternal
    AgentEngine -->|manages| SessionMgmt
    SessionMgmt -->|persists to| SessionDB
    SessionMgmt -->|internal logic| SessionInternal
    AgentEngine -->|reads/writes| MemoryStore
    AgentEngine -->|emits| Telemetry
    Telemetry -->|streams to| TelemetryPipeline

    %% Core to External
    LLMAgent -->|LLM call| LLMProviders
    GCSStorage -->|backed by| GCS
    SessionDB -->|backed by| RelDB
    CLI_ADK -->|deployed on| CloudRun

    %% Examples relation
    Examples -.->|demonstrates| AgentEngine

    %% Click Events
    click CLI_ADK "https://github.com/google/adk-go/blob/main/cmd/adkgo/adkgo.go"
    click CLI_Launcher "https://github.com/google/adk-go/tree/main/cmd/launcher/"
    click REST_A2A "https://github.com/google/adk-go/tree/main/server/adka2a/"
    click REST_REST "https://github.com/google/adk-go/tree/main/server/restapi/"
    click AgentEngine "https://github.com/google/adk-go/tree/main/agent/"
    click LLMAgent "https://github.com/google/adk-go/blob/main/agent/llmagent/llmagent.go"
    click WorkflowAgents "https://github.com/google/adk-go/tree/main/agent/workflowagents/"
    click RemoteA2AAgent "https://github.com/google/adk-go/blob/main/agent/remoteagent/a2a_agent.go"
    click ToolFramework "https://github.com/google/adk-go/tree/main/tool/"
    click InternalTool "https://github.com/google/adk-go/tree/main/internal/toolinternal/"
    click ArtifactService "https://github.com/google/adk-go/blob/main/artifact/service.go"
    click GCSStorage "https://github.com/google/adk-go/tree/main/artifact/gcs/"
    click ModelAbstraction "https://github.com/google/adk-go/blob/main/model/llm.go"
    click Gemini "https://github.com/google/adk-go/tree/main/model/gemini/"
    click LLMInternal "https://github.com/google/adk-go/tree/main/internal/llminternal/"
    click SessionMgmt "https://github.com/google/adk-go/blob/main/session/service.go"
    click SessionDB "https://github.com/google/adk-go/tree/main/session/database/"
    click SessionInternal "https://github.com/google/adk-go/tree/main/internal/sessioninternal/"
    click MemoryStore "https://github.com/google/adk-go/blob/main/internal/memory/memory.go"
    click Telemetry "https://github.com/google/adk-go/blob/main/internal/telemetry/telemetry.go"
    click Examples "https://github.com/google/adk-go/tree/main/examples/"

    %% Styles
    classDef interface fill:#AED6F1,stroke:#21618C,color:#1B4F72
    classDef core      fill:#A9DFBF,stroke:#196F3D,color:#145A32
    classDef external  fill:#F9E79F,stroke:#B7950B,color:#7D6608
```
