Back to Details

adk-deploy-guide

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ADK Deployment Guide

ADK 部署指南

Scaffolded project? Use the 
make
commands throughout this guide — they wrap Terraform, Docker, and deployment into a tested pipeline.
No scaffold? See Quick Deploy below, or the ADK deployment docs. For production infrastructure, scaffold with 
/adk-scaffold
.
使用脚手架生成的项目？ 请在本指南中全程使用
make
命令——它们将Terraform、Docker和部署流程封装为经过测试的流水线。
未使用脚手架？ 请查看下方的快速部署，或参考ADK部署文档。 若要搭建生产环境基础设施，请使用
/adk-scaffold
生成脚手架。

Reference Files

参考文件

For deeper details, consult these reference files in 
references/
:
  • cloud-run.md
     — Scaling defaults, Dockerfile, session types, networking
  • agent-engine.md
     — deploy.py CLI, AdkApp pattern, Terraform resource, deployment metadata, CI/CD differences
  • terraform-patterns.md
     — Custom infrastructure, IAM, state management, importing resources
  • event-driven.md
     — Pub/Sub, Eventarc, BigQuery Remote Function triggers via custom 
    fast_api_app.py
    endpoints
Observability: See the adk-observability-guide skill for Cloud Trace, prompt-response logging, BigQuery Analytics, and third-party integrations.
如需更详细的信息，请查阅
references/
目录下的以下参考文件：
  • cloud-run.md
     — 缩放默认配置、Dockerfile、会话类型、网络配置
  • agent-engine.md
     — deploy.py CLI、AdkApp模式、Terraform资源、部署元数据、CI/CD差异
  • terraform-patterns.md
     — 自定义基础设施、IAM、状态管理、资源导入
  • event-driven.md
     — Pub/Sub、Eventarc、通过自定义
    fast_api_app.py
    端点触发BigQuery远程函数
可观测性： 有关Cloud Trace、提示响应日志、BigQuery分析及第三方集成的内容，请查看adk-observability-guide技能文档。

Deployment Target Decision Matrix

部署目标决策矩阵

Choose the right deployment target based on your requirements:
CriteriaAgent EngineCloud RunGKE
LanguagesPythonPythonPython (+ others via custom containers)
ScalingManaged auto-scaling (configurable min/max, concurrency)Fully configurable (min/max instances, concurrency, CPU allocation)Full Kubernetes scaling (HPA, VPA, node auto-provisioning)
NetworkingVPC-SC and PSC supportedFull VPC support, direct VPC egress, IAP, ingress rulesFull Kubernetes networking
Session stateNative 
VertexAiSessionService
(persistent, managed)		In-memory (dev), Cloud SQL, or Agent Engine session backendCustom (any Kubernetes-compatible store)
Batch/event processingNot supported
/invoke
endpoint for Pub/Sub, Eventarc, BigQuery		Custom (Kubernetes Jobs, Pub/Sub)
Cost modelvCPU-hours + memory-hours (not billed when idle)Per-instance-second + min instance costsNode pool costs (always-on or auto-provisioned)
Setup complexityLower (managed, purpose-built for agents)Medium (Dockerfile, Terraform, networking)Higher (Kubernetes expertise required)
Best forManaged infrastructure, minimal opsCustom infra, event-driven workloadsFull control, open models, GPU workloads
Ask the user which deployment target fits their needs. Each is a valid production choice with different trade-offs.
根据你的需求选择合适的部署目标：
评估标准Agent EngineCloud RunGKE
支持语言PythonPythonPython（通过自定义容器支持其他语言）
缩放能力托管式自动缩放（可配置最小/最大实例数、并发数）完全可配置（最小/最大实例数、并发数、CPU分配）完整的Kubernetes缩放能力（HPA、VPA、节点自动配置）
网络配置支持VPC-SC和PSC完整VPC支持、直接VPC出口、IAP、入口规则完整Kubernetes网络能力
会话状态原生
VertexAiSessionService
（持久化、托管式）		内存存储（开发环境）、Cloud SQL或Agent Engine会话后端自定义存储（任何兼容Kubernetes的存储系统）
批量/事件处理不支持提供
/invoke
端点用于Pub/Sub、Eventarc、BigQuery		自定义处理（Kubernetes Jobs、Pub/Sub）
成本模型vCPU小时 + 内存小时（空闲时不收费）按实例秒计费 + 最小实例成本节点池成本（始终运行或自动配置）
设置复杂度较低（托管式，专为agent打造）中等（需配置Dockerfile、Terraform、网络）较高（需要Kubernetes专业知识）
最佳适用场景托管式基础设施、最小化运维工作自定义基础设施、事件驱动型工作负载完全控制、开源模型、GPU工作负载
请询问用户哪种部署目标符合他们的需求。每种都是有效的生产环境选择，各有不同的权衡。

