Agent Starter Pack 带 UI 部署实战Cloud Run IAP 实现前后端统一部署【免费下载链接】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 官方指南 docs/guide/deploy-ui.md 展开系统讲解如何把带用户界面的 Agent 应用部署到 Google Cloud重点覆盖两种部署策略统一部署与解耦部署、基于 Cloud Run Identity-Aware ProxyIAP的实操流程、内置框架 UI 与自定义前端两种场景的 Dockerfile 与make deploy命令用法以及部署后的用户访问授权管理。读完本文你将掌握用一条make命令将后端 API 前端 UI一键发布为受 IAP 保护的 Cloud Run 服务并理解各配置参数在仓库模板中的底层实现。1. 两种部署策略统一部署 vs 解耦部署带 UI 的 Agent 应用通常由后端 API 服务和前端 Web UI两部分组成。官方指南 deploy-ui.md 明确了两种主流部署策略A. 统一部署Unified Deployment描述将后端与前端打包进同一个服务由单一服务对外提供。适用场景架构更简单非常适合开发与测试阶段。技术选型Google Cloud Run 原生支持这种模式并且可以用一个 Identity-Aware Proxy (IAP) 端点统一保护整条服务链路。B. 解耦部署Decoupled Deployment描述后端与前端作为两个相互独立的服务分别运行。适用场景更健壮、更贴近生产环境的架构。何时使用当后端技术栈不适合托管 Web 前端时例如使用了专用Agent Engine就必须采用此方案。此时前端被单独部署到另一个 Cloud Run 服务或 Cloud Storage静态站点上。提示本文聚焦于统一部署策略即使用 Google Cloud Run 一个服务同时承载后端与前端最适合快速开发与内部测试。2. 部署到 Cloud Run 并启用 IAPIAPIdentity-Aware Proxy是 Google Cloud 的零信任访问控制层它位于 Cloud Run 服务之前要求所有访问者先通过 Google 身份认证再根据预设的 IAM 角色决定是否放行。在 Agent Starter Pack 生成的工程中这一能力已经被固化进make deploy模板。具体采用哪种部署方式取决于你使用的是框架自带 UI 还是自定义前端。场景 A使用框架内置 UI如 ADK Web Playground许多 Agent 框架如 ADK自带一个 Web UI 或playground例如adk-web默认与后端 API 一起被服务出来非常适合快速开放给其他开发者或测试人员体验。在仓库的 Python 基座模板 base_templates/python/Makefile 中本地 playground 的启动命令即为playground: uv run adk web . --port 8501 --reload_agents本地验证通过后在项目根目录执行预配置的make命令即可完成部署make deploy IAPtrue这条命令会一次性完成构建容器镜像、推送到镜像仓库Artifact Registry、部署到 Cloud Run、并配置 IAP。查看模板源码 base_templates/python/Makefile 中deploy目标的实际实现可以看到该命令底层展开为一条gcloud beta run deploydeploy: PROJECT_ID$$(gcloud config get-value project) \ gcloud beta run deploy {{cookiecutter.project_name}} \ --source . \ --memory 4Gi \ --project $$PROJECT_ID \ --region us-east1 \ --no-allow-unauthenticated \ --no-cpu-throttling \ --update-env-vars ... \ $(if $(IAP),--iap) \ $(if $(PORT),--port$(PORT))关键参数说明均可在模板中核对参数含义--no-allow-unauthenticated禁止匿名访问所有请求必须经过身份认证是启用 IAP 的前提--iap由$(if $(IAP),--iap)注入只有显式传入IAPtrue时才附加该标志--port$(PORT)由$(if $(PORT),--port$(PORT))注入用于指定容器对外监听端口--region us-east1模板默认部署区域可通过修改模板变量调整--memory 4Gi/--no-cpu-throttling内存配额与 CPU 常驻配置适合流式推理等长耗时场景值得注意TypeScript 基座模板 base_templates/typescript/Makefile 采用了完全相同的IAP/PORT变量约定因此make deploy IAPtrue在多语言模板间保持一致的调用体验。场景 B自定义前端React / adk_live 等如果你拥有独立的自定义前端例如gemini_fullstack类型的 React 应用或adk_live实时音视频前端并希望与后端一起部署以便测试则需要自定义容器配置。核心策略在开发阶段修改Dockerfile让前端开发服务器 后端 API 服务器在同一个容器内同时启动运行。重要这种方案——尤其是运行前端 dev server如npm run dev——仅适用于开发与测试。生产环境应当构建静态前端资源并高效托管如由后端静态托管或独立部署到 CDN/Cloud Storage。配置组合式 Dockerfile创建或修改Dockerfile同时安装 Python 与 Node.js 依赖并并行启动两个服务。官方指南给出了可直接使用的示例FROM python:3.11-slim # 安装 Node.js 和 npm RUN apt-get update apt-get install -y \ nodejs \ npm \ curl \ apt-get clean \ rm -rf /var/lib/apt/lists/* RUN pip install --no-cache-dir uv0.8.13 WORKDIR /code # 复制后端文件 COPY ./pyproject.toml ./README.md ./uv.lock* ./ COPY ./app ./app # 复制前端文件 COPY ./frontend ./frontend # 安装依赖 RUN uv sync --frozen npm --prefix frontend install EXPOSE 8000 5173 # 并行启动后端与前端 CMD [sh, -c, ALLOW_ORIGINS* uv run uvicorn app.server:app --host 0.0.0.0 --port 8000 npm --prefix frontend run dev -- --host 0.0.0.0 wait]仓库中确实存在同类实践Cloud Run Python 部署模板 deployment_targets/cloud_run/python/Dockerfile 在is_adk_live场景下同样先安装 Node.js通过 NodeSource setup_20.x 脚本再执行cd frontend npm ci npm run build最后在容器内一并启动。这与指南中单容器承载前后端的思路一致区别在于生产模板构建的是静态产物而开发测试场景直接运行 dev server。对于adk_live这类实时交互前端仓库中的 FastAPI 应用 deployment_targets/cloud_run/python/{{cookiecutter.agent_directory}}/fast_api_app.py 展示了如何将构建后的前端目录挂载为静态资源将frontend/build下的/assets目录挂载为静态文件根路径/返回index.html使用 catch-all 路由将非 API 路径ws、feedback、assets、api之外统一回落到index.html以支持前端 SPA 路由。部署组合服务指定前端端口部署时必须告诉 Cloud Run 将流量导向前端的端口。通过向make命令传入PORT变量即可实现。示例中前端运行在5173端口make deploy IAPtrue PORT5173模板中的$(if $(PORT),--port$(PORT))会把它转换为gcloud beta run deploy --port5173从而确保公开的、受 IAP 保护的 URL 对外提供的是用户界面而非后端 API。从仓库测试快照 tests/fixtures/makefile_snapshots/adk_cloud_run_no_data.makefile 中也可以直接看到该模板在真实生成工程中的落地形态# Usage: make deploy [IAPtrue] [PORT8080] - Set IAPtrue to enable Identity-Aware Proxy, PORT to specify container port deploy: ... $(if $(IAP),--iap) \ $(if $(PORT),--port$(PORT))3. 部署后的用户访问管理服务部署完成后IAP 已将其保护起来但此时还没有任何用户被授权访问。你必须将 IAP 的访问角色授予指定的用户或 Google 群组。具体来说需要为目标用户或 Google Group授予httpsResourceAccessor角色这样他们才能通过 IAP 访问你的 Cloud Run 服务。操作可在 Google Cloud Console 中完成也可以使用gcloud命令授予路径为项目 / IAP 设置 / Cloud Run 服务 / 添加成员并绑定 roles/iap.httpsResourceAccessor如果之前使用make deploy IAPtrue部署但访问时仍然被拒绝优先检查是否已完成这一步——这是官方指南明确的常见遗漏点。4. 从开发到生产的演进路径结合仓库整体设计可以梳理出一条清晰的 UI 部署演进路径本地开发make playgroundADK 场景下为uv run adk web . --port 8501 --reload_agents或make local-backend在本地快速迭代内部测试采用本文的统一部署策略用make deploy IAPtrue内置 UI或组合式 Dockerfile PORT变量自定义前端将后端 前端发布到 Cloud Run配合 IAP 做内部访问控制生产环境切换为解耦部署或静态前端托管——后端保持 Cloud Run/Agent Engine 服务前端构建为静态资源高效分发仓库生产模板 deployment_targets/cloud_run/python/Dockerfile 与 fast_api_app.py 已经预置了前端静态构建 后端静态托管的完整实现可作为迁移参考。5. 常见问题与排查要点make deploy报错缺少认证先执行gcloud auth login并确认已gcloud config set project dev-project-id模板中的deploy目标会直接读取当前配置的项目。访问出现 403 或登录后仍拒绝确认已为目标账号授予roles/iap.httpsResourceAccessor角色见第 3 节。部署后页面是后端 API 而非 UI检查是否传入了正确的PORT变量Cloud Run 容器端口必须指向前端服务端口如示例中的 5173。自定义前端跨域问题组合式 Dockerfile 通过ALLOW_ORIGINS*放开 CORS 限制仅建议在开发测试阶段使用生产环境应改为精确配置允许的来源。前端 dev server 不适合生产npm run dev只为开发设计生产务必执行npm run build产出静态资源后托管。结语带 UI 的 Agent 应用部署并不复杂开发测试阶段优先选择Cloud Run 统一部署 IAP一条make deploy IAPtrue必要时追加PORT5173即可让团队通过受保护的 URL 体验你的 Agent生产环境则回归解耦架构前端静态化、后端独立服务化。本文涉及的模板与实现细节均可直接在仓库的 base_templates/python/Makefile、base_templates/typescript/Makefile 与 deployment_targets/cloud_run/python/ 中进一步核对与复用。【免费下载链接】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 带 UI 部署实战：Cloud Run + IAP 实现前后端统一部署
Agent Starter Pack 带 UI 部署实战Cloud Run IAP 实现前后端统一部署【免费下载链接】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 官方指南 docs/guide/deploy-ui.md 展开系统讲解如何把带用户界面的 Agent 应用部署到 Google Cloud重点覆盖两种部署策略统一部署与解耦部署、基于 Cloud Run Identity-Aware ProxyIAP的实操流程、内置框架 UI 与自定义前端两种场景的 Dockerfile 与make deploy命令用法以及部署后的用户访问授权管理。读完本文你将掌握用一条make命令将后端 API 前端 UI一键发布为受 IAP 保护的 Cloud Run 服务并理解各配置参数在仓库模板中的底层实现。1. 两种部署策略统一部署 vs 解耦部署带 UI 的 Agent 应用通常由后端 API 服务和前端 Web UI两部分组成。官方指南 deploy-ui.md 明确了两种主流部署策略A. 统一部署Unified Deployment描述将后端与前端打包进同一个服务由单一服务对外提供。适用场景架构更简单非常适合开发与测试阶段。技术选型Google Cloud Run 原生支持这种模式并且可以用一个 Identity-Aware Proxy (IAP) 端点统一保护整条服务链路。B. 解耦部署Decoupled Deployment描述后端与前端作为两个相互独立的服务分别运行。适用场景更健壮、更贴近生产环境的架构。何时使用当后端技术栈不适合托管 Web 前端时例如使用了专用Agent Engine就必须采用此方案。此时前端被单独部署到另一个 Cloud Run 服务或 Cloud Storage静态站点上。提示本文聚焦于统一部署策略即使用 Google Cloud Run 一个服务同时承载后端与前端最适合快速开发与内部测试。2. 部署到 Cloud Run 并启用 IAPIAPIdentity-Aware Proxy是 Google Cloud 的零信任访问控制层它位于 Cloud Run 服务之前要求所有访问者先通过 Google 身份认证再根据预设的 IAM 角色决定是否放行。在 Agent Starter Pack 生成的工程中这一能力已经被固化进make deploy模板。具体采用哪种部署方式取决于你使用的是框架自带 UI 还是自定义前端。场景 A使用框架内置 UI如 ADK Web Playground许多 Agent 框架如 ADK自带一个 Web UI 或playground例如adk-web默认与后端 API 一起被服务出来非常适合快速开放给其他开发者或测试人员体验。在仓库的 Python 基座模板 base_templates/python/Makefile 中本地 playground 的启动命令即为playground: uv run adk web . --port 8501 --reload_agents本地验证通过后在项目根目录执行预配置的make命令即可完成部署make deploy IAPtrue这条命令会一次性完成构建容器镜像、推送到镜像仓库Artifact Registry、部署到 Cloud Run、并配置 IAP。查看模板源码 base_templates/python/Makefile 中deploy目标的实际实现可以看到该命令底层展开为一条gcloud beta run deploydeploy: PROJECT_ID$$(gcloud config get-value project) \ gcloud beta run deploy {{cookiecutter.project_name}} \ --source . \ --memory 4Gi \ --project $$PROJECT_ID \ --region us-east1 \ --no-allow-unauthenticated \ --no-cpu-throttling \ --update-env-vars ... \ $(if $(IAP),--iap) \ $(if $(PORT),--port$(PORT))关键参数说明均可在模板中核对参数含义--no-allow-unauthenticated禁止匿名访问所有请求必须经过身份认证是启用 IAP 的前提--iap由$(if $(IAP),--iap)注入只有显式传入IAPtrue时才附加该标志--port$(PORT)由$(if $(PORT),--port$(PORT))注入用于指定容器对外监听端口--region us-east1模板默认部署区域可通过修改模板变量调整--memory 4Gi/--no-cpu-throttling内存配额与 CPU 常驻配置适合流式推理等长耗时场景值得注意TypeScript 基座模板 base_templates/typescript/Makefile 采用了完全相同的IAP/PORT变量约定因此make deploy IAPtrue在多语言模板间保持一致的调用体验。场景 B自定义前端React / adk_live 等如果你拥有独立的自定义前端例如gemini_fullstack类型的 React 应用或adk_live实时音视频前端并希望与后端一起部署以便测试则需要自定义容器配置。核心策略在开发阶段修改Dockerfile让前端开发服务器 后端 API 服务器在同一个容器内同时启动运行。重要这种方案——尤其是运行前端 dev server如npm run dev——仅适用于开发与测试。生产环境应当构建静态前端资源并高效托管如由后端静态托管或独立部署到 CDN/Cloud Storage。配置组合式 Dockerfile创建或修改Dockerfile同时安装 Python 与 Node.js 依赖并并行启动两个服务。官方指南给出了可直接使用的示例FROM python:3.11-slim # 安装 Node.js 和 npm RUN apt-get update apt-get install -y \ nodejs \ npm \ curl \ apt-get clean \ rm -rf /var/lib/apt/lists/* RUN pip install --no-cache-dir uv0.8.13 WORKDIR /code # 复制后端文件 COPY ./pyproject.toml ./README.md ./uv.lock* ./ COPY ./app ./app # 复制前端文件 COPY ./frontend ./frontend # 安装依赖 RUN uv sync --frozen npm --prefix frontend install EXPOSE 8000 5173 # 并行启动后端与前端 CMD [sh, -c, ALLOW_ORIGINS* uv run uvicorn app.server:app --host 0.0.0.0 --port 8000 npm --prefix frontend run dev -- --host 0.0.0.0 wait]仓库中确实存在同类实践Cloud Run Python 部署模板 deployment_targets/cloud_run/python/Dockerfile 在is_adk_live场景下同样先安装 Node.js通过 NodeSource setup_20.x 脚本再执行cd frontend npm ci npm run build最后在容器内一并启动。这与指南中单容器承载前后端的思路一致区别在于生产模板构建的是静态产物而开发测试场景直接运行 dev server。对于adk_live这类实时交互前端仓库中的 FastAPI 应用 deployment_targets/cloud_run/python/{{cookiecutter.agent_directory}}/fast_api_app.py 展示了如何将构建后的前端目录挂载为静态资源将frontend/build下的/assets目录挂载为静态文件根路径/返回index.html使用 catch-all 路由将非 API 路径ws、feedback、assets、api之外统一回落到index.html以支持前端 SPA 路由。部署组合服务指定前端端口部署时必须告诉 Cloud Run 将流量导向前端的端口。通过向make命令传入PORT变量即可实现。示例中前端运行在5173端口make deploy IAPtrue PORT5173模板中的$(if $(PORT),--port$(PORT))会把它转换为gcloud beta run deploy --port5173从而确保公开的、受 IAP 保护的 URL 对外提供的是用户界面而非后端 API。从仓库测试快照 tests/fixtures/makefile_snapshots/adk_cloud_run_no_data.makefile 中也可以直接看到该模板在真实生成工程中的落地形态# Usage: make deploy [IAPtrue] [PORT8080] - Set IAPtrue to enable Identity-Aware Proxy, PORT to specify container port deploy: ... $(if $(IAP),--iap) \ $(if $(PORT),--port$(PORT))3. 部署后的用户访问管理服务部署完成后IAP 已将其保护起来但此时还没有任何用户被授权访问。你必须将 IAP 的访问角色授予指定的用户或 Google 群组。具体来说需要为目标用户或 Google Group授予httpsResourceAccessor角色这样他们才能通过 IAP 访问你的 Cloud Run 服务。操作可在 Google Cloud Console 中完成也可以使用gcloud命令授予路径为项目 / IAP 设置 / Cloud Run 服务 / 添加成员并绑定 roles/iap.httpsResourceAccessor如果之前使用make deploy IAPtrue部署但访问时仍然被拒绝优先检查是否已完成这一步——这是官方指南明确的常见遗漏点。4. 从开发到生产的演进路径结合仓库整体设计可以梳理出一条清晰的 UI 部署演进路径本地开发make playgroundADK 场景下为uv run adk web . --port 8501 --reload_agents或make local-backend在本地快速迭代内部测试采用本文的统一部署策略用make deploy IAPtrue内置 UI或组合式 Dockerfile PORT变量自定义前端将后端 前端发布到 Cloud Run配合 IAP 做内部访问控制生产环境切换为解耦部署或静态前端托管——后端保持 Cloud Run/Agent Engine 服务前端构建为静态资源高效分发仓库生产模板 deployment_targets/cloud_run/python/Dockerfile 与 fast_api_app.py 已经预置了前端静态构建 后端静态托管的完整实现可作为迁移参考。5. 常见问题与排查要点make deploy报错缺少认证先执行gcloud auth login并确认已gcloud config set project dev-project-id模板中的deploy目标会直接读取当前配置的项目。访问出现 403 或登录后仍拒绝确认已为目标账号授予roles/iap.httpsResourceAccessor角色见第 3 节。部署后页面是后端 API 而非 UI检查是否传入了正确的PORT变量Cloud Run 容器端口必须指向前端服务端口如示例中的 5173。自定义前端跨域问题组合式 Dockerfile 通过ALLOW_ORIGINS*放开 CORS 限制仅建议在开发测试阶段使用生产环境应改为精确配置允许的来源。前端 dev server 不适合生产npm run dev只为开发设计生产务必执行npm run build产出静态资源后托管。结语带 UI 的 Agent 应用部署并不复杂开发测试阶段优先选择Cloud Run 统一部署 IAP一条make deploy IAPtrue必要时追加PORT5173即可让团队通过受保护的 URL 体验你的 Agent生产环境则回归解耦架构前端静态化、后端独立服务化。本文涉及的模板与实现细节均可直接在仓库的 base_templates/python/Makefile、base_templates/typescript/Makefile 与 deployment_targets/cloud_run/python/ 中进一步核对与复用。【免费下载链接】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），仅供参考