# kolinatasha/adk-python architecture

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

- Interactive diagram: https://gitdiagram.com/kolinatasha/adk-python
- Repository: https://github.com/kolinatasha/adk-python

## Overview

##### Project Type and Purpose
- This is a full-featured, open-source Python framework (a library + CLI + dev UI) called “Agent Development Kit (ADK).”
- Purpose: provide a code-first toolkit for building, orchestrating, evaluating, and deploying AI agents, with pluggable tools, multi-agent flows, state/memory, authentication, execution backends, evaluation, and CI/CD support.

##### High-Level Architectural Layers
- Core Library (src/google/adk)
- Command-Line Interface & Dev UI (src/google/adk/cli + browser assets)
- External Integrations (tools → BigQuery, Vertex AI, OpenAPI, A2A protocol, GCS, OAuth)
- Execution Backends (built-in, container, unsafe local, Vertex AI code executors)
- State Management (memory services, session services, artifact services)
- Evaluation Subsystem (eval sets, metrics, LLM-as-judge)
- Plugins & Extensions (plugin manager, logging plugin, base plugin)
- Tests & Samples (tests/integration, tests/unittests, contributing/samples)

##### Main Components & Relationships
- Agents:
- Represented by classes under agents/ (LlmAgent, SequentialAgent, ParallelAgent, A2AAgent, etc.)
- Use InvocationContext, CallbackContext, AgentConfig, run_config.
- Flows:
- LLM flows (planning, code execution, instructions, auto_flow) orchestrate agent steps.
- Tools:
- A set of toolsets (bigquery, application_integration_tool, openapi_tool, retrieval, etc.)
- Agents invoke tools to perform external operations.
- Models:
- BaseLLMConnection, gemini_llm, google_llm, lite_llm, anthropic_llm, etc.
- Agents delegate requests to model connections.
- Authentication:
- Auth credential services (in-memory, session_state, exchangers, refreshers).
- CredentialManager, AuthHandler, AuthPreprocessor.
- Execution Backends:
- Code executors implementing BaseCodeExecutor (container, built-in, vertex_ai, unsafe_local).
- Flows invoke code execution via executor registry.
- State & Artifacts:
- Memory services (in_memory, vertex_ai_rag, memory bank).
- Session services (database, in_memory, vertex_ai).
- Artifact services (GCS, in_memory).
- Evaluation:
- EvalService, EvalSetsManager, metrics, trajectory evaluator, safety evaluator.
- GCS-backed or in-memory eval result stores.
- CLI & Dev UI:
- CLI commands (adk create, deploy, eval) use click-based cli.py / cli_tools_click.
- FastAPI web server (adk_web_server) with static React/JS frontend assets for interactive UI.
- Integrations:
- Agent2Agent (A2A) protocol for remote agent calls.
- External services: BigQuery, Vertex AI, GCS, secret stores, OpenAPI specs.
- Plugins:
- PluginManager loads plugins (logging, custom) to hook into agent lifecycle.

