企业官网建设流程全解析

使用 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 Runtime（Agent 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 部署架构：容器即 Agent

Agent Runtime（即 Vertex AI Agent Engine / Agent Engine 的新名称，CLI 中统一使用--deployment-target agent_runtime）是 Google Cloud Vertex AI 提供的托管式 Agent 部署服务。与 Cloud Run 自行构建镜像再gcloud run deploy不同，Agent Runtime 采用容器化部署模型：

1. agents-cli deploy将项目文件打包成源包；
2. Agent Engine 根据项目根目录的Dockerfile（必需）构建容器镜像；
3. 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(web=True, lifespan=...)构建 FastAPIapp（见 fast_api_app.py）。其组装过程如下：

• lifespan 构建一个Runner：使用共享的 session/artifact 服务（来自app_utils/services.py，注册在shared://URI 下），并设置auto_create_session=True（见 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 表面：

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 即可访问 Agent

Agent 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 流水线调用的是同一个命令。

部署流程三步：

1. agents-cli deploy打包项目文件（遵循.gcloudignore/.gitignore）；
2. Agent Engine 构建容器镜像并创建/更新 Agent Runtime 实例；
3. 写入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_VERTEXAI=true与GOOGLE_CLOUD_LOCATION=global（见 agent_runtime.py）。

关键部署 Flag

非交互模式注意：当项目通过自动解析获得（未传--project）时，交互模式会弹出确认提示。Agent 通常运行在非交互模式下，因此依赖自动项目解析时必须显式传--no-confirm-project。

超时恢复：--no-wait 与 --status

Agent Runtime 部署可能耗时5-10 分钟，容易超过命令超时。即使部署命令被取消或超时，服务端的部署仍会继续：

# 不阻塞地发起部署 agents-cli deploy --no-wait # 稍后检查进度（建议每 60 秒轮询一次，直到完成或失败） agents-cli deploy --status

该机制在源码中的实现位于 _operation.py：部署启动时（无论同步还是--no-wait），长时操作（LRO）名称、项目、区域、部署目标与开始时间会以pending_operation字段写入deployment_metadata.json；deploy --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_engine

Agent Runtime 在 Terraform 中使用google_vertex_ai_reasoning_engine资源，位于 single-project/service.tf（CI/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_LOCATION=global、 # GOOGLE_GENAI_USE_VERTEXAI=True、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.000+00:00" }

源码中的write_deployment_metadata()（见 agent_runtime.py）还会额外写入language字段（来自项目配置），并按 UTC 记录 ISO 时间戳。

该文件的用途：

• 后续部署：判断是 update 还是 create（按显示名匹配现有引擎）；
• agents-cli run --url：远程查询已部署的 Agent；
• agents-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 Runtime 没有gcloudCLI 可用。部署只能通过agents-cli deploy，查询通过 Pythonagentplatform.ClientSDK（或agents-cli run --url）。

Playground 与远程测试

# 本地模式（使用本地 Agent 实例） agents-cli playground # 远程查询已部署的 Agent Runtime（ADK 项目；否则用 --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必须搭配--mode：adk走 ADK 流式 API（:streamQuery），a2a走 A2A 协议；
• 加-v输出完整 JSON 事件负载；
• 认证自动探测：通过 Google Cloud 凭据获取 token（Agent 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 SDK）

import agentplatform client = agentplatform.Client(location="us-east1") agent = client.agent_engines.get(name="projects/PROJECT/locations/LOCATION/reasoningEngines/ENGINE_ID") async for event in agent.async_stream_query(message="Hello!", user_id="test"): print(event)

Session 与 Artifact 服务

本小节前两段是ADK 脚手架的 session/artifact 装配方式；末尾的环境变量来源对任何框架均适用。

Session：Agent 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 deploy（CLI 的 deploy/agent_runtime.py），Terraform 托管部署来自 single-project/service.tf（或cicd/变体）。当前值以对应文件为准，模板中可见OTEL_SERVICE_NAME、OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=NO_CONTENT、ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false、GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true等遥测默认值。

Memory Bank：跨会话记忆

要在 Agent Runtime 上启用跨会话记忆，请通过context_spec配置memory_bank_config。完整模式参考 ADK 的cross-session-memory示例（google/adk-samples仓库core/python/cross-session-memory目录）。

Networking：PSC 接口（私有网络连通）

Agent Runtime默认无法访问你的 VPC。启用私有连通的步骤：

1. 创建 network attachment（VPC 网络附件）；
2. 部署时加--network-attachment；
3. 需要私有 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）：

• 单异步进程，横向扩容：容器内是单个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 重启，再针对性调整——最大延迟高 → 提升 concurrency；OOM → 提升 memory 或降低 concurrency。

延伸阅读

• 部署技能总览与目标选型矩阵（Agent Runtime / Cloud Run / GKE 对比，OAuth 用户授权 Agent 需选 Agent Runtime + Gemini Enterprise）
• Cloud Run 部署参考（缩放默认值、Dockerfile、session 类型、网络）
• GKE 部署参考（Kubernetes 清单、Workload Identity、网络）
• Terraform 模式参考（自定义基础设施、IAM、状态管理）
• 已部署 Agent 的测试参考（curl 示例、负载测试）
• 可观测性技能（Cloud Trace、prompt-response 日志、BigQuery Analytics）
• ADK 代码技能（事件驱动/环境 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