Quick Deploy (ADK CLI)

快速部署（ADK CLI）

For projects without Agent Starter Pack scaffolding. No Makefile, Terraform, or Dockerfile required.
bash
undefined
适用于未使用Agent Starter Pack脚手架的项目。无需Makefile、Terraform或Dockerfile。
bash
undefined

Cloud Run

Cloud Run

adk deploy cloud_run --project=PROJECT --region=REGION path/to/agent/
adk deploy cloud_run --project=PROJECT --region=REGION path/to/agent/

Agent Engine

Agent Engine

adk deploy agent_engine --project=PROJECT --region=REGION path/to/agent/
adk deploy agent_engine --project=PROJECT --region=REGION path/to/agent/

GKE (requires existing cluster)

GKE（需要现有集群）

adk deploy gke --project=PROJECT --cluster_name=CLUSTER --region=REGION path/to/agent/

All commands support `--with_ui` to deploy the ADK dev UI. Cloud Run also accepts extra `gcloud` flags after `--` (e.g., `-- --no-allow-unauthenticated`).

See `adk deploy --help` or the [ADK deployment docs](https://google.github.io/adk-docs/deploy/) for full flag reference.

> For CI/CD, observability, or production infrastructure, scaffold with `/adk-scaffold` and use the sections below.

---
adk deploy gke --project=PROJECT --cluster_name=CLUSTER --region=REGION path/to/agent/

所有命令都支持`--with_ui`参数以部署ADK开发UI。Cloud Run还支持在`--`后添加额外的`gcloud`标志（例如：`-- --no-allow-unauthenticated`）。

如需完整的参数参考，请查看`adk deploy --help`或[ADK部署文档](https://google.github.io/adk-docs/deploy/)。

> 若要实现CI/CD、可观测性或搭建生产环境基础设施，请使用`/adk-scaffold`生成脚手架并参考以下章节。

---

Dev Environment Setup & Deploy (Scaffolded Projects)

开发环境搭建与部署（脚手架生成的项目）

Setting Up Dev Infrastructure (Optional)

搭建开发环境基础设施（可选）

make setup-dev-env
runs 
terraform apply
in 
deployment/terraform/dev/
. This provisions supporting infrastructure:
  • Service accounts (
    app_sa
    for the agent, used for runtime permissions)
  • Artifact Registry repository (for container images)
  • IAM bindings (granting the app SA necessary roles)
  • Telemetry resources (Cloud Logging bucket, BigQuery dataset)
  • Any custom resources defined in 
    deployment/terraform/dev/
This step is optional — 
make deploy
works without it (Cloud Run creates the service on the fly via 
gcloud run deploy --source .
). However, running it gives you proper service accounts, observability, and IAM setup.
bash
make setup-dev-env
Note: 
make deploy
doesn't automatically use the Terraform-created 
app_sa
. Pass 
--service-account
explicitly or update the Makefile.
make setup-dev-env
会在
deployment/terraform/dev/
目录下执行
terraform apply
，用于部署配套基础设施：
  • 服务账号（
    app_sa
    用于agent，提供运行时权限）
  • Artifact Registry仓库（用于存储容器镜像）
  • IAM绑定（为app SA授予必要角色）
  • 遥测资源（Cloud Logging存储桶、BigQuery数据集）
  • deployment/terraform/dev/
    中定义的所有自定义资源
此步骤为可选——即使不执行该步骤，
make deploy
也能正常工作（Cloud Run会通过
gcloud run deploy --source .
自动创建服务）。但执行该步骤后，你将获得规范的服务账号、可观测性配置和IAM设置。
bash
make setup-dev-env
注意： 
make deploy
不会自动使用Terraform创建的
app_sa
。请显式传递
--service-account
参数或更新Makefile。

Deploying

部署流程

  1. Notify the human: "Eval scores meet thresholds and tests pass. Ready to deploy to dev?"
  2. Wait for explicit approval
  3. Once approved: 
    make deploy
IMPORTANT: Never run 
make deploy
without explicit human approval.
  1. 告知相关人员："评估分数已达标，测试通过。是否准备部署到开发环境？"
  2. 等待明确的批准
  3. 获得批准后执行：
    make deploy
重要提示：未经明确的人工批准，切勿运行
make deploy
。

Production Deployment — CI/CD Pipeline

生产环境部署 — CI/CD流水线

Best for: Production applications, teams requiring staging → production promotion.
Prerequisites:
  1. Project must NOT be in a gitignored folder
  2. User must provide staging and production GCP project IDs
  3. GitHub repository name and owner
Steps:
  1. If prototype, first add Terraform/CI-CD files using the Agent Starter Pack CLI (see 
    /adk-scaffold
    for full options):
    bash
    uvx agent-starter-pack enhance . --cicd-runner github_actions -y -s
  2. Ensure you're logged in to GitHub CLI:
    bash
    gh auth login  # (skip if already authenticated)
  3. Run setup-cicd:
    bash
    uvx agent-starter-pack setup-cicd \
  --staging-project YOUR_STAGING_PROJECT \
  --prod-project YOUR_PROD_PROJECT \
  --repository-name YOUR_REPO_NAME \
  --repository-owner YOUR_GITHUB_USERNAME \
  --auto-approve \
  --create-repository
  4. Push code to trigger deployments
最佳适用场景： 生产环境应用、需要从预发布环境到生产环境Promote流程的团队。
前置条件：
  1. 项目不得位于被git忽略的文件夹中
  2. 用户必须提供预发布和生产环境的GCP项目ID
  3. GitHub仓库名称和所有者信息
步骤：
  1. 如果是原型项目，请先使用Agent Starter Pack CLI添加Terraform/CI-CD文件（完整选项请查看
    /adk-scaffold
    ）：
    bash
    uvx agent-starter-pack enhance . --cicd-runner github_actions -y -s
  2. 确保已登录GitHub CLI：
    bash
    gh auth login  # （已登录可跳过）
  3. 执行setup-cicd命令：
    bash
    uvx agent-starter-pack setup-cicd \
  --staging-project YOUR_STAGING_PROJECT \
  --prod-project YOUR_PROD_PROJECT \
  --repository-name YOUR_REPO_NAME \
  --repository-owner YOUR_GITHUB_USERNAME \
  --auto-approve \
  --create-repository
  4. 推送代码以触发部署

Key 
setup-cicd
Flags

setup-cicd关键参数

FlagDescription
--staging-project
GCP project ID for staging environment
--prod-project
GCP project ID for production environment
--repository-name
/ 
--repository-owner
GitHub repository name and owner
--auto-approve
Skip Terraform plan confirmation prompts
--create-repository
Create the GitHub repo if it doesn't exist
--cicd-project
Separate GCP project for CI/CD infrastructure. Defaults to prod project
--local-state
Store Terraform state locally instead of in GCS (see 
references/terraform-patterns.md
)
Run 
uvx agent-starter-pack setup-cicd --help
for the full flag reference (Cloud Build options, dev project, region, etc.).
参数描述
--staging-project
预发布环境的GCP项目ID
--prod-project
生产环境的GCP项目ID
--repository-name
/ 
--repository-owner
GitHub仓库名称和所有者
--auto-approve
跳过Terraform计划确认提示
--create-repository
如果仓库不存在则创建GitHub仓库
--cicd-project
用于CI/CD基础设施的独立GCP项目。默认使用生产环境项目
--local-state
将Terraform状态存储在本地而非GCS中（请查看
references/terraform-patterns.md
）
如需完整的参数参考（包括Cloud Build选项、开发项目、区域等），请运行
uvx agent-starter-pack setup-cicd --help
。

Choosing a CI/CD Runner

选择CI/CD运行器

RunnerProsCons
github_actions (Default)No PAT needed, uses 
gh auth
, WIF-based, fully automated		Requires GitHub CLI authentication
google_cloud_buildNative GCP integrationRequires interactive browser authorization (or PAT + app installation ID for programmatic mode)
运行器优势劣势
github_actions（默认）无需PAT，使用
gh auth
，基于WIF，完全自动化		需要GitHub CLI认证
google_cloud_build原生GCP集成需要交互式浏览器授权（或使用PAT + 应用安装ID以实现程序化授权）

How Authentication Works (WIF)

认证机制（WIF）

Both runners use Workload Identity Federation (WIF) — GitHub/Cloud Build OIDC tokens are trusted by a GCP Workload Identity Pool, which grants 
cicd_runner_sa
impersonation. No long-lived service account keys needed. Terraform in 
setup-cicd
creates the pool, provider, and SA bindings automatically. If auth fails, re-run 
terraform apply
in the CI/CD Terraform directory.
两种运行器均使用工作负载身份联合（WIF）——GitHub/Cloud Build的OIDC令牌会被GCP工作负载身份池信任，从而授予
cicd_runner_sa
的 impersonation权限。无需使用长期服务账号密钥。setup-cicd中的Terraform会自动创建身份池、提供者和SA绑定。如果认证失败，请重新在CI/CD Terraform目录中运行
terraform apply
。

CI/CD Pipeline Stages

CI/CD流水线阶段

The pipeline has three stages:
  1. CI (PR checks) — Triggered on pull request. Runs unit and integration tests.
  2. Staging CD — Triggered on merge to 
    main
    . Builds container, deploys to staging, runs load tests.
    Path filter: Staging CD uses 
    paths: ['app/**']
    — it only triggers when files under 
    app/
    change. The first push after 
    setup-cicd
    won't trigger staging CD unless you modify something in 
    app/
    . If nothing happens after pushing, this is why.
  3. Production CD — Triggered after successful staging deploy via 
    workflow_run
    . Might require manual approval before deploying to production.
    Approving: Go to GitHub Actions → the production workflow run → click "Review deployments" → approve the pending 
    production
    environment. This is GitHub's environment protection rules, not a custom mechanism.
IMPORTANT: 
setup-cicd
creates infrastructure but doesn't deploy automatically. Terraform configures all required GitHub secrets and variables (WIF credentials, project IDs, service accounts). Push code to trigger the pipeline:
bash
git add . && git commit -m "Initial agent implementation"
git push origin main
To approve production deployment:
bash
undefined
流水线包含三个阶段：
  1. CI（PR检查） — 由拉取请求触发。运行单元测试和集成测试。
  2. 预发布环境CD — 由合并到
    main
    分支触发。构建容器、部署到预发布环境、运行负载测试。
    路径过滤： 预发布环境CD使用
    paths: ['app/**']
    ——仅当
    app/
    目录下的文件变更时才会触发。执行setup-cicd后的第一次推送不会触发预发布环境CD，除非你修改了
    app/
    目录下的内容。如果推送后没有任何反应，原因就在这里。
  3. 生产环境CD — 预发布环境部署成功后，通过
    workflow_run
    触发。部署到生产环境前可能需要人工批准。
    批准方式： 进入GitHub Actions → 生产环境工作流运行记录 → 点击“Review deployments” → 批准待处理的
    production
    环境。这是GitHub的环境保护规则，而非自定义机制。
重要提示：
setup-cicd
会创建基础设施，但不会自动触发部署。Terraform会配置所有必要的GitHub密钥和变量（WIF凭证、项目ID、服务账号）。推送代码以触发流水线：
bash
git add . && git commit -m "Initial agent implementation"
git push origin main
批准生产环境部署的方式：
bash
undefined

GitHub Actions: Approve via repository Actions tab (environment protection rules)

GitHub Actions：通过仓库的Actions标签页批准（环境保护规则）

Cloud Build: Find pending build and approve

Cloud Build：找到待处理的构建任务并批准

gcloud builds list --project=PROD_PROJECT --region=REGION --filter="status=PENDING" gcloud builds approve BUILD_ID --project=PROD_PROJECT

---
gcloud builds list --project=PROD_PROJECT --region=REGION --filter="status=PENDING" gcloud builds approve BUILD_ID --project=PROD_PROJECT

---

Cloud Run Specifics

Cloud Run 专属配置

For detailed infrastructure configuration (scaling defaults, Dockerfile, FastAPI endpoints, session types, networking), see 
references/cloud-run.md
. For ADK docs on Cloud Run deployment, fetch 
https://google.github.io/adk-docs/deploy/cloud-run/index.md
.
如需详细的基础设施配置（缩放默认值、Dockerfile、FastAPI端点、会话类型、网络），请查看
references/cloud-run.md
。有关Cloud Run部署的ADK文档，请访问
https://google.github.io/adk-docs/deploy/cloud-run/index.md
。

Agent Engine Specifics

Agent Engine 专属配置

Agent Engine is a managed Vertex AI service for deploying Python ADK agents. Uses source-based deployment (no Dockerfile) via 
deploy.py
and the 
AdkApp
class.
No 
gcloud
CLI exists for Agent Engine. Deploy via 
deploy.py
or 
adk deploy agent_engine
. Query via the Python 
vertexai.Client
SDK.
Deployments can take 5-10 minutes. If 
make deploy
times out, check if the engine was created and manually populate 
deployment_metadata.json
with the engine resource ID (see reference for details).
For detailed infrastructure configuration (deploy.py flags, AdkApp pattern, Terraform resource, deployment metadata, session/artifact services, CI/CD differences), see 
references/agent-engine.md
. For ADK docs on Agent Engine deployment, fetch 
https://google.github.io/adk-docs/deploy/agent-engine/index.md
.
Agent Engine是托管式Vertex AI服务，用于部署Python ADK agent。通过
deploy.py
和
AdkApp
类实现基于源码的部署（无需Dockerfile）。
目前没有针对Agent Engine的
gcloud
CLI。 请通过
deploy.py
或
adk deploy agent_engine
进行部署。通过Python 
vertexai.Client
SDK进行查询。
部署过程可能需要5-10分钟。如果
make deploy
超时，请检查引擎是否已创建，并手动将引擎资源ID填入
deployment_metadata.json
（详情请参考相关文档）。
如需详细的基础设施配置（deploy.py参数、AdkApp模式、Terraform资源、部署元数据、会话/工件服务、CI/CD差异），请查看
references/agent-engine.md
。有关Agent Engine部署的ADK文档，请访问
https://google.github.io/adk-docs/deploy/agent-engine/index.md
。

Service Account Architecture

服务账号架构

Scaffolded projects use two service accounts:
  • app_sa
     (per environment) — Runtime identity for the deployed agent. Roles defined in 
    deployment/terraform/iam.tf
    .
  • cicd_runner_sa
     (CI/CD project) — CI/CD pipeline identity (GitHub Actions / Cloud Build). Lives in the CI/CD project (defaults to prod project), needs permissions in both staging and prod projects.
Check 
deployment/terraform/iam.tf
for exact role bindings. Cross-project permissions (Cloud Run service agents, artifact registry access) are also configured there.
Common 403 errors:
  • "Permission denied on Cloud Run" → 
    cicd_runner_sa
    missing deployment role in the target project
  • "Cannot act as service account" → Missing 
    iam.serviceAccountUser
    binding on 
    app_sa
  • "Secret access denied" → 
    app_sa
    missing 
    secretmanager.secretAccessor
  • "Artifact Registry read denied" → Cloud Run service agent missing read access in CI/CD project
脚手架生成的项目使用两个服务账号：
  • app_sa
    （每个环境一个）—— 已部署agent的运行时身份。角色定义在
    deployment/terraform/iam.tf
    中。
  • cicd_runner_sa
    （CI/CD项目）—— CI/CD流水线的身份（GitHub Actions / Cloud Build）。位于CI/CD项目中（默认使用生产环境项目），需要在预发布和生产环境项目中拥有权限。
请查看
deployment/terraform/iam.tf
以获取确切的角色绑定信息。跨项目权限（Cloud Run服务代理、Artifact Registry访问）也在该文件中配置。
常见403错误：
  • "Permission denied on Cloud Run" → 
    cicd_runner_sa
    在目标项目中缺少部署角色
  • "Cannot act as service account" → 
    app_sa
    缺少
    iam.serviceAccountUser
    绑定
  • "Secret access denied" → 
    app_sa
    缺少
    secretmanager.secretAccessor
    角色
  • "Artifact Registry read denied" → Cloud Run服务代理在CI/CD项目中缺少读取权限

Secret Manager (for API Credentials)

Secret Manager（用于API凭证）

Instead of passing sensitive keys as environment variables, use GCP Secret Manager.
bash
undefined
请勿将敏感密钥作为环境变量传递，请使用GCP Secret Manager。
bash
undefined

Create a secret

创建密钥

echo -n "YOUR_API_KEY" | gcloud secrets create MY_SECRET_NAME --data-file=-
echo -n "YOUR_API_KEY" | gcloud secrets create MY_SECRET_NAME --data-file=-

Update an existing secret

更新现有密钥

echo -n "NEW_API_KEY" | gcloud secrets versions add MY_SECRET_NAME --data-file=-

**Grant access:** For Cloud Run, grant `secretmanager.secretAccessor` to `app_sa`. For Agent Engine, grant it to the platform-managed SA (`service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com`).

**Pass secrets at deploy time (Agent Engine):**
```bash
make deploy SECRETS="API_KEY=my-api-key,DB_PASS=db-password:2"
Format: 
ENV_VAR=SECRET_ID
or 
ENV_VAR=SECRET_ID:VERSION
(defaults to latest). Access in code via 
os.environ.get("API_KEY")
.
echo -n "NEW_API_KEY" | gcloud secrets versions add MY_SECRET_NAME --data-file=-

**授予访问权限：** 对于Cloud Run，请为`app_sa`授予`secretmanager.secretAccessor`角色。对于Agent Engine，请为平台托管的SA（`service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com`）授予该角色。

**部署时传递密钥（Agent Engine）：**
```bash
make deploy SECRETS="API_KEY=my-api-key,DB_PASS=db-password:2"
格式：
ENV_VAR=SECRET_ID
或 
ENV_VAR=SECRET_ID:VERSION
（默认使用最新版本）。在代码中通过
os.environ.get("API_KEY")
访问。

Observability

可观测性

See the adk-observability-guide skill for observability configuration (Cloud Trace, prompt-response logging, BigQuery Analytics, third-party integrations).
有关可观测性配置（Cloud Trace、提示响应日志、BigQuery分析、第三方集成）的内容，请查看adk-observability-guide技能文档。

Testing Your Deployed Agent

测试已部署的Agent

Agent Engine Deployment

Agent Engine 部署测试

Option 1: Testing Notebook
bash
jupyter notebook notebooks/adk_app_testing.ipynb
Option 2: Python Script
python
import json
import vertexai

with open("deployment_metadata.json") as f:
    engine_id = json.load(f)["remote_agent_engine_id"]

client = vertexai.Client(location="us-central1")
agent = client.agent_engines.get(name=engine_id)

async for event in agent.async_stream_query(message="Hello!", user_id="test"):
    print(event)
Option 3: Playground
bash
make playground
选项1：测试Notebook
bash
jupyter notebook notebooks/adk_app_testing.ipynb
选项2：Python脚本
python
import json
import vertexai

with open("deployment_metadata.json") as f:
    engine_id = json.load(f)["remote_agent_engine_id"]

client = vertexai.Client(location="us-central1")
agent = client.agent_engines.get(name=engine_id)

async for event in agent.async_stream_query(message="Hello!", user_id="test"):
    print(event)
选项3：Playground
bash
make playground

Cloud Run Deployment

Cloud Run 部署测试

Auth required by default. Cloud Run deploys with 
--no-allow-unauthenticated
, so all requests need an 
Authorization: Bearer
header with an identity token. Getting a 403? You're likely missing this header. To allow public access, redeploy with 
--allow-unauthenticated
.
bash
SERVICE_URL="https://SERVICE_NAME-PROJECT_NUMBER.REGION.run.app"
AUTH="Authorization: Bearer $(gcloud auth print-identity-token)"
默认需要认证。 Cloud Run默认使用
--no-allow-unauthenticated
部署，因此所有请求都需要带有身份令牌的
Authorization: Bearer
头。如果收到403错误，很可能是缺少该头。如需允许公共访问，请重新部署并添加
--allow-unauthenticated
参数。
bash
SERVICE_URL="https://SERVICE_NAME-PROJECT_NUMBER.REGION.run.app"
AUTH="Authorization: Bearer $(gcloud auth print-identity-token)"

Test health endpoint

测试健康检查端点

curl -H "$AUTH" "$SERVICE_URL/"
curl -H "$AUTH" "$SERVICE_URL/"

Step 1: Create a session (required before sending messages)

步骤1：创建会话（发送消息前必须执行）

curl -X POST "$SERVICE_URL/apps/app/users/test-user/sessions"
-H "Content-Type: application/json"
-H "$AUTH"
-d '{}'
curl -X POST "$SERVICE_URL/apps/app/users/test-user/sessions"
-H "Content-Type: application/json"
-H "$AUTH"
-d '{}'

→ returns JSON with "id" — use this as SESSION_ID below

→ 返回包含"id"的JSON数据——请将其作为下方的SESSION_ID使用

Step 2: Send a message via SSE streaming

步骤2：通过SSE流发送消息

curl -X POST "$SERVICE_URL/run_sse"
-H "Content-Type: application/json"
-H "$AUTH"
-d '{ "app_name": "app", "user_id": "test-user", "session_id": "SESSION_ID", "new_message": {"role": "user", "parts": [{"text": "Hello!"}]} }'

> **Common mistake:** Using `{"message": "Hello!", "user_id": "...", "session_id": "..."}` returns `422 Field required`. The ADK HTTP server expects the `new_message` / `parts` schema shown above, and the session must already exist.
curl -X POST "$SERVICE_URL/run_sse"
-H "Content-Type: application/json"
-H "$AUTH"
-d '{ "app_name": "app", "user_id": "test-user", "session_id": "SESSION_ID", "new_message": {"role": "user", "parts": [{"text": "Hello!"}]} }'

> **常见错误：** 使用`{"message": "Hello!", "user_id": "...", "session_id": "..."}`会返回`422 Field required`。ADK HTTP服务器需要上述`new_message` / `parts`格式的请求体，且会话必须已存在。

Load Tests

负载测试

bash
make load-test
See 
tests/load_test/README.md
for configuration, default settings, and CI/CD integration details.
bash
make load-test
配置、默认设置和CI/CD集成详情请查看
tests/load_test/README.md
。

Deploying with a UI (IAP)

带UI的部署（IAP）

To expose your agent with a web UI protected by Google identity authentication:
bash
undefined
如需部署受Google身份认证保护的Web UI agent：
bash
undefined

Deploy with IAP (built-in framework UI)

部署带IAP的agent（内置框架UI）

make deploy IAP=true
make deploy IAP=true

Deploy with custom frontend on a different port

在不同端口部署自定义前端

make deploy IAP=true PORT=5173

IAP (Identity-Aware Proxy) secures the Cloud Run service — only authorized Google accounts can access it. After deploying, grant user access via the [Cloud Console IAP settings](https://cloud.google.com/run/docs/securing/identity-aware-proxy-cloud-run#manage_user_or_group_access).

For Agent Engine with a custom frontend, use a **decoupled deployment** — deploy the frontend separately to Cloud Run or Cloud Storage, connecting to the Agent Engine backend API.

---
make deploy IAP=true PORT=5173

IAP（身份感知代理）会保护Cloud Run服务——只有授权的Google账号才能访问。部署完成后，请通过[Cloud Console IAP设置](https://cloud.google.com/run/docs/securing/identity-aware-proxy-cloud-run#manage_user_or_group_access)授予用户访问权限。

对于带有自定义前端的Agent Engine，请使用**解耦部署**——将前端单独部署到Cloud Run或Cloud Storage，连接到Agent Engine后端API。

---

Rollback & Recovery

回滚与恢复

The primary rollback mechanism is git-based: fix the issue, commit, and push to 
main
. The CI/CD pipeline will automatically build and deploy the new version through staging → production.
For immediate Cloud Run rollback without a new commit, use revision traffic shifting:
bash
gcloud run revisions list --service=SERVICE_NAME --region=REGION
gcloud run services update-traffic SERVICE_NAME \
  --to-revisions=REVISION_NAME=100 --region=REGION
Agent Engine doesn't support revision-based rollback — fix and redeploy via 
make deploy
.
主要的回滚机制是基于git的：修复问题、提交、推送到
main
分支。CI/CD流水线会自动构建并通过预发布→生产环境流程部署新版本。
如需在不提交新代码的情况下立即回滚Cloud Run版本，请使用修订版流量转移：
bash
gcloud run revisions list --service=SERVICE_NAME --region=REGION
gcloud run services update-traffic SERVICE_NAME \
  --to-revisions=REVISION_NAME=100 --region=REGION
Agent Engine不支持基于修订版的回滚——请修复问题后通过
make deploy
重新部署。

Custom Infrastructure (Terraform)

自定义基础设施（Terraform）

For custom infrastructure patterns (Pub/Sub, BigQuery, Eventarc, Cloud SQL, IAM), consult 
references/terraform-patterns.md
for:
  • Where to put custom Terraform files (dev vs CI/CD)
  • Resource examples (Pub/Sub, BigQuery, Eventarc triggers)
  • IAM bindings for custom resources
  • Terraform state management (remote vs local, importing resources)
  • Common infrastructure patterns
如需自定义基础设施模式（Pub/Sub、BigQuery、Eventarc、Cloud SQL、IAM），请查看
references/terraform-patterns.md
以获取以下信息：
  • 自定义Terraform文件的存放位置（开发环境 vs CI/CD）
  • 资源示例（Pub/Sub、BigQuery、Eventarc触发器）
  • 自定义资源的IAM绑定
  • Terraform状态管理（远程 vs 本地、资源导入）
  • 常见基础设施模式

Troubleshooting

故障排查

IssueSolution
Terraform state locked
terraform force-unlock -force LOCK_ID
in deployment/terraform/
GitHub Actions auth failedRe-run 
terraform apply
in CI/CD terraform dir; verify WIF pool/provider
Cloud Build authorization pendingUse 
github_actions
runner instead
Resource already exists
terraform import
(see 
references/terraform-patterns.md
)
Agent Engine deploy timeout / hangsDeployments take 5-10 min; check if engine was created (see Agent Engine Specifics)
Secret not availableVerify 
secretAccessor
granted to 
app_sa
(not the default compute SA)
403 on deployCheck 
deployment/terraform/iam.tf
— 
cicd_runner_sa
needs deployment + SA impersonation roles in the target project
403 when testing Cloud RunDefault is 
--no-allow-unauthenticated
; include 
Authorization: Bearer $(gcloud auth print-identity-token)
header
Cold starts too slowSet 
min_instance_count > 0
in Cloud Run Terraform config
Cloud Run 503 errorsCheck resource limits (memory/CPU), increase 
max_instance_count
, or check container crash logs
403 right after granting IAM roleIAM propagation is not instant — wait a couple of minutes before retrying. Don't keep re-granting the same role
Resource seems missing but Terraform created itRun 
terraform state list
to check what Terraform actually manages. Resources created via 
null_resource
+ 
local-exec
(e.g., BQ linked datasets) won't appear in 
gcloud
CLI output
问题解决方案
Terraform状态被锁定在deployment/terraform/目录下执行
terraform force-unlock -force LOCK_ID
GitHub Actions认证失败重新在CI/CD terraform目录下运行
terraform apply
；验证WIF池/提供者配置
Cloud Build授权待处理改用
github_actions
运行器
资源已存在使用
terraform import
（请查看
references/terraform-patterns.md
）
Agent Engine部署超时/挂起部署需要5-10分钟；检查引擎是否已创建（请查看Agent Engine专属配置章节）
密钥不可用确认
secretAccessor
角色已授予
app_sa
（而非默认compute SA）
部署时出现403错误检查
deployment/terraform/iam.tf
——
cicd_runner_sa
在目标项目中需要部署权限和SA impersonation角色
测试Cloud Run时出现403错误默认设置为
--no-allow-unauthenticated
；请添加
Authorization: Bearer $(gcloud auth print-identity-token)
请求头
冷启动过慢在Cloud Run Terraform配置中设置
min_instance_count > 0
Cloud Run出现503错误检查资源限制（内存/CPU）、增加
max_instance_count
或查看容器崩溃日志
授予IAM角色后立即出现403错误IAM权限传播并非即时生效——请等待几分钟后重试。请勿重复授予相同角色
Terraform显示已创建资源，但实际找不到运行
terraform state list
查看Terraform实际管理的资源。通过
null_resource
+ 
local-exec
创建的资源（例如BQ关联数据集）不会出现在
gcloud
CLI输出中