# google/adk-samples architecture

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

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

## Overview

以下说明面向负责绘制系统设计图的高级工程师，结合本项目的结构和目标，指导如何准确地将 ADK Samples 仓库的架构可视化。全程以中文呈现。

##### 项目类型与目的
- 本仓库为 Google Agent Development Kit (ADK) 的示例集合，包含基于 Java 和 Python 的多种示例 Agent（“软件缺陷辅助”、“时间序列预测”、学术研究、品牌搜索优化、客服、数据科学、金融顾问、FOMC 研究、LLM 审计、营销代理、个性化购物、旅行礼宾等）。
- 主要目的是展示 ADK 在不同应用场景下的模块化设计、部署和评估流程，帮助开发者快速上手。

##### 文件结构分析
- 顶层分为两大语言目录：java/agents 和 python/agents，各自包含若干子目录，每个子目录对应一个示例 Agent。
- 每个示例 Agent 下通常包含这些模块：
- core agent 代码（agent.py 或 Java 的 SoftwareBugAssistant.java/ForecastingAgent）
- prompts 配置（prompts.py、prompt.py）
- sub_agents 子模块（多 Agent 协作的子流程，如 academic_research/sub_agents）
- shared_libraries 或 tools（公用工具、BigQuery 连接器、文件工具等）
- deployment（部署脚本、Dockerfile、Grant 权限脚本等）
- eval（评估脚本与测试数据）
- tests（单元测试、示例对话等）
- 构建与配置文件：Java 使用 pom.xml，Python 使用 pyproject.toml；部分示例提供 Dockerfile。

##### 系统设计图主要组件
a. 根级别：Monorepo
- 分支到 Java 示例集与 Python 示例集
b. 语言分支下的各个 Agent 微服务
- 每个 Agent 作为独立微服务/模块，展示自身的模块分层
c. Agent 微服务内部
- Agent 核心（接收外部请求，协调子 Agent）
- Sub-agents（分工子流，如数据检索、分析、执行等）
- Prompts 配置（构造 LLM 输入）
- Tools/Shared Libraries（外部服务调用，如 BigQuery、文件读写、HTTP 接口）
d. 辅助模块
- Deployment（CI/CD 或容器化部署流程）
- Evaluation（自动化评估管道，测试数据与报告）
e. 外部依赖
- LLM 服务 API（ChatGPT、Vertex AI 等）
- 数据服务（BigQuery、存储桶、HTTP 接口）
- 容器化平台（Docker、Kubernetes 等，可选）

##### 组件间关系与数据流
- 外部 Client/脚本（deploy.py/run.py/test_eval.py）触发 → Agent 核心入口
- Agent 核心 → Prompts 生成 → 向 LLM 服务发起请求
- LLM 响应 → Agent 核心或 Sub-agents 处理结果
- Sub-agents 如需外部数据调用，调用 Tools/Shared Libraries → 数据服务
- 最终结果反馈给 Client 或写入评估报告

##### 架构模式与设计原则
- 微服务化：每个示例 Agent 独立部署与评估
- 模块化：核心逻辑、提示工程、子 Agent、工具库严格分层
- 可扩展性：通过 shared_libraries 或 sub_agents 插件式扩展功能
- CI/CD 一体化：部署与评估脚本与代码仓库紧耦合

##### 绘制图示建议
- 层次分明：自上而下展示 Monorepo → 语言分支 → 单个 Agent 模块
- 组件与子组件用不同形状区分：
- 矩形：代码模块（Core Agent、Sub-agents、Tools）
- 圆角矩形：部署/评估脚本
- 圆形或云图标：外部服务（LLM API、BigQuery）
- 颜色编码：
- Java 示例：蓝色系
- Python 示例：绿色系
- 公共模块（Deployment/Eval）：灰色系
- 箭头加注方向与数据类型：
- 实线箭头：控制流/调用
- 虚线箭头：异步或事件驱动
- 箭头旁标注协议或格式（HTTP/gRPC、JSON、Prompt）
- 标注关键技术栈：
- “Java ADK SDK” 或 “Python ADK SDK”
- Docker、pom.xml、pyproject.toml
- BigQuery Connector、Custom Tools

