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:

Criteria	Agent Engine	Cloud Run	GKE
Languages	Python	Python	Python (+ others via custom containers)
Scaling	Managed auto-scaling (configurable min/max, concurrency)	Fully configurable (min/max instances, concurrency, CPU allocation)	Full Kubernetes scaling (HPA, VPA, node auto-provisioning)
Networking	VPC-SC and PSC supported	Full VPC support, direct VPC egress, IAP, ingress rules	Full Kubernetes networking
Session state	Native `VertexAiSessionService` (persistent, managed)	In-memory (dev), Cloud SQL, or Agent Engine session backend	Custom (any Kubernetes-compatible store)
Batch/event processing	Not supported	`/invoke` endpoint for Pub/Sub, Eventarc, BigQuery	Custom (Kubernetes Jobs, Pub/Sub)
Cost model	vCPU-hours + memory-hours (not billed when idle)	Per-instance-second + min instance costs	Node pool costs (always-on or auto-provisioned)
Setup complexity	Lower (managed, purpose-built for agents)	Medium (Dockerfile, Terraform, networking)	Higher (Kubernetes expertise required)
Best for	Managed infrastructure, minimal ops	Custom infra, event-driven workloads	Full 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 Engine	Cloud Run	GKE
支持语言	Python	Python	Python（通过自定义容器支持其他语言）
缩放能力	托管式自动缩放（可配置最小/最大实例数、并发数）	完全可配置（最小/最大实例数、并发数、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

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

Agent Engine

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

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

部署流程

Notify the human: "Eval scores meet thresholds and tests pass. Ready to deploy to dev?"
Wait for explicit approval
Once approved:
```
make deploy
```

IMPORTANT: Never run

make deploy

without explicit human approval.

告知相关人员："评估分数已达标，测试通过。是否准备部署到开发环境？"
等待明确的批准
获得批准后执行：
```
make deploy
```

重要提示：未经明确的人工批准，切勿运行

make deploy

。

Production Deployment — CI/CD Pipeline

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

Best for: Production applications, teams requiring staging → production promotion.

Prerequisites:

Project must NOT be in a gitignored folder
User must provide staging and production GCP project IDs
GitHub repository name and owner

Steps:

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
```

Ensure you're logged in to GitHub CLI:

bash

gh auth login  # (skip if already authenticated)

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

Push code to trigger deployments

最佳适用场景： 生产环境应用、需要从预发布环境到生产环境Promote流程的团队。

前置条件：

项目不得位于被git忽略的文件夹中
用户必须提供预发布和生产环境的GCP项目ID
GitHub仓库名称和所有者信息

步骤：

如果是原型项目，请先使用Agent Starter Pack CLI添加Terraform/CI-CD文件（完整选项请查看
```
/adk-scaffold
```
）：
bash
```
uvx agent-starter-pack enhance . --cicd-runner github_actions -y -s
```

确保已登录GitHub CLI：

bash

gh auth login  # （已登录可跳过）

执行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

推送代码以触发部署

Key

setup-cicd

Flags

setup-cicd关键参数

Flag	Description
`--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运行器

Runner	Pros	Cons
github_actions (Default)	No PAT needed, uses `gh auth` , WIF-based, fully automated	Requires GitHub CLI authentication
google_cloud_build	Native GCP integration	Requires 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:

CI (PR checks) — Triggered on pull request. Runs unit and integration tests.
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.
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

流水线包含三个阶段：

CI（PR检查） — 由拉取请求触发。运行单元测试和集成测试。
预发布环境CD — 由合并到
```
main
```
分支触发。构建容器、部署到预发布环境、运行负载测试。
路径过滤： 预发布环境CD使用
```
paths: ['app/**']
```
——仅当
```
app/
```
目录下的文件变更时才会触发。执行setup-cicd后的第一次推送不会触发预发布环境CD，除非你修改了
```
app/
```
目录下的内容。如果推送后没有任何反应，原因就在这里。
生产环境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=-

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

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/"

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 '{}'

→ 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.


> **常见错误：** 使用`{"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

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

故障排查

Issue	Solution
Terraform state locked	`terraform force-unlock -force LOCK_ID` in deployment/terraform/
GitHub Actions auth failed	Re-run `terraform apply` in CI/CD terraform dir; verify WIF pool/provider
Cloud Build authorization pending	Use `github_actions` runner instead
Resource already exists	`terraform import` (see `references/terraform-patterns.md` )
Agent Engine deploy timeout / hangs	Deployments take 5-10 min; check if engine was created (see Agent Engine Specifics)
Secret not available	Verify `secretAccessor` granted to `app_sa` (not the default compute SA)
403 on deploy	Check `deployment/terraform/iam.tf` — `cicd_runner_sa` needs deployment + SA impersonation roles in the target project
403 when testing Cloud Run	Default is `--no-allow-unauthenticated` ; include `Authorization: Bearer $(gcloud auth print-identity-token)` header
Cold starts too slow	Set `min_instance_count > 0` in Cloud Run Terraform config
Cloud Run 503 errors	Check resource limits (memory/CPU), increase `max_instance_count` , or check container crash logs
403 right after granting IAM role	IAM 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 it	Run `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输出中