用 ADK 构建最小化 AI Agentagent-starter-pack ADK 模板源码级实战指南【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack本文围绕 agent-starter-pack 仓库中的adk模板agent_starter_pack/agents/adk/README.md展开深入拆解一个基于 Google Agent Development KitADK的最小化 ReAct Agent 的完整实现从工具定义、Agent 组装到集成测试、评估与云端部署。读完本文你将掌握 ADK 的核心概念Agent、Tool、Runner、Session、App并能在本地运行、测试和评估一个生产级结构的 ADK 应用。模板定位一个麻雀虽小、五脏俱全的 ADK 示例在 docs/agents/overview.md 的模板清单中adk被定义为基于 Google Agent Development Kit 的基础 ReAct Agent适用于通用对话型 Agent 场景是学习 ADK 框架与 ReAct 模式、上手 Google Cloud Agent 开发的首选起点。该模板的核心技术要点来自模板 README.md基于Google Agent Development KitADK构建演示 Agent 创建与工具集成两大核心概念使用gemini-3-flash-preview模型作为推理引擎内置两个演示工具get_weather模拟天气查询对旧金山硬编码返回结果get_current_time模拟时间查询对旧金山硬编码返回结果。整个模板刻意保持最小化minimal让开发者可以聚焦于 ADK 的核心抽象再基于此扩展成自己的业务 Agent。模板文件结构adk模板的完整目录结构如下agent_starter_pack/agents/adk/ ├── README.md # 模板说明本文所依托的文档 ├── app/ │ ├── __init__.py # 导出 app 对象 │ └── agent.py # Agent 与工具的核心实现 ├── notebooks/ │ ├── adk_app_testing.ipynb # 应用测试手册Agent Engine / Cloud Run │ └── evaluating_adk_agent.ipynb # 使用 Vertex AI Gen AI Evaluation 评估 Agent └── tests/ ├── eval/ │ ├── eval_config.json # 评分标准与判题模型配置 │ └── evalsets/ │ ├── README.md # evalset 格式说明 │ └── basic.evalset.json # 基础评估用例集 └── integration/ └── test_agent.py # Runner Session 流式集成测试其中app/agent.py是整个模板的灵魂其余文件围绕它提供测试、评估与部署验证。核心实现拆解app/agent.pyapp/agent.py 以 Jinja2 模板形式存在生成 agent 时由 cookiecutter 渲染我们逐段解析。依赖与环境适配import datetime from zoneinfo import ZoneInfo from google.adk.agents import Agent from google.adk.apps import App from google.adk.models import Gemini from google.genai import types模板同时支持两种认证方式由模板变量use_google_api_key控制agent.py{%- if not cookiecutter.use_google_api_key %} import os import google.auth _, project_id google.auth.default() os.environ[GOOGLE_CLOUD_PROJECT] project_id os.environ[GOOGLE_CLOUD_LOCATION] global os.environ[GOOGLE_GENAI_USE_VERTEXAI] True {%- endif %}当不使用 API Key 时模板自动通过google.auth.default()读取应用默认凭证获取当前 GCP 项目 ID并设置三个关键环境变量GOOGLE_CLOUD_PROJECT项目 ID、GOOGLE_CLOUD_LOCATION区域此处设为global、GOOGLE_GENAI_USE_VERTEXAI切换到底层走 Vertex AI 而非 Gemini API。这意味着生成后的 Agent 可以直接借助 Vertex AI 运行gemini-3-flash-preview模型。工具一get_weatherdef get_weather(query: str) - str: Simulates a web search. Use it get information on weather. Args: query: A string containing the location to get weather information for. Returns: A string with the simulated weather information for the queried location. if sf in query.lower() or san francisco in query.lower(): return Its 60 degrees and foggy. return Its 90 degrees and sunny.get_weather 接收一个位置字符串通过关键词匹配sf/san francisco返回旧金山的模拟天气其他位置则统一返回90 度晴朗。它演示了 ADK 工具的最基本形态普通 Python 函数 类型注解 docstring。ADK 会自动把 docstring 和签名转换为模型可感知的 function schema这也是为什么注释里会刻意写明参数含义与返回值。工具二get_current_timedef get_current_time(query: str) - str: Simulates getting the current time for a city. ... if sf in query.lower() or san francisco in query.lower(): tz_identifier America/Los_Angeles else: return fSorry, I dont have timezone information for query: {query}. tz ZoneInfo(tz_identifier) now datetime.datetime.now(tz) return fThe current time for query {query} is {now.strftime(%Y-%m-%d %H:%M:%S %Z%z)}get_current_time 则更进一步使用了标准库zoneinfo.ZoneInfo与datetime实现真实的时区换算识别到旧金山时使用America/Los_Angeles时区并返回带时区偏移%Z%z的当前时间未知城市则给出礼貌的拒绝回复。相比硬编码字符串这个工具示范了如何让模拟工具返回看起来真实的动态数据。Agent 组装root_agentroot_agent Agent( nameroot_agent, modelGemini( modelgemini-3-flash-preview, retry_optionstypes.HttpRetryOptions(attempts3), ), instructionYou are a helpful AI assistant designed to provide accurate and useful information., tools[get_weather, get_current_time], )Agent 定义 展示了几项关键配置nameAgent 唯一标识root_agentmodel通过 ADK 的Gemini包装类指定gemini-3-flash-preview并通过HttpRetryOptions(attempts3)配置了 HTTP 层最多重试 3 次提升弱网环境下的稳定性instruction系统提示词定义 Agent 的角色与行为准则乐于助人、提供准确有用信息的 AI 助手tools注册两个工具函数模型在推理时会自主判断是否需要调用以及传入什么参数。这正是 ReActReasoning Acting模式在 ADK 中的最小落地模型先生成推理再决定调用哪个工具最后基于工具结果生成回复。App 封装与可选的可观测性插件app App( root_agentroot_agent, name{{cookiecutter.agent_directory}}, {%- if cookiecutter.bq_analytics %} plugins_plugins, {%- endif %} )App 是 ADK 的应用级入口将root_agent包装为可被 Runner / 服务化部署消费的应用对象name取自模板变量agent_directory。当模板变量bq_analytics为真时agent.py 还会自动初始化 BigQuery Agent Analytics 插件读取GOOGLE_CLOUD_PROJECT、BQ_ANALYTICS_DATASET_ID默认adk_agent_analytics、GOOGLE_CLOUD_REGION默认us-east1等环境变量创建 BigQuery 数据集并挂载BigQueryAgentAnalyticsPlugin与BigQueryLoggerConfig含可选的 GCS bucket 与 connection_id将 Agent 运行日志写入 BigQuery 以便后续分析。初始化失败时只记录 warning 而不阻断应用启动体现了模板的容错设计。模板变量小结从 agent.py 的 Jinja2 语法可以归纳出该模板由 cookiecutter 注入的变量变量作用影响位置use_google_api_key是否使用 Gemini API Key 认证决定是否走 Vertex AI 环境变量初始化bq_analytics是否启用 BigQuery Agent Analytics 插件决定是否创建数据集并挂载插件agent_directory生成后的 Agent 目录名 / App 名称App 的name与包结构用 Runner Session 验证 Agent集成测试解析app/init.py 仅做一件事from .agent import app并导出供测试与服务化入口复用。模板自带的集成测试 tests/integration/test_agent.py 完整演示了 ADK 的运行时三大件session_service InMemorySessionService() session session_service.create_session_sync(user_idtest_user, app_nametest) runner Runner(agentroot_agent, session_servicesession_service, app_nametest) message types.Content( roleuser, parts[types.Part.from_text(textWhy is the sky blue?)] ) events list( runner.run( new_messagemessage, user_idtest_user, session_idsession.id, run_configRunConfig(streaming_modeStreamingMode.SSE), ) ) assert len(events) 0, Expected at least one message测试用例 test_agent_stream 的调用链清晰展示了 ADK 运行模型SessionService用InMemorySessionService创建内存会话生产环境可替换为持久化实现以user_idapp_name标识会话归属Runner将root_agent与会话服务绑定作为执行入口run以StreamingMode.SSE流式模式运行逐条产出Event断言校验至少产出一条事件、且事件中包含文本内容part.text。这不仅是测试更是一份如何以编程方式驱动 ADK Agent的样板代码可用于本地调试、自动化回归与评估数据采集。评估从 adk eval 到 Vertex AI Gen AI Evaluation基于 evalset 的本地评估tests/eval/evalsets/README.md 说明了用 ADK 自带评估模块adk eval运行评估的方式# 运行默认 evalset make eval # 运行指定的 evalset make eval EVALSETtests/eval/evalsets/custom.evalset.json # 运行全部 evalsets make eval-all生成后的 Agent 目录会包含对应的 Makefile仓库 tests/fixtures/makefile_snapshots 中保存了这些 Makefile 的渲染快照。评估用例集 basic.evalset.json 给出了最小样例{ eval_set_id: basic_eval, name: Basic Agent Evaluation, eval_cases: [ { eval_id: greeting, conversation: [ { user_content: { parts: [{text: Hello, what can you help me with?}] } } ], session_input: { app_name: app, user_id: eval_user, state: {} } }, { eval_id: weather_query, conversation: [ { user_content: { parts: [{text: Whats the weather like in San Francisco?}] } } ], session_input: { app_name: app, user_id: eval_user, state: {} } } ] }关键字段语义来自 evalsets/README.mdeval_cases测试场景数组conversation用户消息序列intermediate_data.tool_uses期望的工具调用轨迹用于轨迹匹配格式为{name: tool_name, args: {...}}session_input初始会话状态。ADK eval 会产出两类核心指标tool_trajectory_avg_score工具是否被按正确顺序调用response_match_score回复与期望输出的相似度。评分标准由 eval_config.json 定义它配置了一个基于 rubric 的最终回复质量判题器rubric_based_final_response_quality_v1threshold为 0.8由gemini-3-flash-preview作为 judge 模型numSamples: 1并按两条 rubric 打分relevance回复是否直接回应用户问题与helpfulness回复是否有用、信息充分。使用 Vertex AI Gen AI Evaluation 做深度评估模板还附带 evaluating_adk_agent.ipynb演示用 Vertex AI Gen AI Evaluation 服务评估 ADK Agent覆盖四个层次单工具使用评估TrajectorySingleToolUse验证 Agent 是否在过程中使用过期望的工具例如TrajectorySingleToolUse(tool_nameget_product_price)轨迹评估基于 ground truth 的五个指标——trajectory_exact_match轨迹完全一致动作与顺序均相同trajectory_in_order_match参考动作按顺序出现在预测轨迹中允许多余动作trajectory_any_order_match参考动作全部出现顺序与多余动作不影响trajectory_precision预测动作中属于参考的比例trajectory_recall参考动作中被预测覆盖的比例其中 precision / recall 取值 0~1其余四个指标为 0 或 1响应评估使用safety、coherence等模型内置指标评估最终回复质量自定义指标通过PointwiseMetricPromptTemplate定义 criteria 与评分 rubric构建PointwiseMetric如response_follows_trajectory判断回复是否逻辑上承接了工具调用轨迹——这是文本质量指标无法覆盖的 Agent 特有维度。Notebook 还演示了Bring-Your-Own-DatasetBYOD场景当数据集已包含reference_trajectory、predicted_trajectory与response列时可直接以该数据集运行EvalTask无需在线跑 Agent。评估结果通过EvalTask.evaluate写入 Vertex AI Experiment并可用 bar / radar 图可视化。从本地到云端应用测试手册adk_app_testing.ipynb 覆盖两种部署目标Agent Engine 与 Cloud Run下的本地 / 远程测试Agent Engine 远程测试通过vertexai.Client获取已部署的 agent engine资源 ID 可从deployment_metadata.json自动读取用async_stream_query流式对话并支持register_feedback回传用户评分score / text / user_id / session_idAgent Engine 本地测试直接导入agent_engine_app中的agent_engine对象set_up()后在本地以流式方式 queryCloud Run 远程测试先通过gcloud auth print-identity-token获取身份令牌再以POST {SERVICE_URL}/apps/{app}/users/{user_id}/sessions创建会话、POST {SERVICE_URL}/run_sse发送流式消息并解析data:事件Cloud Run 本地测试运行make local-backend起本地服务默认127.0.0.1:8000随后以同样的 HTTP 流程建会话、发消息。值得注意的是本地 Agent Engine 测试要求使用make install创建的.venv作为 Notebook kernel以保证依赖一致——这也是模板生态中 uv / Makefile 工作流的一部分。基于模板扩展你的 Agent该模板定位为起点而非终点docs/agents/overview.md 建议的自定义路径是选定模板创建实例 → 熟悉代码结构agent 逻辑、工具定义、UI 组件→ 修改提示词、增删工具、接入数据源、调整推理逻辑。对本模板而言最小改造通常包括在app/agent.py中新增自己的工具函数保持类型注解 docstring约定ADK 会自动生成 schema将工具加入root_agent的tools列表按 basic.evalset.json 的格式补充评估用例覆盖每个核心能力的 happy path 与边界场景建议从 3~5 个代表性用例起步在生成 Agent 时通过 cookiecutter 变量控制认证方式与是否启用 BigQuery 可观测性。结语agent-starter-pack 的adk模板用不足百行的核心代码串联起 ADK 的全部关键抽象工具函数、Agent 组装、App 封装、Runner Session 运行时、evalset 评估与双部署目标测试。它既是 ADK 初学者的最小可运行示例也是生产级 Agent 工程化CI/CD、评估、可观测性的起点——你可以在此基础上把两个模拟工具替换为真实的业务 API把basic_eval扩展成覆盖全能力的评估集把内存会话换成持久化存储逐步演进出属于你自己的生产级 Agent。【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考