# astrodevil/adk-agent-examples architecture

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

- Interactive diagram: https://gitdiagram.com/astrodevil/adk-agent-examples
- Repository: https://github.com/astrodevil/adk-agent-examples

## Overview

##### Project Type and Purpose
- This is a collection of AI agent demos built on Google’s ADK (Agent Development Kit).
- It showcases five agents (Analyzer, Email, Sequential, Multi-Tool Search, Job Finder), each demonstrating ADK patterns like sequential pipelines, tool integration, and delegation.

##### File Structure
- Top level contains:
- 5 agent directories (`analyzer_agent`, `email_adk_agent`, `seq_adk_agent`, `multi_tool_search_agent`, `jobfinder_agent`)
- A shared `requirements.txt`, CLI entrypoints via `adk` commands, and environment setup files.
- Each agent folder contains:
- `.env.example` for API keys
- `agent.py` (or notebook in Job Finder) defining the ADK agent or pipeline
- `README.md` with agent-specific details
- No frontend code—interaction happens via ADK CLI, Dev UI (`adk web`), or FastAPI server (`adk api_server`).

##### README for Insights
- All agents use LiteLLM to integrate open-source LLMs (Meta-Llama, Nemotron Ultra, Qwen).
- External services (Nebius AI for inference, Exa/Tavily for search, Firecrawl for scraping, Resend for email, Mistral for OCR, Linkup for jobs) appear as tools.
- Patterns: sequential chaining, tool integration, agent delegation, multi-model approach, specialized agents.

a. Main Components
- User Interfaces:
- CLI (terminal)
- Dev UI (`adk web`)
- API Server (FastAPI via `adk api_server`)
- ADK Core/Orchestrator (central runtime)
- Agent Modules (5 separate pipelines):
- Analyzer Agent (5-step pipeline)
- Email Agent (single agent + Resend API tool)
- Sequential Agent (3-step pipeline)
- Multi-Tool Search Agent (root agent + delegated sub-agents)
- Job Finder Agent (4-step pipeline in notebook)
- LLM Integration Layer (LiteLLM)
- LLM Providers (Nebius AI endpoints for Meta-Llama, Nemotron Ultra; Qwen3-14B)
- External Tool Services: Exa, Tavily, Firecrawl, Resend, Mistral, Linkup

b. Relationships and Interactions
- Users → ADK CLI/UI/API → ADK Core
- ADK Core loads a selected agent module
- Within each agent:
- Sequential agents pass output from one sub-agent to the next
- Root agent delegates tasks to specialized sub-agents
- Agents invoke LiteLLM to call appropriate LLM provider
- Agents call external REST APIs (tools) to augment LLM results
- Final output returns via CLI, Dev UI, or API response

c. Architectural Patterns
- Sequential Pipelines: chain of agents (Analyzer, Sequential, Job Finder)
- Tool Integration: agents embed external API calls as “tools” (Email, Search, OCR)
- Agent Delegation: Multi-Tool Search agent delegates to sub-agents
- Multi-Model Approach: choose LLM per task
- Specialized Agents: each folder is a plug-and-play agent demo

d. Technologies/Frameworks
- Python, Google ADK (core runtime)
- LiteLLM for LLM connectivity
- FastAPI (via `adk api_server`)
- Various external RESTful services

