使用 agents-cli 将 AI Agent 部署到 Google Cloud Agent Runtime容器化部署、/api 透传与生产运维实战指南【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli本文聚焦 agents-cli 项目中Agent RuntimeAgent Engine部署目标的完整技术细节容器化部署模型、统一 FastAPI 入口、/apiHTTP 透传、Terraform 资源编排、部署元数据、远程测试与会话/Artifact 服务。读完本文你将掌握用agents-cli deploy将 ADK 或任意框架的 Agent 打包成容器并部署到 Vertex AI Agent Runtime 的全流程理解其与 Cloud Run 的关键差异并能独立完成远程查询、状态恢复、私有网络PSC接入与跨会话记忆等生产场景配置。前置要求本文假设项目已经通过/google-agents-cli-scaffold脚手架完成创建agents-cli create/scaffold enhance未脚手架的项目请先参阅 scaffold 技能。Agent Runtime 部署要求项目根目录存在Dockerfile脚手架生成的项目自带一份。Agent Runtime 部署架构容器即 AgentAgent Runtime即 Vertex AI Agent Engine / Agent Engine 的新名称CLI 中统一使用--deployment-target agent_runtime是 Google Cloud Vertex AI 提供的托管式 Agent 部署服务。与 Cloud Run 自行构建镜像再gcloud run deploy不同Agent Runtime 采用容器化部署模型agents-cli deploy将项目文件打包成源包Agent Engine 根据项目根目录的Dockerfile必需构建容器镜像Agent Engine 创建/更新 Agent Runtime 实例并对外提供服务。文件选择规则.gcloudignore 优先打包源包时文件选择遵循项目根目录的.gcloudignore若不存在则回退到项目根目录的.gitignore。嵌套的.gitignore文件不会被读取。在源码中这一逻辑由 deploy/agent_runtime.py 的_ignore_lines()与_packaged_files()实现始终忽略.git、.gcloudignore、.gitignore三项对应_DEFAULT_IGNORE_LINES与 gcloud 生成的默认忽略规则保持一致支持顶层#!include:file指令展开一次被包含的忽略文件使用pathspec的gitwildmatch语法匹配目录和文件都会逐项校验遍历时对目录与文件排序保证归档顺序确定、可复现。一个值得注意的边界情况如果Dockerfile存在但被.gcloudignore/.gitignore排除agents-cli deploy会在构建前直接报错并提示移除匹配的忽略规则而不是让 Agent Engine 在构建时失败见 agent_runtime.py。对于在 agent_runtime 切换到容器构建模型CLI 版本 0.6.0之前脚手架创建、没有 Dockerfile 的老项目CLI 会给出可操作的迁移建议运行agents-cli scaffold upgrade或使用项目脚手架时对应的旧版本 CLI 部署见 agent_runtime.py。统一的应用入口uvicorn app.fast_api_app:app部署后的容器运行uvicorn app.fast_api_app:app—— 这与 Cloud Run 和 GKE 是同一个入口。不再存在顶层的AgentEngineApp/AdkApp部署入口容器直接通过 HTTP 提供服务。应用暴露哪些路由取决于框架具体查看脚手架的app/fast_api_app.py。agents-cli deploy总是将部署标记为agent_framework google-adk见 service.tf 与 agent_runtime.py。源码注释明确指出该标签仅用于控制 Console 侧渲染哪个 Playground并不约束容器本身——任何语言、任何框架的容器都可以部署。ADK 项目的容器表面Serving Surface对 ADK 项目而言fast_api_app.py通过get_fast_api_app(webTrue, lifespan...)构建 FastAPIapp见 fast_api_app.py。其组装过程如下lifespan 构建一个Runner使用共享的 session/artifact 服务来自app_utils/services.py注册在shared://URI 下并设置auto_create_sessionTrue见 fast_api_app.py挂载 A2A 路由attach_a2a_routes(app, ...)注册 A2A 协议端点挂载 reasoning_engine 契约路由attach_reasoning_engine_routes(app)增加 reasoning_engine 契约端点——该适配器在内部构造一个AdkApp用来分发原生的:streamQuery/:query契约见 reasoning_engine_adapter.py。因此ADK 容器对外同时提供三类 HTTP 表面表面路径用途ADK HTTP 表面/run_sse、/apps/...ADK 原生流式接口A2A 路由/a2a/{app_name}JSON-RPC agent cardA2A 协议交互reasoning_engine 适配器/api/reasoning_engine/api/stream_reasoning_engineConsole Playground 与 Gemini Enterprise ADK 注册reasoning_engine 适配器把分发的类方法严格限制在AdkApp.register_operations()返回的方法集合内stream/async_stream走流式/async走同步确保线上输出与打包版 Agent Engine 一致见 reasoning_engine_adapter.py。此外_adk_python_class_methods()会在部署时通过AdkApp.register_operations()探测并写入容器暴露的运行时契约供部署后用 Vertex SDK 查询 Agent 使用见 agent_runtime.py。/api HTTP 透传无需公网 URL 即可访问 AgentAgent Engine 将容器的 HTTP 路由以/api前缀对外暴露部署后的 Agent 无需独立的公网 Cloud Run URL 即可访问。透传 URL 格式为https://{location}-aiplatform.googleapis.com/reasoningEngines/v1/{resource}/api/{container_path}其中{resource}是完整的projects/.../reasoningEngines/...资源名。例如A2A agent card容器路由/a2a/{agent_directory}/.well-known/agent-card.json可通过以下地址访问https://{location}-aiplatform.googleapis.com/reasoningEngines/v1/{resource}/api/a2a/{agent_directory}/.well-known/agent-card.json{agent_directory}即应用名项目的agent_directory记录在deployment_metadata.json中。这正是deploy成功后广告的精确 URL也是run在--mode a2a下针对 Agent Runtime URL 构造的目标——两者都使用你的 Google 凭据进行认证。在源码层面透传 URL 的构造统一收敛在 _remote.py 的build_agent_runtime_passthrough_url()认证头由 build_remote_headers() 处理——对 Agent Runtime URL 使用access token对 Cloud Run/GKE 等其他目标使用以服务 URL 为 audience 的identity token调用方可通过--header传入自定义Authorization覆盖自动探测。publish 注册差异在 Agent Runtime 上publish默认走ADK 注册对 reasoning-engine 资源名发起:streamQuery而不是 agent card URL只有当容器只提供 A2A 服务时才需要传--registration-type a2a。部署时 CLI 还会为容器注入APP_URL环境变量值为 Agent Runtime 透传地址让 A2A agent card 指向真实的线上入口而不是 localhost。由于首次创建时还不知道服务端分配的引擎 ID这个值在下一次部署时才会被正确填充见 agent_runtime.py。A2A 侧_resolve_app_url()的解析顺序为显式app_url→APP_URL环境变量 → 由运行时环境变量自建透传 URL首次部署即有效→ 本地默认值见 a2a.py。部署agents-cli deploy 完整流程使用agents-cli deploy部署运行agents-cli deploy --help可查看完整 flag 参考。CI/CD 流水线调用的是同一个命令。部署流程三步agents-cli deploy打包项目文件遵循.gcloudignore/.gitignoreAgent Engine 构建容器镜像并创建/更新 Agent Runtime 实例写入deployment_metadata.json记录引擎资源 ID。从源码看deploy_agent_runtime()见 agent_runtime.py内部还做了这些关键动作创建 vs 更新判定按display_name查找现有引擎存在则走 update否则走 create。update 时通过client.agent_engines.get()读取线上完整 spec保留部署外部设置的环境变量与标签_existing_plain_env_vars()/_existing_labels()CLI/用户显式传入的值仍然优先尺寸默认值首次创建时应用保守默认值——--cpu 1、--memory 4Gi、--concurrency 8、--min-instances 0、--max-instances 10见 _utils.py。更新时只发送用户显式设置的参数未设置的保持线上值不变resource_limits只在 cpu/memory 同时给出时才会发送单个给出时会尝试从线上 spec 补齐另一半Agent Identity--agent-identity开启Preview首次部署时setup_agent_identity()创建带身份代理的引擎并授予 6 个 IAM 角色roles/aiplatform.user、roles/serviceusage.serviceUsageConsumer、roles/browser、roles/cloudapiregistry.viewer、roles/logging.logWriter、roles/monitoring.metricWriter见 agent_runtime.py。注意身份类型创建后不可更改CLI 会校验--agent-identity与现有引擎是否匹配不匹配时报错并给出重建建议--service-name name-v2或删除后重部署Agent Gateway 绑定--agent-gateway-egress/--agent-gateway-ingress接受完整网关资源名projects/PROJECT/locations/REGION/agentGateways/GATEWAY空值解绑、缺省不变egress 网关做 TLS 终结要求镜像信任网关根 CA项目需以--agent-gateway脚手架标志创建缺少时会给出agents-cli scaffold enhance . --agent-gateway的修复提示环境变量组装优先级从高到低为--update-env-vars/--set-secrets→ 项目.env→ 可覆盖默认值。GOOGLE_CLOUD_PROJECT被 Agent Runtime 保留平台注入写入会被FAILED_PRECONDITION拒绝CLI 会主动过滤并告警GOOGLE_CLOUD_LOCATION不保留LLM 位置可与部署区域不同。无 AI Studio API Key 时默认GOOGLE_GENAI_USE_VERTEXAItrue与GOOGLE_CLOUD_LOCATIONglobal见 agent_runtime.py。关键部署 FlagFlag说明适用--project/--regionGCP 项目 ID / 区域全部目标--service-name覆盖部署服务名Agent Runtime 显示名默认取项目名覆盖后需同步更新 Terraform 与 CIAgent Runtime, Cloud Run--secrets逗号分隔的ENVSECRET或ENVSECRET:VERSIONAgent Runtime, Cloud Run--update-env-vars逗号分隔的KEYVALUE环境变量Agent Runtime, Cloud Run--agent-identity启用 Agent IdentityPreviewAgent Runtime--network-attachmentPSC 接口的 network attachment 资源名私有 VPC 连通Agent Runtime--dns-peering-domain/--dns-peering-project/--dns-peering-network私有 DNS 解析的三件套需--network-attachmentAgent Runtime--agent-gateway-egress/--agent-gateway-ingress绑定 Agent Gateway 管理出/入站流量Agent Runtime--memory/--cpu资源限制默认4Gi/1Agent Runtime, Cloud Run--min-instances/--max-instances实例数默认0/10Terraform 生成的配置用1Agent Runtime, Cloud Run--concurrency每容器并发请求数默认8Agent Runtime, Cloud Run--port容器端口Cloud Run, Agent Runtime--build-args逗号分隔的 Docker 构建参数Agent Runtime--labels逗号分隔的资源标签增量式未指定的标签保留Agent Runtime, Cloud Run--no-wait/--status异步发起部署 / 查询挂起部署状态Agent Runtime, Cloud Run--list/--dry-run/-n/--no-confirm-project列出部署 / 只打印将执行的命令 / 跳过项目确认全部目标非交互模式注意当项目通过自动解析获得未传--project时交互模式会弹出确认提示。Agent 通常运行在非交互模式下因此依赖自动项目解析时必须显式传--no-confirm-project。超时恢复--no-wait 与 --statusAgent Runtime 部署可能耗时5-10 分钟容易超过命令超时。即使部署命令被取消或超时服务端的部署仍会继续# 不阻塞地发起部署 agents-cli deploy --no-wait # 稍后检查进度建议每 60 秒轮询一次直到完成或失败 agents-cli deploy --status该机制在源码中的实现位于 _operation.py部署启动时无论同步还是--no-wait长时操作LRO名称、项目、区域、部署目标与开始时间会以pending_operation字段写入deployment_metadata.jsondeploy --status读取该字段轮询 LRO。当--status检测到操作完成时会像正常部署一样写入deployment_metadata.json并打印成功输出见 agent_runtime.py。同时CLI 会打印 Logs Explorer 的查询 URL按resource.labels.reasoning_engine_id过滤供实时监控部署日志。重要agents-cli deploy只有在获得用户明确批准后才能执行且不要在部署前先运行agents-cli infra single-project——它并不是部署的前置条件仅当需要可观测性能力时才单独运行见google-agents-cli-observability技能。Terraform 资源google_vertex_ai_reasoning_engineAgent Runtime 在 Terraform 中使用google_vertex_ai_reasoning_engine资源位于 single-project/service.tfCI/CD 托管部署使用 cicd/service.tf 的多项目变体。当前缩放、并发与资源限制设置以这两个文件为准。从模板文件可见当前的资源形状resource google_vertex_ai_reasoning_engine app { display_name var.project_name description Agent deployed via Terraform region var.region project var.project_id spec { agent_framework google-adk service_account google_service_account.app_sa.email deployment_spec { min_instances 1 max_instances 10 container_concurrency 9 resource_limits { cpu 4 memory 8Gi } # env 块LOGS_BUCKET_NAME、GOOGLE_CLOUD_LOCATIONglobal、 # GOOGLE_GENAI_USE_VERTEXAITrue、OTEL_* 遥测变量、BQ 分析变量可选 } source_code_spec { inline_source { source_archive local.dummy_source_b64 # 占位源包 } image_spec {} } } lifecycle { ignore_changes [ spec[0].container_spec, spec[0].source_code_spec, spec[0].deployment_spec, ] } }与 Cloud Run 的关键差异lifecycle.ignore_changes覆盖container_spec、source_code_spec和deployment_spec至关重要——镜像与源码由agents-cli deploy/CI/CD 更新而不是 Terraform。Terraform 创建资源时使用占位源包dummy_source.b64随后 CI/CD 用真实代码覆盖同一个source_code_spec占位必须同样使用source_code_spec而非container_spec否则两者并存会被 Agent Engine 拒绝更新。ignore_changes保证 Terraform 永远不把已部署的 Agent 回滚到占位状态。镜像来源提示Terraform 托管的 Agent Runtime 部署中环境变量含遥测与 BQ 分析配置定义在service.tf内而 SDK 部署agents-cli deploy直接调用的环境变量来自 agent_runtime.py 的_build_runtime_env_vars()。两处当前值均以对应文件为准。deployment_metadata.json部署状态的唯一事实源agents-cli deploy成功部署后写入deployment_metadata.json{ remote_agent_runtime_id: projects/PROJECT/locations/LOCATION/reasoningEngines/ENGINE_ID, deployment_target: agent_runtime, is_a2a: true, agent_directory: app, deployment_timestamp: 2025-02-25T10:30:00.00000:00 }源码中的write_deployment_metadata()见 agent_runtime.py还会额外写入language字段来自项目配置并按 UTC 记录 ISO 时间戳。该文件的用途后续部署判断是 update 还是 create按显示名匹配现有引擎agents-cli run --url远程查询已部署的 Agentagents-cli publish在 Agent Runtime 上读取运行时 ID 作为默认 ADK 注册的 target仅当显式选择 A2A 注册时才构造 A2A card URL。Cloud Run 不使用此文件。另外如果部署超时但引擎已创建成功可以手动将该文件填充为引擎资源 ID格式如上面的 JSON后续命令即可继续工作。文件同时承载pending_operation字段用于--status轮询损坏或残缺的文件会被容错地当作空处理见 _operation.py不会永久阻塞后续部署。CI/CD 与 Cloud Run 的差异对照方面Agent RuntimeCloud Run构建Dockerfile → 镜像由 Agent Engine 构建Dockerfile → 镜像gcloud builds部署命令agents-cli deploygcloud run deploy --image ...产物容器镜像Artifact Registry 中的容器镜像Python 版本在 Dockerfile 中配置在 Dockerfile 中配置负载测试通过locust打向 Agent Runtime 端点直接 HTTP 打向 Cloud Run URL另一个架构级差异Agent Runtime 没有gcloudCLI 可用。部署只能通过agents-cli deploy查询通过 Pythonagentplatform.ClientSDK或agents-cli run --url。Playground 与远程测试# 本地模式使用本地 Agent 实例 agents-cli playground # 远程查询已部署的 Agent RuntimeADK 项目否则用 --mode a2a agents-cli run --url https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/reasoningEngines/ID --mode adk Hello, what can you do?--url必须搭配--modeadk走 ADK 流式 API:streamQuerya2a走 A2A 协议加-v输出完整 JSON 事件负载认证自动探测通过 Google Cloud 凭据获取 tokenAgent Runtime 用 access token。从 cmd_run.py 的源码看远程模式会先校验--mode缺失并报出明确错误再对 URL 做 Agent Runtime 识别is_agent_runtime_url()要求 host 含aiplatform.googleapis.com且路径含reasoningEngines并校验 host 是否带location-区域前缀validate_agent_runtime_url()缺失时给出正确格式提示。app_name即agent_directory未显式给出时从本地项目配置读取。程序化查询Python SDKimport agentplatform client agentplatform.Client(locationus-east1) agent client.agent_engines.get(nameprojects/PROJECT/locations/LOCATION/reasoningEngines/ENGINE_ID) async for event in agent.async_stream_query(messageHello!, user_idtest): print(event)Session 与 Artifact 服务本小节前两段是ADK 脚手架的 session/artifact 装配方式末尾的环境变量来源对任何框架均适用。SessionAgent Runtime 在脚手架阶段总是使用内存会话InMemorySessionService运行时当 Agent Engine 注入GOOGLE_CLOUD_AGENT_ENGINE_ID后app_utils/services.py自动升级为VertexAiSessionService托管式 Agent Engine 会话跨实例/跨请求持久。get_fast_api_app接收shared://sessionURI由 services.py 解析。从源码看session 服务的解析顺序为显式SESSION_SERVICE_URI环境变量 → 有GOOGLE_CLOUD_AGENT_ENGINE_ID时用VertexAiSessionService注意其 location 取运行时注入的GOOGLE_CLOUD_AGENT_ENGINE_LOCATION而不是被 agent.py 固定在global的GOOGLE_CLOUD_LOCATION→ 否则InMemorySessionService。服务注册在shared://命名空间下并通过functools.cache做进程级缓存使 ADK web 路由、A2A 路径与 reasoning_engine 适配器共享同一个实例——任何表面上创建的会话对其他表面都可见。Artifact当LOGS_BUCKET_NAME设置时使用GcsArtifactService否则回退InMemoryArtifactService见 services.py。环境变量来源部署时设置的环境变量SDK 部署来自agents-cli deployCLI 的 deploy/agent_runtime.pyTerraform 托管部署来自 single-project/service.tf或cicd/变体。当前值以对应文件为准模板中可见OTEL_SERVICE_NAME、OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENT、ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANSfalse、GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRYtrue等遥测默认值。Memory Bank跨会话记忆要在 Agent Runtime 上启用跨会话记忆请通过context_spec配置memory_bank_config。完整模式参考 ADK 的cross-session-memory示例google/adk-samples仓库core/python/cross-session-memory目录。NetworkingPSC 接口私有网络连通Agent Runtime默认无法访问你的 VPC。启用私有连通的步骤创建 network attachmentVPC 网络附件部署时加--network-attachment需要私有 DNS 解析时追加--dns-peering-domain、--dns-peering-project、--dns-peering-network三个 flag三者必须同时提供。CLI 侧的校验逻辑见 cmd_deploy.py 的_build_psc_interface_config()DNS peering 相关 flag 必须与--network-attachment一起使用三个 DNS flag 缺一不可。部署时 PSC 配置会以psc_interface_config传入 Agent Engine包含network_attachment与可选dns_peering_configs。重要限制PSC 配置在部署后不可变——如需变更必须删除并重新部署。前置条件与完整设置步骤参考 GCP 官方文档Gemini Enterprise Agent Platform 的 Private Service Connect interface 页面。常见问题与故障排查要点针对 Agent Runtime 部署的常见问题来自 deploy 技能 的 Troubleshooting 小节问题处理Agent Runtime 部署超时/卡住部署需 5-10 分钟检查引擎是否已创建--status轮询部署被取消/中断服务端继续构建运行agents-cli deploy --status检查进度完成后会自动补写元数据403 权限错误检查 iam.tf以实际生成路径为准cicd_runner_sa需要在目标项目具备部署与 SA 模拟角色app_sa缺少iam.serviceAccountUser会报 Cannot act as service accountSecret 访问被拒确认secretmanager.secretAccessor授予了正确的运行身份——Agent Runtime 应授予平台托管的 SAservice-PROJECT_NUMBERgcp-sa-aiplatform-re.iam.gserviceaccount.com而不是默认 compute SA部署后 Agent 报错用 Cloud Logging 按 reasoning engine 资源过滤gcloud logging read resource.typeaiplatform.googleapis.com/ReasoningEngine --projectPROJECT --limit50关于资源尺寸的调优建议同样适用于 Agent Runtime单异步进程横向扩容容器内是单个uvicorn事件循环进程吞吐来自--concurrency与--max-instances而非额外 worker仅在剖析表明事件循环或同步工具调用为 CPU 瓶颈时才提升--cpu内存约束并发每个并发请求在等待模型期间都会把完整工作集上下文窗口、历史、RAG 分块、响应缓冲留在内存中峰值 ≈ 基线 concurrency × 单请求内存。内存是第一个瓶颈只提高--concurrency不提高--memory是 OOM 的主因并发默认值偏保守8是为保护 RAG/多模态等内存密集型 Agent轻量 Agent 可在负载测试后提升到 16-32。# 4 倍吞吐示例四个参数一起缩放而不是只调一个 agents-cli deploy --cpu 4 --concurrency 16 --memory 16Gi --max-instances 20用脚手架的负载测试tests/load_test/本地或 CI/CD staging 阶段运行驱动压测观察最大延迟与内存/OOM 重启再针对性调整——最大延迟高 → 提升 concurrencyOOM → 提升 memory 或降低 concurrency。延伸阅读部署技能总览与目标选型矩阵Agent Runtime / Cloud Run / GKE 对比OAuth 用户授权 Agent 需选 Agent Runtime Gemini EnterpriseCloud Run 部署参考缩放默认值、Dockerfile、session 类型、网络GKE 部署参考Kubernetes 清单、Workload Identity、网络Terraform 模式参考自定义基础设施、IAM、状态管理已部署 Agent 的测试参考curl 示例、负载测试可观测性技能Cloud Trace、prompt-response 日志、BigQuery AnalyticsADK 代码技能事件驱动/环境 Agent 的trigger_sources模式Agent Runtime 上可通过/api透传访问/apps/{app}/trigger/*端点发布技能Gemini Enterprise 注册【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
使用 agents-cli 将 AI Agent 部署到 Google Cloud Agent Runtime：容器化部署、/api 透传与生产运维实战指南
使用 agents-cli 将 AI Agent 部署到 Google Cloud Agent Runtime容器化部署、/api 透传与生产运维实战指南【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli本文聚焦 agents-cli 项目中Agent RuntimeAgent Engine部署目标的完整技术细节容器化部署模型、统一 FastAPI 入口、/apiHTTP 透传、Terraform 资源编排、部署元数据、远程测试与会话/Artifact 服务。读完本文你将掌握用agents-cli deploy将 ADK 或任意框架的 Agent 打包成容器并部署到 Vertex AI Agent Runtime 的全流程理解其与 Cloud Run 的关键差异并能独立完成远程查询、状态恢复、私有网络PSC接入与跨会话记忆等生产场景配置。前置要求本文假设项目已经通过/google-agents-cli-scaffold脚手架完成创建agents-cli create/scaffold enhance未脚手架的项目请先参阅 scaffold 技能。Agent Runtime 部署要求项目根目录存在Dockerfile脚手架生成的项目自带一份。Agent Runtime 部署架构容器即 AgentAgent Runtime即 Vertex AI Agent Engine / Agent Engine 的新名称CLI 中统一使用--deployment-target agent_runtime是 Google Cloud Vertex AI 提供的托管式 Agent 部署服务。与 Cloud Run 自行构建镜像再gcloud run deploy不同Agent Runtime 采用容器化部署模型agents-cli deploy将项目文件打包成源包Agent Engine 根据项目根目录的Dockerfile必需构建容器镜像Agent Engine 创建/更新 Agent Runtime 实例并对外提供服务。文件选择规则.gcloudignore 优先打包源包时文件选择遵循项目根目录的.gcloudignore若不存在则回退到项目根目录的.gitignore。嵌套的.gitignore文件不会被读取。在源码中这一逻辑由 deploy/agent_runtime.py 的_ignore_lines()与_packaged_files()实现始终忽略.git、.gcloudignore、.gitignore三项对应_DEFAULT_IGNORE_LINES与 gcloud 生成的默认忽略规则保持一致支持顶层#!include:file指令展开一次被包含的忽略文件使用pathspec的gitwildmatch语法匹配目录和文件都会逐项校验遍历时对目录与文件排序保证归档顺序确定、可复现。一个值得注意的边界情况如果Dockerfile存在但被.gcloudignore/.gitignore排除agents-cli deploy会在构建前直接报错并提示移除匹配的忽略规则而不是让 Agent Engine 在构建时失败见 agent_runtime.py。对于在 agent_runtime 切换到容器构建模型CLI 版本 0.6.0之前脚手架创建、没有 Dockerfile 的老项目CLI 会给出可操作的迁移建议运行agents-cli scaffold upgrade或使用项目脚手架时对应的旧版本 CLI 部署见 agent_runtime.py。统一的应用入口uvicorn app.fast_api_app:app部署后的容器运行uvicorn app.fast_api_app:app—— 这与 Cloud Run 和 GKE 是同一个入口。不再存在顶层的AgentEngineApp/AdkApp部署入口容器直接通过 HTTP 提供服务。应用暴露哪些路由取决于框架具体查看脚手架的app/fast_api_app.py。agents-cli deploy总是将部署标记为agent_framework google-adk见 service.tf 与 agent_runtime.py。源码注释明确指出该标签仅用于控制 Console 侧渲染哪个 Playground并不约束容器本身——任何语言、任何框架的容器都可以部署。ADK 项目的容器表面Serving Surface对 ADK 项目而言fast_api_app.py通过get_fast_api_app(webTrue, lifespan...)构建 FastAPIapp见 fast_api_app.py。其组装过程如下lifespan 构建一个Runner使用共享的 session/artifact 服务来自app_utils/services.py注册在shared://URI 下并设置auto_create_sessionTrue见 fast_api_app.py挂载 A2A 路由attach_a2a_routes(app, ...)注册 A2A 协议端点挂载 reasoning_engine 契约路由attach_reasoning_engine_routes(app)增加 reasoning_engine 契约端点——该适配器在内部构造一个AdkApp用来分发原生的:streamQuery/:query契约见 reasoning_engine_adapter.py。因此ADK 容器对外同时提供三类 HTTP 表面表面路径用途ADK HTTP 表面/run_sse、/apps/...ADK 原生流式接口A2A 路由/a2a/{app_name}JSON-RPC agent cardA2A 协议交互reasoning_engine 适配器/api/reasoning_engine/api/stream_reasoning_engineConsole Playground 与 Gemini Enterprise ADK 注册reasoning_engine 适配器把分发的类方法严格限制在AdkApp.register_operations()返回的方法集合内stream/async_stream走流式/async走同步确保线上输出与打包版 Agent Engine 一致见 reasoning_engine_adapter.py。此外_adk_python_class_methods()会在部署时通过AdkApp.register_operations()探测并写入容器暴露的运行时契约供部署后用 Vertex SDK 查询 Agent 使用见 agent_runtime.py。/api HTTP 透传无需公网 URL 即可访问 AgentAgent Engine 将容器的 HTTP 路由以/api前缀对外暴露部署后的 Agent 无需独立的公网 Cloud Run URL 即可访问。透传 URL 格式为https://{location}-aiplatform.googleapis.com/reasoningEngines/v1/{resource}/api/{container_path}其中{resource}是完整的projects/.../reasoningEngines/...资源名。例如A2A agent card容器路由/a2a/{agent_directory}/.well-known/agent-card.json可通过以下地址访问https://{location}-aiplatform.googleapis.com/reasoningEngines/v1/{resource}/api/a2a/{agent_directory}/.well-known/agent-card.json{agent_directory}即应用名项目的agent_directory记录在deployment_metadata.json中。这正是deploy成功后广告的精确 URL也是run在--mode a2a下针对 Agent Runtime URL 构造的目标——两者都使用你的 Google 凭据进行认证。在源码层面透传 URL 的构造统一收敛在 _remote.py 的build_agent_runtime_passthrough_url()认证头由 build_remote_headers() 处理——对 Agent Runtime URL 使用access token对 Cloud Run/GKE 等其他目标使用以服务 URL 为 audience 的identity token调用方可通过--header传入自定义Authorization覆盖自动探测。publish 注册差异在 Agent Runtime 上publish默认走ADK 注册对 reasoning-engine 资源名发起:streamQuery而不是 agent card URL只有当容器只提供 A2A 服务时才需要传--registration-type a2a。部署时 CLI 还会为容器注入APP_URL环境变量值为 Agent Runtime 透传地址让 A2A agent card 指向真实的线上入口而不是 localhost。由于首次创建时还不知道服务端分配的引擎 ID这个值在下一次部署时才会被正确填充见 agent_runtime.py。A2A 侧_resolve_app_url()的解析顺序为显式app_url→APP_URL环境变量 → 由运行时环境变量自建透传 URL首次部署即有效→ 本地默认值见 a2a.py。部署agents-cli deploy 完整流程使用agents-cli deploy部署运行agents-cli deploy --help可查看完整 flag 参考。CI/CD 流水线调用的是同一个命令。部署流程三步agents-cli deploy打包项目文件遵循.gcloudignore/.gitignoreAgent Engine 构建容器镜像并创建/更新 Agent Runtime 实例写入deployment_metadata.json记录引擎资源 ID。从源码看deploy_agent_runtime()见 agent_runtime.py内部还做了这些关键动作创建 vs 更新判定按display_name查找现有引擎存在则走 update否则走 create。update 时通过client.agent_engines.get()读取线上完整 spec保留部署外部设置的环境变量与标签_existing_plain_env_vars()/_existing_labels()CLI/用户显式传入的值仍然优先尺寸默认值首次创建时应用保守默认值——--cpu 1、--memory 4Gi、--concurrency 8、--min-instances 0、--max-instances 10见 _utils.py。更新时只发送用户显式设置的参数未设置的保持线上值不变resource_limits只在 cpu/memory 同时给出时才会发送单个给出时会尝试从线上 spec 补齐另一半Agent Identity--agent-identity开启Preview首次部署时setup_agent_identity()创建带身份代理的引擎并授予 6 个 IAM 角色roles/aiplatform.user、roles/serviceusage.serviceUsageConsumer、roles/browser、roles/cloudapiregistry.viewer、roles/logging.logWriter、roles/monitoring.metricWriter见 agent_runtime.py。注意身份类型创建后不可更改CLI 会校验--agent-identity与现有引擎是否匹配不匹配时报错并给出重建建议--service-name name-v2或删除后重部署Agent Gateway 绑定--agent-gateway-egress/--agent-gateway-ingress接受完整网关资源名projects/PROJECT/locations/REGION/agentGateways/GATEWAY空值解绑、缺省不变egress 网关做 TLS 终结要求镜像信任网关根 CA项目需以--agent-gateway脚手架标志创建缺少时会给出agents-cli scaffold enhance . --agent-gateway的修复提示环境变量组装优先级从高到低为--update-env-vars/--set-secrets→ 项目.env→ 可覆盖默认值。GOOGLE_CLOUD_PROJECT被 Agent Runtime 保留平台注入写入会被FAILED_PRECONDITION拒绝CLI 会主动过滤并告警GOOGLE_CLOUD_LOCATION不保留LLM 位置可与部署区域不同。无 AI Studio API Key 时默认GOOGLE_GENAI_USE_VERTEXAItrue与GOOGLE_CLOUD_LOCATIONglobal见 agent_runtime.py。关键部署 FlagFlag说明适用--project/--regionGCP 项目 ID / 区域全部目标--service-name覆盖部署服务名Agent Runtime 显示名默认取项目名覆盖后需同步更新 Terraform 与 CIAgent Runtime, Cloud Run--secrets逗号分隔的ENVSECRET或ENVSECRET:VERSIONAgent Runtime, Cloud Run--update-env-vars逗号分隔的KEYVALUE环境变量Agent Runtime, Cloud Run--agent-identity启用 Agent IdentityPreviewAgent Runtime--network-attachmentPSC 接口的 network attachment 资源名私有 VPC 连通Agent Runtime--dns-peering-domain/--dns-peering-project/--dns-peering-network私有 DNS 解析的三件套需--network-attachmentAgent Runtime--agent-gateway-egress/--agent-gateway-ingress绑定 Agent Gateway 管理出/入站流量Agent Runtime--memory/--cpu资源限制默认4Gi/1Agent Runtime, Cloud Run--min-instances/--max-instances实例数默认0/10Terraform 生成的配置用1Agent Runtime, Cloud Run--concurrency每容器并发请求数默认8Agent Runtime, Cloud Run--port容器端口Cloud Run, Agent Runtime--build-args逗号分隔的 Docker 构建参数Agent Runtime--labels逗号分隔的资源标签增量式未指定的标签保留Agent Runtime, Cloud Run--no-wait/--status异步发起部署 / 查询挂起部署状态Agent Runtime, Cloud Run--list/--dry-run/-n/--no-confirm-project列出部署 / 只打印将执行的命令 / 跳过项目确认全部目标非交互模式注意当项目通过自动解析获得未传--project时交互模式会弹出确认提示。Agent 通常运行在非交互模式下因此依赖自动项目解析时必须显式传--no-confirm-project。超时恢复--no-wait 与 --statusAgent Runtime 部署可能耗时5-10 分钟容易超过命令超时。即使部署命令被取消或超时服务端的部署仍会继续# 不阻塞地发起部署 agents-cli deploy --no-wait # 稍后检查进度建议每 60 秒轮询一次直到完成或失败 agents-cli deploy --status该机制在源码中的实现位于 _operation.py部署启动时无论同步还是--no-wait长时操作LRO名称、项目、区域、部署目标与开始时间会以pending_operation字段写入deployment_metadata.jsondeploy --status读取该字段轮询 LRO。当--status检测到操作完成时会像正常部署一样写入deployment_metadata.json并打印成功输出见 agent_runtime.py。同时CLI 会打印 Logs Explorer 的查询 URL按resource.labels.reasoning_engine_id过滤供实时监控部署日志。重要agents-cli deploy只有在获得用户明确批准后才能执行且不要在部署前先运行agents-cli infra single-project——它并不是部署的前置条件仅当需要可观测性能力时才单独运行见google-agents-cli-observability技能。Terraform 资源google_vertex_ai_reasoning_engineAgent Runtime 在 Terraform 中使用google_vertex_ai_reasoning_engine资源位于 single-project/service.tfCI/CD 托管部署使用 cicd/service.tf 的多项目变体。当前缩放、并发与资源限制设置以这两个文件为准。从模板文件可见当前的资源形状resource google_vertex_ai_reasoning_engine app { display_name var.project_name description Agent deployed via Terraform region var.region project var.project_id spec { agent_framework google-adk service_account google_service_account.app_sa.email deployment_spec { min_instances 1 max_instances 10 container_concurrency 9 resource_limits { cpu 4 memory 8Gi } # env 块LOGS_BUCKET_NAME、GOOGLE_CLOUD_LOCATIONglobal、 # GOOGLE_GENAI_USE_VERTEXAITrue、OTEL_* 遥测变量、BQ 分析变量可选 } source_code_spec { inline_source { source_archive local.dummy_source_b64 # 占位源包 } image_spec {} } } lifecycle { ignore_changes [ spec[0].container_spec, spec[0].source_code_spec, spec[0].deployment_spec, ] } }与 Cloud Run 的关键差异lifecycle.ignore_changes覆盖container_spec、source_code_spec和deployment_spec至关重要——镜像与源码由agents-cli deploy/CI/CD 更新而不是 Terraform。Terraform 创建资源时使用占位源包dummy_source.b64随后 CI/CD 用真实代码覆盖同一个source_code_spec占位必须同样使用source_code_spec而非container_spec否则两者并存会被 Agent Engine 拒绝更新。ignore_changes保证 Terraform 永远不把已部署的 Agent 回滚到占位状态。镜像来源提示Terraform 托管的 Agent Runtime 部署中环境变量含遥测与 BQ 分析配置定义在service.tf内而 SDK 部署agents-cli deploy直接调用的环境变量来自 agent_runtime.py 的_build_runtime_env_vars()。两处当前值均以对应文件为准。deployment_metadata.json部署状态的唯一事实源agents-cli deploy成功部署后写入deployment_metadata.json{ remote_agent_runtime_id: projects/PROJECT/locations/LOCATION/reasoningEngines/ENGINE_ID, deployment_target: agent_runtime, is_a2a: true, agent_directory: app, deployment_timestamp: 2025-02-25T10:30:00.00000:00 }源码中的write_deployment_metadata()见 agent_runtime.py还会额外写入language字段来自项目配置并按 UTC 记录 ISO 时间戳。该文件的用途后续部署判断是 update 还是 create按显示名匹配现有引擎agents-cli run --url远程查询已部署的 Agentagents-cli publish在 Agent Runtime 上读取运行时 ID 作为默认 ADK 注册的 target仅当显式选择 A2A 注册时才构造 A2A card URL。Cloud Run 不使用此文件。另外如果部署超时但引擎已创建成功可以手动将该文件填充为引擎资源 ID格式如上面的 JSON后续命令即可继续工作。文件同时承载pending_operation字段用于--status轮询损坏或残缺的文件会被容错地当作空处理见 _operation.py不会永久阻塞后续部署。CI/CD 与 Cloud Run 的差异对照方面Agent RuntimeCloud Run构建Dockerfile → 镜像由 Agent Engine 构建Dockerfile → 镜像gcloud builds部署命令agents-cli deploygcloud run deploy --image ...产物容器镜像Artifact Registry 中的容器镜像Python 版本在 Dockerfile 中配置在 Dockerfile 中配置负载测试通过locust打向 Agent Runtime 端点直接 HTTP 打向 Cloud Run URL另一个架构级差异Agent Runtime 没有gcloudCLI 可用。部署只能通过agents-cli deploy查询通过 Pythonagentplatform.ClientSDK或agents-cli run --url。Playground 与远程测试# 本地模式使用本地 Agent 实例 agents-cli playground # 远程查询已部署的 Agent RuntimeADK 项目否则用 --mode a2a agents-cli run --url https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/reasoningEngines/ID --mode adk Hello, what can you do?--url必须搭配--modeadk走 ADK 流式 API:streamQuerya2a走 A2A 协议加-v输出完整 JSON 事件负载认证自动探测通过 Google Cloud 凭据获取 tokenAgent Runtime 用 access token。从 cmd_run.py 的源码看远程模式会先校验--mode缺失并报出明确错误再对 URL 做 Agent Runtime 识别is_agent_runtime_url()要求 host 含aiplatform.googleapis.com且路径含reasoningEngines并校验 host 是否带location-区域前缀validate_agent_runtime_url()缺失时给出正确格式提示。app_name即agent_directory未显式给出时从本地项目配置读取。程序化查询Python SDKimport agentplatform client agentplatform.Client(locationus-east1) agent client.agent_engines.get(nameprojects/PROJECT/locations/LOCATION/reasoningEngines/ENGINE_ID) async for event in agent.async_stream_query(messageHello!, user_idtest): print(event)Session 与 Artifact 服务本小节前两段是ADK 脚手架的 session/artifact 装配方式末尾的环境变量来源对任何框架均适用。SessionAgent Runtime 在脚手架阶段总是使用内存会话InMemorySessionService运行时当 Agent Engine 注入GOOGLE_CLOUD_AGENT_ENGINE_ID后app_utils/services.py自动升级为VertexAiSessionService托管式 Agent Engine 会话跨实例/跨请求持久。get_fast_api_app接收shared://sessionURI由 services.py 解析。从源码看session 服务的解析顺序为显式SESSION_SERVICE_URI环境变量 → 有GOOGLE_CLOUD_AGENT_ENGINE_ID时用VertexAiSessionService注意其 location 取运行时注入的GOOGLE_CLOUD_AGENT_ENGINE_LOCATION而不是被 agent.py 固定在global的GOOGLE_CLOUD_LOCATION→ 否则InMemorySessionService。服务注册在shared://命名空间下并通过functools.cache做进程级缓存使 ADK web 路由、A2A 路径与 reasoning_engine 适配器共享同一个实例——任何表面上创建的会话对其他表面都可见。Artifact当LOGS_BUCKET_NAME设置时使用GcsArtifactService否则回退InMemoryArtifactService见 services.py。环境变量来源部署时设置的环境变量SDK 部署来自agents-cli deployCLI 的 deploy/agent_runtime.pyTerraform 托管部署来自 single-project/service.tf或cicd/变体。当前值以对应文件为准模板中可见OTEL_SERVICE_NAME、OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENT、ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANSfalse、GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRYtrue等遥测默认值。Memory Bank跨会话记忆要在 Agent Runtime 上启用跨会话记忆请通过context_spec配置memory_bank_config。完整模式参考 ADK 的cross-session-memory示例google/adk-samples仓库core/python/cross-session-memory目录。NetworkingPSC 接口私有网络连通Agent Runtime默认无法访问你的 VPC。启用私有连通的步骤创建 network attachmentVPC 网络附件部署时加--network-attachment需要私有 DNS 解析时追加--dns-peering-domain、--dns-peering-project、--dns-peering-network三个 flag三者必须同时提供。CLI 侧的校验逻辑见 cmd_deploy.py 的_build_psc_interface_config()DNS peering 相关 flag 必须与--network-attachment一起使用三个 DNS flag 缺一不可。部署时 PSC 配置会以psc_interface_config传入 Agent Engine包含network_attachment与可选dns_peering_configs。重要限制PSC 配置在部署后不可变——如需变更必须删除并重新部署。前置条件与完整设置步骤参考 GCP 官方文档Gemini Enterprise Agent Platform 的 Private Service Connect interface 页面。常见问题与故障排查要点针对 Agent Runtime 部署的常见问题来自 deploy 技能 的 Troubleshooting 小节问题处理Agent Runtime 部署超时/卡住部署需 5-10 分钟检查引擎是否已创建--status轮询部署被取消/中断服务端继续构建运行agents-cli deploy --status检查进度完成后会自动补写元数据403 权限错误检查 iam.tf以实际生成路径为准cicd_runner_sa需要在目标项目具备部署与 SA 模拟角色app_sa缺少iam.serviceAccountUser会报 Cannot act as service accountSecret 访问被拒确认secretmanager.secretAccessor授予了正确的运行身份——Agent Runtime 应授予平台托管的 SAservice-PROJECT_NUMBERgcp-sa-aiplatform-re.iam.gserviceaccount.com而不是默认 compute SA部署后 Agent 报错用 Cloud Logging 按 reasoning engine 资源过滤gcloud logging read resource.typeaiplatform.googleapis.com/ReasoningEngine --projectPROJECT --limit50关于资源尺寸的调优建议同样适用于 Agent Runtime单异步进程横向扩容容器内是单个uvicorn事件循环进程吞吐来自--concurrency与--max-instances而非额外 worker仅在剖析表明事件循环或同步工具调用为 CPU 瓶颈时才提升--cpu内存约束并发每个并发请求在等待模型期间都会把完整工作集上下文窗口、历史、RAG 分块、响应缓冲留在内存中峰值 ≈ 基线 concurrency × 单请求内存。内存是第一个瓶颈只提高--concurrency不提高--memory是 OOM 的主因并发默认值偏保守8是为保护 RAG/多模态等内存密集型 Agent轻量 Agent 可在负载测试后提升到 16-32。# 4 倍吞吐示例四个参数一起缩放而不是只调一个 agents-cli deploy --cpu 4 --concurrency 16 --memory 16Gi --max-instances 20用脚手架的负载测试tests/load_test/本地或 CI/CD staging 阶段运行驱动压测观察最大延迟与内存/OOM 重启再针对性调整——最大延迟高 → 提升 concurrencyOOM → 提升 memory 或降低 concurrency。延伸阅读部署技能总览与目标选型矩阵Agent Runtime / Cloud Run / GKE 对比OAuth 用户授权 Agent 需选 Agent Runtime Gemini EnterpriseCloud Run 部署参考缩放默认值、Dockerfile、session 类型、网络GKE 部署参考Kubernetes 清单、Workload Identity、网络Terraform 模式参考自定义基础设施、IAM、状态管理已部署 Agent 的测试参考curl 示例、负载测试可观测性技能Cloud Trace、prompt-response 日志、BigQuery AnalyticsADK 代码技能事件驱动/环境 Agent 的trigger_sources模式Agent Runtime 上可通过/api透传访问/apps/{app}/trigger/*端点发布技能Gemini Enterprise 注册【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
