# google/adk-docs architecture

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

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

## Overview

##### Project Type and Purpose
- The ADK repo is an open-source, code-first Python toolkit (library) for building, evaluating, and deploying AI agents.
- It provides core abstractions (Agents, Tools, Callbacks, Workflows, Sessions, Context, Streaming), model- and deployment-agnostic adapters, and documentation/examples.

##### High-Level Architectural Layers
a. Developer Layer
– Python application code (examples/, tutorials/, notebooks/)
– User-defined Agents, Tools, Custom callbacks
b. ADK Core Library Layer
– Core modules in the released package (`google_adk` namespace):
- Agents (llm_agents, custom_agents, workflow_agents)
- Tools (built_in, function_tools, openapi_tools, third_party)
- Callbacks (before/after model/tool/agent)
- Sessions & Context
- Streaming & Runtime
- Deployment connectors (Cloud Run, Vertex AI Agent Engine)
c. Model & Tool Adapters Layer
– LLM Providers (Gemini, OpenAI, Anthropic, etc.)
– Google-specific services (Search, Vertex AI, Cloud APIs)
– External APIs via OpenAPI specs or custom integration
d. Infrastructure & Services Layer
– Deployment targets (Cloud Run, GKE, Vertex AI Agent Engine)
– CI/CD pipelines (GitHub Actions: python-lint, python-tests, publish-docs)
– Documentation site build (mkdocs → site/)
– Artifact storage, monitoring, logging

##### Extract Key Components from the File Tree
- Top-level directories:
– docs/ → full Sphinx & MkDocs documentation, code examples
– examples/, notebooks/, tutorial code → demonstration of ADK usage
– .github/workflows/ → CI steps (lint, test, publish docs)
– mkdocs.yml + overrides/ + site/ → doc site generation pipeline
- README.md signals the core purpose & high-level features.

##### Relationships & Data Flows
- Developer writes Python code against the ADK Core Library → instantiates Agents and Tools → submits tasks.
- ADK Core orchestrates calls to LLM adapters and external Tools → streams responses back through Callback hooks.
- Multi-agent workflows compose Agents in parallel/sequential/loop patterns.
- Output may be logged, persisted in Session/Context stores, or forwarded to downstream services.
- At build/deploy time, CI workflows test the library and examples, then publish docs to GitHub Pages via mkdocs.

##### Architectural Patterns & Principles
- Modular design: clear separation of concerns (Agents vs. Tools vs. Callbacks vs. Deployments).
- Dependency injection / inversion: user code supplies tool definitions; library core orchestrates them.
- Extensibility points: custom agents, custom tools, custom callbacks.
- Pluggable adapters: interchangeable model and deployment backends.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Layer
    subgraph "Developer Layer"
        direction TB
        Examples["Examples & Tutorials"]:::user
        Notebooks["Notebooks"]:::user
        Tutorials["Quickstart & Tutorial Code"]:::user
    end

    %% ADK Core Library Layer
    subgraph "ADK Core Library"
        direction TB
        Agents["Agents Module"]:::core
        Tools["Tools Module"]:::core
        Callbacks["Callbacks Module"]:::core
        Runtime["Runtime (Sessions, Context, Streaming)"]:::core
        DeploymentConnectors["Deployment Connectors"]:::core
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        direction TB
        LLM["LLM Connectors"]:::adapter
        CloudAPIs["Google Cloud & External APIs"]:::adapter
    end

    %% Infrastructure & Services Layer
    subgraph "Infrastructure & Services"
        direction TB
        CloudRun["Cloud Run / GKE"]:::infra
        VertexAI["Vertex AI Agent Engine"]:::infra
    end

    %% CI/CD & Docs Pipeline
    subgraph "CI/CD & Docs Pipeline"
        direction TB
        CI["GitHub Actions (Lint & Test)"]:::pipeline
        DocsBuild["Docs Build & Publish"]:::pipeline
    end

    %% Connections
    Examples -->|"uses"| Agents
    Notebooks -->|"uses"| Agents
    Tutorials -->|"uses"| Agents

    Agents -->|"orchestrates"| Runtime
    Tools -->|"orchestrates"| Runtime
    Runtime -->|"invokes"| Callbacks

    Agents -->|"calls"| LLM
    LLM -->|"returns"| Agents

    Tools -->|"calls"| CloudAPIs
    CloudAPIs -->|"returns"| Tools

    DeploymentConnectors -->|"deploys to"| CloudRun
    DeploymentConnectors -->|"deploys to"| VertexAI

    CI -->|"runs"| DocsBuild

    %% Click Events
    click Examples "https://github.com/google/adk-docs/tree/main/examples/"
    click Notebooks "https://github.com/google/adk-docs/tree/main/examples/python/notebooks/"
    click Tutorials "https://github.com/google/adk-docs/tree/main/examples/python/tutorial/agent_team/adk-tutorial/"
    click Agents "https://github.com/google/adk-docs/tree/main/docs/agents/"
    click Tools "https://github.com/google/adk-docs/tree/main/docs/tools/"
    click Callbacks "https://github.com/google/adk-docs/tree/main/docs/callbacks/"
    click Runtime "https://github.com/google/adk-docs/tree/main/docs/runtime/"
    click DeploymentConnectors "https://github.com/google/adk-docs/tree/main/docs/deploy/"
    click CI "https://github.com/google/adk-docs/tree/main/.github/workflows/"
    click DocsBuild "https://github.com/google/adk-docs/blob/main/mkdocs.yml"

    %% Styles
    classDef user fill:#fff2cc,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef adapter fill:#d5f5e3,stroke:#333,stroke-width:1px
    classDef infra fill:#d0e6f7,stroke:#333,stroke-width:1px
    classDef pipeline fill:#efefef,stroke:#333,stroke-width:1px
```
