How google/adk-samples works
以下说明面向负责绘制系统设计图的高级工程师,结合本项目的结构和目标,指导如何准确地将 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 的通用模式。