##### 专门针对本项目的定制化提示
- 在根视图突出“java/agents” 与 “python/agents” 目录结构。
- 对每个示例 Agent，可选展示其代表性子模块（如 brand-search-optimization 的 BQ data setup、personalized-shopping 的 Web Agent Site）。
- 在部署层面，标示 Dockerfile 与 deploy.py/run.py/grant_permissions.sh 等脚本如何与容器平台或 GCP 交互。
- 在评估层面，标示 test_eval.py、eval/data/*.json 测试流程，展示自动化评估管道。

总结：通过上述分层结构与模块化组件，结合清晰的标签、箭头与配色，即可绘制一份既全面又针对本 ADK Samples 仓库的精准系统设计图，帮助团队快速理解整体架构与示例 Agent 的通用模式。

## Diagram (Mermaid)

```mermaid
flowchart TD
    Monorepo["Monorepo"]:::common
    Monorepo --> JavaBranch["java/agents"]:::java
    Monorepo --> PythonBranch["python/agents"]:::python

    subgraph "Java Agents"
        direction TB
        SBA["Software Bug Assistant"]:::java
        Forecast["Time Series Forecasting"]:::java
    end
    JavaBranch --> SBA
    JavaBranch --> Forecast

    subgraph "Software Bug Assistant 微服务"
        direction TB
        SBA_Core["Core Agent"]:::java
        SBA_Deployment["Deployment"]:::common
    end
    SBA --> SBA_Core
    SBA --> SBA_Deployment
    click SBA_Core "https://github.com/google/adk-samples/blob/main/java/agents/software-bug-assistant/software-bug-assistant/src/main/java/SoftwareBugAssistant.java"
    click SBA_Deployment "https://github.com/google/adk-samples/tree/main/java/agents/software-bug-assistant/deployment"

    subgraph "Time Series Forecasting 微服务"
        direction TB
        Forecast_Core["Core Agent"]:::java
        Forecast_Deployment["Dockerfile & Deployment"]:::common
    end
    Forecast --> Forecast_Core
    Forecast --> Forecast_Deployment
    click Forecast_Core "https://github.com/google/adk-samples/blob/main/java/agents/time-series-forecasting/src/main/java/com/google/adk/samples/agents/timeseriesforecasting/ForecastingAgent.java"
    click Forecast_Deployment "https://github.com/google/adk-samples/tree/main/java/agents/time-series-forecasting/Dockerfile"

    subgraph "Python Agents"
        direction TB
        RAG["RAG"]:::python
        AR["Academic Research"]:::python
    end
    PythonBranch --> RAG
    PythonBranch --> AR

    subgraph "RAG 微服务"
        direction TB
        RAG_Core["Core Agent"]:::python
        RAG_Prompts["Prompts"]:::python
        RAG_Sub["Sub-agents"]:::python
        RAG_Tools["Shared Libraries"]:::python
        RAG_Deployment["Deployment"]:::common
        RAG_Eval["Evaluation"]:::common
        RAG_Tests["Tests"]:::common
    end
    RAG --> RAG_Core
    RAG --> RAG_Prompts
    RAG --> RAG_Sub
    RAG --> RAG_Tools
    RAG --> RAG_Deployment
    RAG --> RAG_Eval
    RAG --> RAG_Tests
    click RAG_Core "https://github.com/google/adk-samples/blob/main/python/agents/RAG/rag/agent.py"
    click RAG_Prompts "https://github.com/google/adk-samples/blob/main/python/agents/RAG/rag/prompts.py"
    click RAG_Tools "https://github.com/google/adk-samples/blob/main/python/agents/RAG/rag/shared_libraries/prepare_corpus_and_data.py"
    click RAG_Deployment "https://github.com/google/adk-samples/blob/main/python/agents/RAG/deployment/deploy.py"
    click RAG_Eval "https://github.com/google/adk-samples/blob/main/python/agents/RAG/eval/test_eval.py"
    click RAG_Tests "https://github.com/google/adk-samples/tree/main/python/agents/RAG/tests"

    subgraph "Academic Research 微服务"
        direction TB
        AR_Core["Core Agent"]:::python
        AR_Prompts["Prompts"]:::python
        AR_Sub["Sub-agents"]:::python
        AR_Deployment["Deployment"]:::common
        AR_Eval["Evaluation"]:::common
        AR_Tests["Tests"]:::common
    end
    AR --> AR_Core
    AR --> AR_Prompts
    AR --> AR_Sub
    AR --> AR_Deployment
    AR --> AR_Eval
    AR --> AR_Tests
    click AR_Core "https://github.com/google/adk-samples/blob/main/python/agents/academic-research/academic_research/agent.py"
    click AR_Prompts "https://github.com/google/adk-samples/blob/main/python/agents/academic-research/academic_research/prompt.py"
    click AR_Sub "https://github.com/google/adk-samples/tree/main/python/agents/academic-research/academic_research/sub_agents"
    click AR_Deployment "https://github.com/google/adk-samples/blob/main/python/agents/academic-research/deployment/deploy.py"
    click AR_Eval "https://github.com/google/adk-samples/blob/main/python/agents/academic-research/eval/test_eval.py"
    click AR_Tests "https://github.com/google/adk-samples/tree/main/python/agents/academic-research/tests"

    classDef java fill:#cce5ff,stroke:#339,stroke-width:1px
    classDef python fill:#d4edda,stroke:#295,stroke-width:1px
    classDef common fill:#f8f9fa,stroke:#666,stroke-width:1px
```