##### Architectural Patterns & Design Principles
- Modular packages: each concern (agents, flows, tools, auth, state, evaluation) isolated in its own package.
- Dependency Injection / Registry patterns: executors, credential exchangers, evaluators registered via registries.
- Strategy pattern: pluggable code executors, memory services, session services.
- Layered architecture:
1) Presentation: CLI & Dev UI
2) Application/Core: Agents, Flows, Tools
3) Infrastructure: Executors, Auth services, Memory/Session/Artifact services, Evaluation backends
4) External systems

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        CLI_UI["CLI & Dev UI"]:::presentation
        CLI["CLI Core"]:::presentation
        BrowserAssets["Browser Assets"]:::presentation
    end

    %% Core Library
    subgraph "Core ADK Library"
        direction TB
        Agents["Agents"]:::core
        Flows["Flows (LLM Orchestration)"]:::core
        Tools["Tools & Integrations"]:::core
        Models["Models & LLM Connections"]:::core
        Plugins["Plugins & Extensions"]:::core
        A2A["Agent-to-Agent Protocol"]:::core
    end

    %% Infrastructure Services
    subgraph "Infrastructure Services"
        direction TB
        ExecutorRegistry["Code Executor Registry"]:::infrastructure
        AuthRegistry["Auth Service Registry"]:::infrastructure
        MemoryRegistry["Memory Service Registry"]:::infrastructure
        SessionRegistry["Session Service Registry"]:::infrastructure
        ArtifactRegistry["Artifact Service Registry"]:::infrastructure
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        VertexAI["Vertex AI / Gemini"]:::external
        BigQuery["BigQuery"]:::external
        GCS["GCS"]:::external
        OAuth2["OAuth2 Providers"]:::external
        A2AEndpoints["A2A Protocol Endpoints"]:::external
        OpenAPI["OpenAPI-defined APIs"]:::external
    end

    %% Evaluation Subsystem
    subgraph "Evaluation Subsystem"
        direction TB
        EvalManager["Eval Sets Manager"]:::evaluation
        MetricEvaluator["Metric Evaluator"]:::evaluation
        JudgeLLM["Judge LLM"]:::evaluation
        ResultsStore["Results Store (GCS/In-Memory)"]:::evaluation
    end

    %% Testing & Samples
    subgraph "Tests & Samples"
        direction TB
        Examples["Examples & Samples"]:::testing
        IntegrationTests["Integration Tests"]:::testing
        UnitTests["Unit Tests"]:::testing
    end

    %% Connections
    CLI_UI -->|"invoke APIs"| Agents
    CLI_UI -->|"invoke flows"| Flows
    CLI_UI -->|"trigger evaluation"| EvalManager

    Agents ---|uses| Flows
    Agents -->|"invoke tool"| Tools
    Tools -->|"call service"| BigQuery
    Tools -->|"call service"| GCS
    Tools -->|"call service"| OpenAPI

    Agents -->|"delegate to model"| Models
    Models -->|"call endpoint"| VertexAI
    Models -->|"call endpoint"| OpenAPI

    Flows -->|"lookup executor"| ExecutorRegistry
    ExecutorRegistry -->|"execute code"| VertexAI
    ExecutorRegistry -->|"execute code"| CLI_UI

    Agents -->|"authenticate via"| AuthRegistry
    AuthRegistry -->|"use credentials"| OAuth2

    Agents -->|"store memory"| MemoryRegistry
    MemoryRegistry -->|"persist"| GCS
    Agents -->|"store session"| SessionRegistry
    SessionRegistry -->|"persist"| GCS
    Agents -->|"store artifact"| ArtifactRegistry
    ArtifactRegistry -->|"persist"| GCS

    EvalManager -->|"evaluate metrics"| MetricEvaluator
    MetricEvaluator -->|"use judge"| JudgeLLM
    JudgeLLM -->|"store results"| ResultsStore

    A2A -->|"communicate via"| A2AEndpoints
    CLI --> CLI_UI
    BrowserAssets --> CLI_UI

    Examples --> Agents
    IntegrationTests --> Agents
    UnitTests --> Agents

    %% Click Events
    click CLI_UI "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/cli/"
    click CLI "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/cli/"
    click BrowserAssets "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/cli/browser/assets/"
    click Agents "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/agents/"
    click Flows "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/flows/llm_flows/"
    click Tools "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/tools/"
    click Models "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/models/"
    click AuthRegistry "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/auth/"
    click AuthRegistry "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/auth/credential_service/"
    click AuthRegistry "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/auth/exchanger/"
    click AuthRegistry "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/auth/refresher/"
    click ExecutorRegistry "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/code_executors/"
    click MemoryRegistry "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/memory/"
    click SessionRegistry "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/sessions/"
    click ArtifactRegistry "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/artifacts/"
    click EvalManager "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/evaluation/"
    click Plugins "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/plugins/"
    click A2A "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/a2a/"
    click Examples "https://github.com/kolinatasha/adk-python/tree/main/src/google/adk/examples/"
    click Examples "https://github.com/kolinatasha/adk-python/tree/main/contributing/samples/"
    click IntegrationTests "https://github.com/kolinatasha/adk-python/tree/main/tests/integration/"
    click UnitTests "https://github.com/kolinatasha/adk-python/tree/main/tests/unittests/"

    %% Styles
    classDef presentation fill:#CCCCCC,stroke:#000,stroke-width:1px
    classDef core fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef infrastructure fill:#D8F8D8,stroke:#000,stroke-width:1px
    classDef external fill:#FFE4B5,stroke:#000,stroke-width:1px
    classDef evaluation fill:#FFF8B5,stroke:#000,stroke-width:1px
    classDef testing fill:#E8E8E8,stroke:#000,stroke-width:1px
```
