# avkus/agent-development-kit-crash-course architecture

> Architecture diagram of the GitHub repository avkus/agent-development-kit-crash-course, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/avkus/agent-development-kit-crash-course
- Repository: https://github.com/avkus/agent-development-kit-crash-course

## Overview

##### Project Type and Purpose
- This is not a single application but a **learning toolkit**: a set of 12 hands-on examples demonstrating how to build LLM-powered agents with Google’s ADK.
- Each example folder (1-basic-agent through 12-loop-agent) encapsulates a different architectural pattern or feature set (simple response, tools, state, multi-agent orchestration, etc.).

##### File Structure
- Top-level:
– README.md, requirements.txt, GEMINI_MODELS.md
– 12 example directories, each with its own README and a module directory containing agent.py, .env.example, and sometimes subagent packages or utility scripts.
- Patterns:
– **Single-Agent** (folders 1–4): a lone agent.py demonstrating core ADK usage.
– **Stateful** (5–6): session management, persistent store (e.g., utils.py, memory_agent).
– **Multi-Agent** (7–8): a root “manager” agent orchestrating specialized subagents.
– **Callbacks** (9): injection points before/after tool or model calls.
– **Sequential / Parallel / Loop** (10–12): pipeline chaining, concurrent subagent execution, iterative refinement loops.

##### Extract Insights from the README
- The README confirms each folder is a self-contained example illustrating a specific ADK feature.
- Dependencies: Python, virtualenv, Google Cloud API (GOOGLE_API_KEY), the ADK library itself, Pydantic for structured outputs, LiteLLM for model abstraction, plus optional tools and storage modules.

##### Main Components
a. **Developer Environment**
– Virtual environment with Python & ADK libraries
– .env file storing `GOOGLE_API_KEY`
b. **ADK Core Framework**
– Agent base classes, session & state management APIs, callback hooks, tool registration mechanisms
c. **Example Agent Modules (1–12)**
– Each folder is a “plug-in” that instantiates one or more Agent classes
– Subcomponents:
- *Subagents* (in multi-agent, parallel, loop examples)
- *Tools* (in tool agent, callback examples)
- *Storage layer* (persistent-storage example)
- *Schemas* (structured-outputs example)
d. **External Services**
– Google AI Platform via ADK (models, embeddings)
– Optional custom tool endpoints or local storage (filesystem or database)

##### Relationships & Interactions
– Agents invoke ADK framework APIs → ADK framework calls Google AI services
– In multi-agent cases, the manager agent delegates tasks to subagents (sequentially, in parallel, or in a loop)
– Callback examples intercept model or tool calls before/after execution
– Stateful examples read/write session data or persistent storage between turns

##### Architectural Patterns & Design Principles
– **Plug-in Modularity**: each example folder is self-contained, illustrating a single pattern
– **Orchestration vs. Delegation**: manager agents vs. standalone/simple agents
– **Concurrency**: parallel example uses asynchronous/subprocess calls to gather metrics
– **Pipelines & Loops**: sequential chaining vs. iterative refinement
– **Separation of Concerns**: clear boundaries between agent logic, tool wrappers, state managers, and external service clients

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Developer Environment"
        Req["requirements.txt"]:::core
        Git[".gitignore"]:::core
        Gem["GEMINI_MODELS.md"]:::core
    end
    Req --> ADKCore
    Git --> ADKCore
    Gem --> ADKCore

    ADKCore["ADK Core Framework"]:::core

    subgraph "Example Agents"
        Ex1["1. Basic Agent"]:::example
        Ex2["2. Tool Agent"]:::example
        Ex3["3. LiteLLM Agent"]:::example
        Ex4["4. Structured Outputs Agent"]:::example
        Ex5["5. Stateful Session Agent"]:::example
        Ex6["6. Persistent Storage Agent"]:::storage
        Ex7["7. Multi-Agent Orchestration"]:::example
        Ex8["8. Stateful Multi-Agent"]:::example
        Ex9["9. Callbacks"]:::example
        Ex10["10. Sequential Pipeline Agent"]:::example
        Ex11["11. Parallel Execution Agent"]:::example
        Ex12["12. Loop / Iterative Refinement Agent"]:::example
    end

    ADKCore --> Ex1
    ADKCore --> Ex2
    ADKCore --> Ex3
    ADKCore --> Ex4
    ADKCore --> Ex5
    ADKCore --> Ex6
    ADKCore --> Ex7
    ADKCore --> Ex8
    ADKCore --> Ex9
    ADKCore --> Ex10
    ADKCore --> Ex11
    ADKCore --> Ex12

    click Req "https://github.com/avkus/agent-development-kit-crash-course/blob/main/requirements.txt"
    click Git "https://github.com/avkus/agent-development-kit-crash-course/blob/main/.gitignore"
    click Gem "https://github.com/avkus/agent-development-kit-crash-course/blob/main/GEMINI_MODELS.md"
    click Ex1 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/1-basic-agent/greeting_agent/agent.py"
    click Ex2 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/2-tool-agent/tool_agent/agent.py"
    click Ex3 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/3-litellm-agent/dad_joke_agent/agent.py"
    click Ex4 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/4-structured-outputs/email_agent/agent.py"
    click Ex5 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/5-sessions-and-state/question_answering_agent/agent.py"
    click Ex6 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/6-persistent-storage/main.py"
    click Ex7 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/7-multi-agent/manager/agent.py"
    click Ex8 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/8-stateful-multi-agent/main.py"
    click Ex9 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/9-callbacks/before_after_agent/agent.py"
    click Ex10 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/10-sequential-agent/lead_qualification_agent/agent.py"
    click Ex11 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/11-parallel-agent/system_monitor_agent/agent.py"
    click Ex12 "https://github.com/avkus/agent-development-kit-crash-course/blob/main/12-loop-agent/linkedin_post_agent/agent.py"

    classDef core fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef example fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef storage fill:#FFF9C4,stroke:#F57F17,color:#F57F17;
```