##### Detail
- Agent’s internal flow if space allows (e.g., 5 sequential steps in Analyzer)
- Shared dependencies (requirements.txt, `.env` configs) as side notes
- Multi-model selection logic in LLM layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    CLI(["User CLI"]):::interface
    DevUI(["Dev UI<br/>(adk web)"]):::interface
    APIServer(["API Server<br/>(adk api_server)"]):::interface

    %% Orchestrator
    ADKCore(["ADK Core<br/>(Orchestrator)"]):::core

    %% Agent Modules
    subgraph "Agent Modules"
        direction TB
        AnalyzerAgent(["Analyzer Agent"]):::agent
        EmailAgent(["Email Agent"]):::agent
        SequentialAgent(["Sequential Agent"]):::agent
        MultiToolAgent(["Multi-Tool Search Agent"]):::agent
        JobFinderAgent(["Job Finder Agent"]):::agent
    end

    %% LLM Integration Layer
    LiteLLM(["LiteLLM<br/>(LLM Integration)"]):::llm

    %% LLM Providers
    subgraph "LLM Providers"
        direction TB
        NebiusAI(["Nebius AI<br/>(Meta-Llama, Nemotron)"]):::external
        Qwen(["Qwen3-14B"]):::external
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        Exa(["Exa Search"]):::external
        Tavily(["Tavily Search"]):::external
        Firecrawl(["Firecrawl Scraper"]):::external
        Resend(["Resend Email"]):::external
        Mistral(["Mistral OCR"]):::external
        Linkup(["Linkup Jobs"]):::external
    end

    %% Documentation & Configs
    README(["README.md"]):::doc
    Requirements(["requirements.txt"]):::doc

    %% Connections
    CLI -->|select agent| ADKCore
    DevUI -->|select agent| ADKCore
    APIServer -->|select agent| ADKCore

    ADKCore -->|"load module"| AnalyzerAgent
    ADKCore -->|"load module"| EmailAgent
    ADKCore -->|"load module"| SequentialAgent
    ADKCore -->|"load module"| MultiToolAgent
    ADKCore -->|"load module"| JobFinderAgent

    %% Agents to LLM
    AnalyzerAgent -->|"invoke LLM"| LiteLLM
    EmailAgent -->|"invoke LLM"| LiteLLM
    SequentialAgent -->|"invoke LLM"| LiteLLM
    MultiToolAgent -->|"invoke LLM"| LiteLLM
    JobFinderAgent -->|"invoke LLM"| LiteLLM

    %% LLM to Providers
    LiteLLM -->|calls| NebiusAI
    LiteLLM -->|calls| Qwen

    %% Agents to Tools
    EmailAgent -->|uses| Resend
    AnalyzerAgent -->|uses| Exa
    AnalyzerAgent -->|uses| Tavily
    AnalyzerAgent -->|uses| Firecrawl
    SequentialAgent -->|uses| Mistral
    MultiToolAgent -->|delegates to sub-agents| Exa
    MultiToolAgent -->|delegates to sub-agents| Tavily
    MultiToolAgent -->|delegates to sub-agents| Firecrawl
    MultiToolAgent -->|delegates to sub-agents| Resend
    JobFinderAgent -->|uses| Linkup

    %% Documentation & Configs connections
    ADKCore --> Requirements
    ADKCore --> README

    %% Click Events
    click AnalyzerAgent "https://github.com/astrodevil/adk-agent-examples/blob/main/analyzer_agent/agent.py"
    click EmailAgent "https://github.com/astrodevil/adk-agent-examples/blob/main/email_adk_agent/agent.py"
    click SequentialAgent "https://github.com/astrodevil/adk-agent-examples/blob/main/seq_adk_agent/agent.py"
    click MultiToolAgent "https://github.com/astrodevil/adk-agent-examples/blob/main/multi_tool_search_agent/agent.py"
    click JobFinderAgent "https://github.com/astrodevil/adk-agent-examples/blob/main/jobfinder_agent/JobFinder_Agent.ipynb"
    click Requirements "https://github.com/astrodevil/adk-agent-examples/blob/main/requirements.txt"
    click README "https://github.com/astrodevil/adk-agent-examples/blob/main/README.md"

    %% Styles
    classDef interface fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef agent fill:#D8BFD8,stroke:#333,stroke-width:1px;
    classDef llm fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef external fill:#FFFFE0,stroke:#333,stroke-width:1px;
    classDef doc fill:#F0F8FF,stroke:#333,stroke-width:1px;
```
