尧图网站建设 
agent-starter-pack Java 基础模板深度解析用 ADK 在 Google Cloud 上构建、测试与部署 Java AI 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本指南以 agent-starter-pack 仓库中的 Java 基础模板agent_starter_pack/base_templates/java/README.md为核心结合模板内的 Maven 配置、Makefile、Agent 实现与测试源码系统讲解如何基于 Google Agent Development KitADK搭建一个 Java 语言编写的 AI Agent 项目。读完本文你将掌握该模板的完整目录结构、依赖与构建机制、本地 Playground 调试方法、单元 / E2E / 负载测试体系以及部署到 Cloud Run / GKE 并注册到 Gemini Enterprise 的完整链路。模板定位生成 Java Agent 项目的标准骨架agent-starter-pack为不同语言提供了统一的基础模板base templatesJava 模板位于 agent_starter_pack/base_templates/java/目录结构与 Go、Python、TypeScript 模板平行。它是 Cookiecutter 风格的可渲染模板——文件中的{{cookiecutter.project_name}}、{{cookiecutter.java_package}}等占位符会在通过agent-starter-pack create命令生成项目时被替换为实际值最终产出一个开箱即用的 Java ADK Agent 工程。模板的定位可以从两个维度理解占位实现Placeholder模板自带的Agent.java只是一个待覆盖的桩实现真正的 Agent 逻辑由adk_java等具体 Agent 模板agent_starter_pack/agents/adk_java/在生成时覆盖进去工程化能力完整无论 Agent 业务如何替换构建Maven、测试单元 / 集成 / 负载、代码质量Checkstyle、部署Terraform CI/CD等工程设施都是现成的。项目结构总览模板 README 给出了生成后项目的完整结构{{cookiecutter.project_name}}/ ├── pom.xml # Maven project file ├── src/ │ ├── main/ │ │ ├── java/{{cookiecutter.java_package_path}}/ │ │ │ ├── Main.java # Application entry point │ │ │ └── Agent.java # Agent implementation │ │ └── resources/ │ │ └── application.properties │ └── test/java/{{cookiecutter.java_package_path}}/ │ ├── unit/ # Unit tests │ └── e2e/ # End-to-end tests │ ├── integration/ # Server integration tests │ └── load_test/ # Load tests ├── deployment/ │ └── terraform/ # Infrastructure as Code ├── Dockerfile # Container build ├── GEMINI.md # AI-assisted development guide └── Makefile # Common commands对照仓库实际文件agent_starter_pack/base_templates/java/可以看到测试目录确实按unit/、e2e/integration/、e2e/load_test/三个层次组织分别对应AgentTest.java、ServerE2ETest.java、LoadTest.java。若选择 GKE 作为部署目标结构还会额外包含k8s/目录存放 Kubernetes 清单。模板中另有一个被渲染为GEMINI.md的占位文件{{cookiecutter.agent_guidance_filename}}README 建议配合 Gemini CLI 做 AI 辅助开发——项目上下文已预配置在该文件中。环境要求生成的项目对开发环境有明确的版本要求完整项目模式即非 extracted 模式依赖版本要求用途Java17 或更高JDK 运行时与编译环境Maven3.9 或更高依赖管理与构建Google Cloud SDKgcloud最新稳定版部署、认证与资源管理Google Cloud 项目已启用 Vertex AIAgent 模型调用所需Maven 侧的最低 Java 版本由 pom.xml 中的java.version17/java.version与maven.compiler.release属性共同约束。快速开始三步跑起本地 Playground完整项目模式的 Quick Start 只有三步1. 安装依赖make install该命令在 Makefile 中实现为mvn dependency:resolve只解析下载依赖而不编译。2. 配置环境cp .env.example .env # 编辑 .env 填入你的 Google Cloud 项目 IDMakefile 顶部会自动加载项目根目录下存在的.env文件ifneq (,$(wildcard ./.env))判断后include .env并export所以通过.env声明的环境变量会直接注入后续所有 make 目标。3. 启动 Playgroundmake playgroundplayground目标实际执行的是mvn compile exec:java -Dlogging.level.rootWARN -Dlogging.level.com.google.adkINFO启动后打开http://localhost:8080/dev-ui/ADK Web 界面即可与 Agent 交互。Makefile 中的横幅提示了一个典型试问句Whats the weather in San Francisco?——这与模板自带的getWeather天气工具遥相呼应。日志级别被显式压制root 为 WARN、ADK 包为 INFO避免开发时刷屏。常用命令一览模板 README 汇总了全部 make 目标CommandDescriptionmake install下载 Maven 依赖make playground启动带 Web UI 的本地开发环境make test运行单元与 E2E 集成测试make build构建 JAR 包make clean清理构建产物make lint运行代码质量检查make local-backend在 8080 端口启动服务端与 Cloud Run 行为一致make deploy部署到 Cloud Runmake load-test运行负载测试需要服务端已在运行make inspector启动 A2A Protocol Inspectormake setup-dev-env通过 Terraform 搭建开发环境基础设施make register-gemini-enterprise将 Agent 注册到 Gemini Enterprise其中build在 Makefile 中实现为mvn package -DskipTests跳过测试打包lint对应mvn checkstyle:check使用 Google 官方代码规范google_checks.xml见 pom.xml 中 maven-checkstyle-plugin 配置local-backend与playground底层命令相同只是定位为模拟 Cloud Run 的运行形态。深入源码pom.xml 的依赖与构建编排pom.xml 是理解该模板技术栈的关键。它声明了四类 ADK 相关依赖版本统一由adk.version0.5.0/adk.version属性管理依赖com.google.adk作用google-adkADK 核心库提供BaseAgent、LlmAgent、工具FunctionTool等google-adk-devADK Dev UI支撑/dev-ui调试界面google-adk-a2a-webserviceA2AAgent-to-Agent协议 Web 服务提供远程消息端点junit-jupiter5.11.4test 作用域JUnit 5 单元测试框架spring-boot-starter-test3.5.3test 作用域Spring Boot 测试支持WebEnvironment、TestRestTemplate 等构建插件同样值得留意maven-compiler-plugin 3.13.0以release17/release编译exec-maven-plugin 3.4.1mainClass指向{{cookiecutter.java_package}}.Main供make playground/make local-backend直接运行maven-surefire-plugin 3.5.2默认测试阶段只包含**/unit/**/*Test.java和**/e2e/integration/**/*Test.java并通过excludedGroupsload/excludedGroups显式排除负载测试maven-failsafe-plugin 3.5.2专门执行**/e2e/load_test/**/*Test.javagroupsload/groups并通过systemPropertyVariables传递staging.url、load.duration、load.users、load.ramp四个参数maven-checkstyle-plugin 3.6.0使用google_checks.xml并failsOnErrortrue保证代码风格一致性spring-boot-maven-plugin 3.4.1repackage生成可执行 JARfinalName为app。此外 pom.xml 还内嵌了 ASPAgent Starter Pack元数据属性asp.name、asp.version、asp.deployment_target、asp.cicd_runner等用于记录项目来源供后续upgrade命令做智能合并。入口与 Agent 定义从占位到真实实现Main.java以静态加载模式启动 ADK Web ServerMain.java 是整个应用的入口public class Main { public static void main(String[] args) { System.setProperty(adk.agents.loader, static); new SpringApplication(AdkWebServer.class, Agent.class).run(args); } }它做了两件关键的事将adk.agents.loader设为static采用静态 Agent 加载器直接从代码注册的 Agent 而非动态加载然后以 Spring Boot 方式启动AdkWebServer并把Agent.class作为配置类一起装配。启动后同时提供 API、A2A 与 Web UI 三套能力。Agent.java占位桩与真实天气 Agent基础模板自带的 Agent.java 是一个刻意留空的占位类它通过ConfigurationImport(A2ARemoteConfiguration.class)引入 A2A 支持端点/a2a/remote/v1/message:send但静态块直接抛出UnsupportedOperationException并注释说明该文件应由 Agent 模板覆盖。真正被覆盖后的实现可以参考 agent_starter_pack/agents/adk_java/ 中的 Agent.java它展示了完整的 Agent 定义范式public static final LlmAgent ROOT_AGENT LlmAgent.builder() .name({{cookiecutter.project_name}}) .model(gemini-3-flash-preview) .description(A helpful AI assistant that can provide weather information.) .instruction( You are a helpful assistant that can provide weather information. When asked about weather, use the get_weather tool. Be friendly and concise in your responses.) .tools(FunctionTool.create(Agent.class, getWeather)) .build();要点包括用LlmAgent.builder()声明大模型 Agent通过.tools(FunctionTool.create(...))把静态方法getWeather暴露为工具工具参数用Schema(name city, description ...)注解描述ADK 会据此生成模型可理解的工具 schema。同时该类还内嵌了一个AgentCardControllerREST 控制器在/.well-known/agent-card.json暴露 A2A Agent Card卡片内容名称、描述、URL、版本、capabilities、输入输出模式、skills由ROOT_AGENT的元数据与工具列表动态生成——这正是 A2A 协议下其他 Agent 发现并调用本 Agent 的入口。测试体系单元、E2E 与负载三层防护模板 README 给出了完整的测试命令# 运行单元和 e2e 集成测试 make test # 本地负载测试先通过 make local-backend 启动服务端 make load-test # 针对远程部署的负载测试 make load-test URLhttps://your-service.run.app # 自定义参数的负载测试 make load-test DURATION60 USERS20 RAMP5单元测试AgentTest.java 是一个 JUnit 5 占位测试assertNotNull(Test infrastructure is working)同样会在生成项目时被具体 Agent 模板的测试替换用于验证测试基础设施可用。E2E 集成测试ServerE2ETest.java 用SpringBootTestwebEnvironment RANDOM_PORT、adk.agents.loaderstatic拉起完整服务端覆盖三个场景Agent Card 端点GET/.well-known/agent-card.json校验 200 状态及name、description、url、version、capabilities、defaultInputModes、defaultOutputModes、skills等必需字段并断言至少一个 skill、streamingfalse、输入输出模式包含text/plainA2A 消息发送向/a2a/remote/v1/message:sendPOST 一个标准 JSON-RPC 2.0 的message/send请求断言返回 200错误处理发送未知 methodinvalid/method的请求验证错误响应符合 JSON-RPC 错误格式。负载测试LoadTest.java 是一个基于 Java 原生HttpClient的并发压测工具其详细使用说明见 load_test/README.md。可配置参数及默认值如下参数Makefile 变量默认值说明目标 URLURLhttp://127.0.0.1:8080压测的服务地址持续时长DURATION30 秒压测总时长并发用户数USERS10同时模拟的用户线程数爬坡速率RAMP2 用户/秒用户启动间隔的换算基准实现细节用户按1000/ramp毫秒间隔逐个启动每个用户循环向/a2a/remote/v1/message:send发送message/send请求请求间随机休眠 13 秒支持通过_ID_TOKEN环境变量携带 Bearer Token远程压测时使用export _ID_TOKEN$(gcloud auth print-identity-token -q)获取需要roles/run.invoker角色。结束时输出 Total / Successful / Failed / Rate LimitedHTTP 429、吞吐量req/sec、Min / Avg / Max / P50 / P95 / P99 延迟且失败率超过 10% 会直接判定测试失败failureRate 0.1抛出 AssertionError。若未提供staging.url测试会静默跳过。Makefile 中load-test目标对应的底层命令是mvn test-compile failsafe:integration-test failsafe:verify \ -Dstaging.url$(or $(URL),http://127.0.0.1:8080) \ -Dload.duration$(or $(DURATION),30) \ -Dload.users$(or $(USERS),10) \ -Dload.ramp$(or $(RAMP),2)部署Cloud Run / GKE / CI/CD一键部署make deploy根据生成时选择的部署目标cookiecutter.deployment_targetMakefile 中的deploy目标有两种实现Cloud Run自动读取gcloud config get-value project获取项目 ID执行gcloud run deploy默认区域us-east1、内存 4Gi、--no-allow-unauthenticated不允许匿名访问、--no-cpu-throttling并注入GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATIONglobal、GOOGLE_GENAI_USE_VERTEXAITrue与APP_URL环境变量可通过make deploy PORT8080指定容器端口GKE先terraform init terraform apply搭建基础设施再获取 kubectl 凭证、通过 Cloud Build 构建并推送镜像到 Artifact Registry随后kubectl set image滚动更新并等待 rollout 完成最后尝试获取 LoadBalancer 外部 IP 并注入APP_URL示例make deploy IMAGE_TAGv1.0.0。backend目标是deploy的向后兼容别名。开发环境基础设施make setup-dev-env会在deployment/terraform/dev目录下执行terraform init terraform apply --var-file vars/env.tfvars --var dev_project_id$(gcloud config get-value project)一键搭建开发环境所需的 Google Cloud 资源。关于 Terraform 配置的更详细说明见 deployment/README.md——官方推荐用agent-starter-pack setup-cicd命令完成基础设施部署与 CI/CD 管道搭建也支持手动应用 Terraform 配置。CI/CD 管道模板按cookiecutter.cicd_runner的选择内置 CI/CDgoogle_cloud_build.cloudbuild/目录下的 Cloud Build 配置github_actions.github/workflows/目录下的 GitHub Actions 工作流。交互调试A2A Protocol Inspector 与 Gemini Enterprise 注册A2A Inspectormake inspector会克隆并启动 A2A 官方 InspectorUI 位于http://localhost:5001用于以可视化的方式测试 Agent 的 A2A 实现。按 Makefile 提示本地测试时把http://localhost:8080/.well-known/agent-card.json粘贴进 Inspector远程测试时先用gcloud run services describe {{cookiecutter.project_name}} --region us-east1拿到服务 URL再拼接/.well-known/agent-card.json。Gemini Enterprise 注册仅 Cloud Run 目标提供make register-gemini-enterprise其底层调用uvx agent-starter-pack register-gemini-enterprise将 Agent 的 agent-card URLhttps://{{cookiecutter.project_name}}-PROJECT_NUMBER.us-east1.run.app/.well-known/agent-card.json注册到 Gemini Enterprise供 A2A 发现。版本升级智能合并保留自定义模板 README 提供了升级到最新 agent-starter-pack 版本的方式uvx agent-starter-pack upgrade该命令会智能合并上游更新同时保留你已有的自定义改动--dry-run可以先预览变更效果。升级逻辑对应的实现位于 agent_starter_pack/cli/utils/upgrade.py其测试覆盖见 tests/cli/utils/test_upgrade_utils.py。从模板中提取的最小 Agent如果项目是通过extract命令从完整项目提取出来的最小 Agentextracted 模式README 会呈现一个精简形态没有部署目录与 E2E 测试Quick Start简化为make install make playgroundRequirements只需 Java 17 与 Maven 3.9。此时若需要恢复部署能力CI/CD、Terraform、Cloud Run 支持及测试脚手架只需在项目根目录执行agent-starter-pack enhanceenhance命令会还原完整的项目结构与部署能力相关实现位于 agent_starter_pack/cli/commands/enhance.py。小结agent-starter-pack 的 Java 基础模板把Agent 业务实现与工程化能力做了清晰解耦你只需在Agent.java中声明模型、指令与工具就能免费获得 Maven 依赖管理、三层测试体系、Google 代码规范检查、Terraform 基础设施、Cloud Run / GKE 部署、A2A 协议支持与 Gemini Enterprise 注册等一整套生产级设施。对 Java 团队而言这是将 ADK Agent 快速推向 Google Cloud 的一条低成本、可验证、可升级的标准化路径。【免费下载链接】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），仅供参考 agent-starter-pack Java 基础模板深度解析：用 ADK 在 Google Cloud 上构建、测试与部署 Java AI Agent
agent-starter-pack Java 基础模板深度解析用 ADK 在 Google Cloud 上构建、测试与部署 Java AI 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本指南以 agent-starter-pack 仓库中的 Java 基础模板agent_starter_pack/base_templates/java/README.md为核心结合模板内的 Maven 配置、Makefile、Agent 实现与测试源码系统讲解如何基于 Google Agent Development KitADK搭建一个 Java 语言编写的 AI Agent 项目。读完本文你将掌握该模板的完整目录结构、依赖与构建机制、本地 Playground 调试方法、单元 / E2E / 负载测试体系以及部署到 Cloud Run / GKE 并注册到 Gemini Enterprise 的完整链路。模板定位生成 Java Agent 项目的标准骨架agent-starter-pack为不同语言提供了统一的基础模板base templatesJava 模板位于 agent_starter_pack/base_templates/java/目录结构与 Go、Python、TypeScript 模板平行。它是 Cookiecutter 风格的可渲染模板——文件中的{{cookiecutter.project_name}}、{{cookiecutter.java_package}}等占位符会在通过agent-starter-pack create命令生成项目时被替换为实际值最终产出一个开箱即用的 Java ADK Agent 工程。模板的定位可以从两个维度理解占位实现Placeholder模板自带的Agent.java只是一个待覆盖的桩实现真正的 Agent 逻辑由adk_java等具体 Agent 模板agent_starter_pack/agents/adk_java/在生成时覆盖进去工程化能力完整无论 Agent 业务如何替换构建Maven、测试单元 / 集成 / 负载、代码质量Checkstyle、部署Terraform CI/CD等工程设施都是现成的。项目结构总览模板 README 给出了生成后项目的完整结构{{cookiecutter.project_name}}/ ├── pom.xml # Maven project file ├── src/ │ ├── main/ │ │ ├── java/{{cookiecutter.java_package_path}}/ │ │ │ ├── Main.java # Application entry point │ │ │ └── Agent.java # Agent implementation │ │ └── resources/ │ │ └── application.properties │ └── test/java/{{cookiecutter.java_package_path}}/ │ ├── unit/ # Unit tests │ └── e2e/ # End-to-end tests │ ├── integration/ # Server integration tests │ └── load_test/ # Load tests ├── deployment/ │ └── terraform/ # Infrastructure as Code ├── Dockerfile # Container build ├── GEMINI.md # AI-assisted development guide └── Makefile # Common commands对照仓库实际文件agent_starter_pack/base_templates/java/可以看到测试目录确实按unit/、e2e/integration/、e2e/load_test/三个层次组织分别对应AgentTest.java、ServerE2ETest.java、LoadTest.java。若选择 GKE 作为部署目标结构还会额外包含k8s/目录存放 Kubernetes 清单。模板中另有一个被渲染为GEMINI.md的占位文件{{cookiecutter.agent_guidance_filename}}README 建议配合 Gemini CLI 做 AI 辅助开发——项目上下文已预配置在该文件中。环境要求生成的项目对开发环境有明确的版本要求完整项目模式即非 extracted 模式依赖版本要求用途Java17 或更高JDK 运行时与编译环境Maven3.9 或更高依赖管理与构建Google Cloud SDKgcloud最新稳定版部署、认证与资源管理Google Cloud 项目已启用 Vertex AIAgent 模型调用所需Maven 侧的最低 Java 版本由 pom.xml 中的java.version17/java.version与maven.compiler.release属性共同约束。快速开始三步跑起本地 Playground完整项目模式的 Quick Start 只有三步1. 安装依赖make install该命令在 Makefile 中实现为mvn dependency:resolve只解析下载依赖而不编译。2. 配置环境cp .env.example .env # 编辑 .env 填入你的 Google Cloud 项目 IDMakefile 顶部会自动加载项目根目录下存在的.env文件ifneq (,$(wildcard ./.env))判断后include .env并export所以通过.env声明的环境变量会直接注入后续所有 make 目标。3. 启动 Playgroundmake playgroundplayground目标实际执行的是mvn compile exec:java -Dlogging.level.rootWARN -Dlogging.level.com.google.adkINFO启动后打开http://localhost:8080/dev-ui/ADK Web 界面即可与 Agent 交互。Makefile 中的横幅提示了一个典型试问句Whats the weather in San Francisco?——这与模板自带的getWeather天气工具遥相呼应。日志级别被显式压制root 为 WARN、ADK 包为 INFO避免开发时刷屏。常用命令一览模板 README 汇总了全部 make 目标CommandDescriptionmake install下载 Maven 依赖make playground启动带 Web UI 的本地开发环境make test运行单元与 E2E 集成测试make build构建 JAR 包make clean清理构建产物make lint运行代码质量检查make local-backend在 8080 端口启动服务端与 Cloud Run 行为一致make deploy部署到 Cloud Runmake load-test运行负载测试需要服务端已在运行make inspector启动 A2A Protocol Inspectormake setup-dev-env通过 Terraform 搭建开发环境基础设施make register-gemini-enterprise将 Agent 注册到 Gemini Enterprise其中build在 Makefile 中实现为mvn package -DskipTests跳过测试打包lint对应mvn checkstyle:check使用 Google 官方代码规范google_checks.xml见 pom.xml 中 maven-checkstyle-plugin 配置local-backend与playground底层命令相同只是定位为模拟 Cloud Run 的运行形态。深入源码pom.xml 的依赖与构建编排pom.xml 是理解该模板技术栈的关键。它声明了四类 ADK 相关依赖版本统一由adk.version0.5.0/adk.version属性管理依赖com.google.adk作用google-adkADK 核心库提供BaseAgent、LlmAgent、工具FunctionTool等google-adk-devADK Dev UI支撑/dev-ui调试界面google-adk-a2a-webserviceA2AAgent-to-Agent协议 Web 服务提供远程消息端点junit-jupiter5.11.4test 作用域JUnit 5 单元测试框架spring-boot-starter-test3.5.3test 作用域Spring Boot 测试支持WebEnvironment、TestRestTemplate 等构建插件同样值得留意maven-compiler-plugin 3.13.0以release17/release编译exec-maven-plugin 3.4.1mainClass指向{{cookiecutter.java_package}}.Main供make playground/make local-backend直接运行maven-surefire-plugin 3.5.2默认测试阶段只包含**/unit/**/*Test.java和**/e2e/integration/**/*Test.java并通过excludedGroupsload/excludedGroups显式排除负载测试maven-failsafe-plugin 3.5.2专门执行**/e2e/load_test/**/*Test.javagroupsload/groups并通过systemPropertyVariables传递staging.url、load.duration、load.users、load.ramp四个参数maven-checkstyle-plugin 3.6.0使用google_checks.xml并failsOnErrortrue保证代码风格一致性spring-boot-maven-plugin 3.4.1repackage生成可执行 JARfinalName为app。此外 pom.xml 还内嵌了 ASPAgent Starter Pack元数据属性asp.name、asp.version、asp.deployment_target、asp.cicd_runner等用于记录项目来源供后续upgrade命令做智能合并。入口与 Agent 定义从占位到真实实现Main.java以静态加载模式启动 ADK Web ServerMain.java 是整个应用的入口public class Main { public static void main(String[] args) { System.setProperty(adk.agents.loader, static); new SpringApplication(AdkWebServer.class, Agent.class).run(args); } }它做了两件关键的事将adk.agents.loader设为static采用静态 Agent 加载器直接从代码注册的 Agent 而非动态加载然后以 Spring Boot 方式启动AdkWebServer并把Agent.class作为配置类一起装配。启动后同时提供 API、A2A 与 Web UI 三套能力。Agent.java占位桩与真实天气 Agent基础模板自带的 Agent.java 是一个刻意留空的占位类它通过ConfigurationImport(A2ARemoteConfiguration.class)引入 A2A 支持端点/a2a/remote/v1/message:send但静态块直接抛出UnsupportedOperationException并注释说明该文件应由 Agent 模板覆盖。真正被覆盖后的实现可以参考 agent_starter_pack/agents/adk_java/ 中的 Agent.java它展示了完整的 Agent 定义范式public static final LlmAgent ROOT_AGENT LlmAgent.builder() .name({{cookiecutter.project_name}}) .model(gemini-3-flash-preview) .description(A helpful AI assistant that can provide weather information.) .instruction( You are a helpful assistant that can provide weather information. When asked about weather, use the get_weather tool. Be friendly and concise in your responses.) .tools(FunctionTool.create(Agent.class, getWeather)) .build();要点包括用LlmAgent.builder()声明大模型 Agent通过.tools(FunctionTool.create(...))把静态方法getWeather暴露为工具工具参数用Schema(name city, description ...)注解描述ADK 会据此生成模型可理解的工具 schema。同时该类还内嵌了一个AgentCardControllerREST 控制器在/.well-known/agent-card.json暴露 A2A Agent Card卡片内容名称、描述、URL、版本、capabilities、输入输出模式、skills由ROOT_AGENT的元数据与工具列表动态生成——这正是 A2A 协议下其他 Agent 发现并调用本 Agent 的入口。测试体系单元、E2E 与负载三层防护模板 README 给出了完整的测试命令# 运行单元和 e2e 集成测试 make test # 本地负载测试先通过 make local-backend 启动服务端 make load-test # 针对远程部署的负载测试 make load-test URLhttps://your-service.run.app # 自定义参数的负载测试 make load-test DURATION60 USERS20 RAMP5单元测试AgentTest.java 是一个 JUnit 5 占位测试assertNotNull(Test infrastructure is working)同样会在生成项目时被具体 Agent 模板的测试替换用于验证测试基础设施可用。E2E 集成测试ServerE2ETest.java 用SpringBootTestwebEnvironment RANDOM_PORT、adk.agents.loaderstatic拉起完整服务端覆盖三个场景Agent Card 端点GET/.well-known/agent-card.json校验 200 状态及name、description、url、version、capabilities、defaultInputModes、defaultOutputModes、skills等必需字段并断言至少一个 skill、streamingfalse、输入输出模式包含text/plainA2A 消息发送向/a2a/remote/v1/message:sendPOST 一个标准 JSON-RPC 2.0 的message/send请求断言返回 200错误处理发送未知 methodinvalid/method的请求验证错误响应符合 JSON-RPC 错误格式。负载测试LoadTest.java 是一个基于 Java 原生HttpClient的并发压测工具其详细使用说明见 load_test/README.md。可配置参数及默认值如下参数Makefile 变量默认值说明目标 URLURLhttp://127.0.0.1:8080压测的服务地址持续时长DURATION30 秒压测总时长并发用户数USERS10同时模拟的用户线程数爬坡速率RAMP2 用户/秒用户启动间隔的换算基准实现细节用户按1000/ramp毫秒间隔逐个启动每个用户循环向/a2a/remote/v1/message:send发送message/send请求请求间随机休眠 13 秒支持通过_ID_TOKEN环境变量携带 Bearer Token远程压测时使用export _ID_TOKEN$(gcloud auth print-identity-token -q)获取需要roles/run.invoker角色。结束时输出 Total / Successful / Failed / Rate LimitedHTTP 429、吞吐量req/sec、Min / Avg / Max / P50 / P95 / P99 延迟且失败率超过 10% 会直接判定测试失败failureRate 0.1抛出 AssertionError。若未提供staging.url测试会静默跳过。Makefile 中load-test目标对应的底层命令是mvn test-compile failsafe:integration-test failsafe:verify \ -Dstaging.url$(or $(URL),http://127.0.0.1:8080) \ -Dload.duration$(or $(DURATION),30) \ -Dload.users$(or $(USERS),10) \ -Dload.ramp$(or $(RAMP),2)部署Cloud Run / GKE / CI/CD一键部署make deploy根据生成时选择的部署目标cookiecutter.deployment_targetMakefile 中的deploy目标有两种实现Cloud Run自动读取gcloud config get-value project获取项目 ID执行gcloud run deploy默认区域us-east1、内存 4Gi、--no-allow-unauthenticated不允许匿名访问、--no-cpu-throttling并注入GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATIONglobal、GOOGLE_GENAI_USE_VERTEXAITrue与APP_URL环境变量可通过make deploy PORT8080指定容器端口GKE先terraform init terraform apply搭建基础设施再获取 kubectl 凭证、通过 Cloud Build 构建并推送镜像到 Artifact Registry随后kubectl set image滚动更新并等待 rollout 完成最后尝试获取 LoadBalancer 外部 IP 并注入APP_URL示例make deploy IMAGE_TAGv1.0.0。backend目标是deploy的向后兼容别名。开发环境基础设施make setup-dev-env会在deployment/terraform/dev目录下执行terraform init terraform apply --var-file vars/env.tfvars --var dev_project_id$(gcloud config get-value project)一键搭建开发环境所需的 Google Cloud 资源。关于 Terraform 配置的更详细说明见 deployment/README.md——官方推荐用agent-starter-pack setup-cicd命令完成基础设施部署与 CI/CD 管道搭建也支持手动应用 Terraform 配置。CI/CD 管道模板按cookiecutter.cicd_runner的选择内置 CI/CDgoogle_cloud_build.cloudbuild/目录下的 Cloud Build 配置github_actions.github/workflows/目录下的 GitHub Actions 工作流。交互调试A2A Protocol Inspector 与 Gemini Enterprise 注册A2A Inspectormake inspector会克隆并启动 A2A 官方 InspectorUI 位于http://localhost:5001用于以可视化的方式测试 Agent 的 A2A 实现。按 Makefile 提示本地测试时把http://localhost:8080/.well-known/agent-card.json粘贴进 Inspector远程测试时先用gcloud run services describe {{cookiecutter.project_name}} --region us-east1拿到服务 URL再拼接/.well-known/agent-card.json。Gemini Enterprise 注册仅 Cloud Run 目标提供make register-gemini-enterprise其底层调用uvx agent-starter-pack register-gemini-enterprise将 Agent 的 agent-card URLhttps://{{cookiecutter.project_name}}-PROJECT_NUMBER.us-east1.run.app/.well-known/agent-card.json注册到 Gemini Enterprise供 A2A 发现。版本升级智能合并保留自定义模板 README 提供了升级到最新 agent-starter-pack 版本的方式uvx agent-starter-pack upgrade该命令会智能合并上游更新同时保留你已有的自定义改动--dry-run可以先预览变更效果。升级逻辑对应的实现位于 agent_starter_pack/cli/utils/upgrade.py其测试覆盖见 tests/cli/utils/test_upgrade_utils.py。从模板中提取的最小 Agent如果项目是通过extract命令从完整项目提取出来的最小 Agentextracted 模式README 会呈现一个精简形态没有部署目录与 E2E 测试Quick Start简化为make install make playgroundRequirements只需 Java 17 与 Maven 3.9。此时若需要恢复部署能力CI/CD、Terraform、Cloud Run 支持及测试脚手架只需在项目根目录执行agent-starter-pack enhanceenhance命令会还原完整的项目结构与部署能力相关实现位于 agent_starter_pack/cli/commands/enhance.py。小结agent-starter-pack 的 Java 基础模板把Agent 业务实现与工程化能力做了清晰解耦你只需在Agent.java中声明模型、指令与工具就能免费获得 Maven 依赖管理、三层测试体系、Google 代码规范检查、Terraform 基础设施、Cloud Run / GKE 部署、A2A 协议支持与 Gemini Enterprise 注册等一整套生产级设施。对 Java 团队而言这是将 ADK Agent 快速推向 Google Cloud 的一条低成本、可验证、可升级的标准化路径。【免费下载链接】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），仅供参考