部署到 Cloud Run¶

Supported in ADKPythonTypeScriptGoJava

Cloud Run 是一个完全托管的平台，使你能够直接在 Google 可扩展基础设施上运行代码。

要部署你的智能体，你可以使用 adk deploy cloud_run 命令 （推荐用于 Python），或通过 Cloud Run 使用 gcloud run deploy 命令。

智能体示例¶

对于每个命令，我们将引用在 LLM 智能体页面上定义的 Capital Agent 示例。我们假设它在一个目录中（例如：capital_agent）。

继续之前，请确认你的智能体代码配置如下：

PythonTypeScriptGoJava

智能体代码在名为 agent.py 的文件中，位于你的智能体目录下。
你的智能体变量命名为 root_agent。
你的智能体目录下有 __init__.py，内容为 from . import agent。
你的智能体目录下有 requirements.txt 文件。

智能体代码位于项目目录下名为 agent.ts 的文件中。
你的智能体变量命名为 rootAgent 并且已被导出。
你的智能体目录下有 package.json 文件，并包含 @google/adk 及其他依赖项。

应用程序的入口点（main 包和 main() 函数）位于单个 Go 文件中。使用 main.go 是一个强有力的惯例。
你的智能体实例被传递给启动器配置，通常使用 agent.NewSingleLoader(yourAgent)。
你的项目目录下有 go.mod 和 go.sum 文件用于管理依赖项。

有关更多详细信息，请参阅以下部分。你还可以在 Github 仓库中找到一个示例应用。

智能体代码在名为 CapitalAgent.java 的文件中，位于你的智能体目录内。
你的智能体变量是全局的，遵循格式 public static final BaseAgent ROOT_AGENT。
你的智能体定义存在于静态类方法中。

有关更多详细信息，请参阅以下部分。你还可以在 Github 仓库中找到一个示例应用。

环境变量¶

按照设置和安装指南中描述的设置环境变量。

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_CLOUD_LOCATION=us-central1 # 或你偏好的位置
export GOOGLE_GENAI_USE_ENTERPRISE=True

如需了解更多关于从 ADK 智能体连接到 Google Cloud 的信息，请参阅连接到 Google Cloud 和 Agent Platform。

前提条件¶

你应该拥有一个 Google Cloud 项目。你需要知道以下信息：
1. 项目名称（即"my-project"）
2. 项目位置（即"us-central1"）
3. 服务账号（即"1234567890-compute@developer.gserviceaccount.com"）
4. GOOGLE_API_KEY

密钥¶

请确保你已创建一个可被你的服务账号读取的密钥。

Cloud Build 权限¶

由于 adk deploy 命令使用 Google Cloud Build 来自动化构建过程，你必须为默认计算服务账号设置使用 Cloud Build 的权限。以下命令示例展示了如何授予此权限：

gcloud projects add-iam-policy-binding [PROJECT_ID] \
    --member="serviceAccount:[PROJECT_NUMBER]-compute@developer.gserviceaccount.com" \
    --role="roles/cloudbuild.builds.builder"

GOOGLE_API_KEY 密钥条目¶

你可以手动创建密钥，也可以使用命令行工具：

echo "<<在此处填入你的 GOOGLE_API_KEY>>" | gcloud secrets create GOOGLE_API_KEY --project=my-project --data-file=-

读取权限¶

你应该为你的服务账号授予读取此密钥的适当权限。

gcloud secrets add-iam-policy-binding GOOGLE_API_KEY --member="serviceAccount:1234567890-compute@developer.gserviceaccount.com" --role="roles/secretmanager.secretAccessor" --project=my-project

部署载荷¶

当你将 ADK 智能体工作流部署到 Google Cloud Run 时，以下内容将被上传到服务中：

你的 ADK 智能体代码
你的 ADK 智能体代码中声明的所有依赖项
你的智能体使用的 ADK API 服务器代码版本

默认部署不包含 ADK Web 用户界面库，除非你在部署设置中指定了它，例如 adk deploy cloud_run 命令的 --with_ui 选项。

部署命令¶

Python - adk CLIPython - gcloud CLITypeScript - adk CLIGo - adkgo CLIJava - gcloud CLI

adk CLI¶

adk deploy cloud_run 命令将你的智能体代码部署到 Google Cloud Run。

确保你已通过 Google Cloud 认证（gcloud auth login 和 gcloud config set project <your-project-id>）。

设置环境变量¶

可选但推荐：设置环境变量可以使部署命令更简洁。

# 设置你的 Google Cloud 项目 ID
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

# 设置你期望的 Google Cloud 位置
export GOOGLE_CLOUD_LOCATION="us-central1" # 示例位置

# 设置你的智能体代码目录路径
export AGENT_PATH="./capital_agent" # 假设 capital_agent 在当前目录中

# 设置 Cloud Run 服务名称（可选）
export SERVICE_NAME="capital-agent-service"

# 设置应用名称（可选）
export APP_NAME="capital_agent_app"

命令用法¶

最简命令¶

adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
$AGENT_PATH

包含可选标志的完整命令¶

adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH

参数¶

AGENT_PATH：（必填）位置参数，指定包含你的智能体源代码的目录路径（例如示例中的 $AGENT_PATH，或 capital_agent/）。该目录必须至少包含一个 __init__.py 和你的主智能体文件（例如 agent.py）。

选项¶

--project TEXT：（必填）你的 Google Cloud 项目 ID（例如 $GOOGLE_CLOUD_PROJECT）。
--region TEXT：（必填）用于部署的 Google Cloud 位置（例如 $GOOGLE_CLOUD_LOCATION、us-central1）。
--service_name TEXT：（可选）Cloud Run 服务的名称（例如 $SERVICE_NAME）。默认为 adk-default-service-name。
--app_name TEXT：（可选）ADK API 服务器的应用名称（例如 $APP_NAME）。默认为 AGENT_PATH 指定的目录名称（例如如果 AGENT_PATH 是 ./capital_agent，则默认为 capital_agent）。
--agent_engine_id TEXT：（可选）如果你通过 Agent Runtime 使用托管会话服务，请在此处提供其资源 ID。
--port INTEGER：（可选）ADK API 服务器将在容器内监听的端口号。默认为 8000。
--with_ui：（可选）如果包含此标志，则在部署智能体 API 服务器的同时部署 ADK 开发 UI。默认情况下，只部署 API 服务器。
--temp_folder TEXT：（可选）指定用于存储部署过程中生成的中间文件的目录。默认为系统临时目录中带时间戳的文件夹。（注意：除非排查问题，否则通常不需要此选项。）
--help：显示帮助信息并退出。

传递 gcloud CLI 参数¶

要通过 adk deploy cloud_run 命令传递特定的 gcloud 标志，请在 ADK 参数之后使用双破折号分隔符（--）。-- 之后的任何标志（ADK 管理的除外）将直接传递给底层的 gcloud 命令。

语法示例¶

adk deploy cloud_run [ADK_FLAGS] -- [GCLOUD_FLAGS]

示例¶

adk deploy cloud_run --project=[PROJECT_ID] --region=[REGION] path/to/my_agent    -- --no-allow-unauthenticated --min-instances=2

经过身份验证的访问¶

在部署过程中，你可能会收到提示：Allow unauthenticated invocations to [your-service-name] (y/N)?。

输入 y 以允许无需身份验证即可公开访问你的智能体 API 端点。
输入 N（或按 Enter 使用默认值）以要求身份验证（例如，使用"测试你的智能体"部分所示的身份令牌）。

命令成功执行后，将把你的智能体部署到 Cloud Run 并提供已部署服务的 URL。

Python 的 gcloud CLI¶

你也可以使用标准的 gcloud run deploy 命令和 Dockerfile 进行部署。与 adk 命令相比，此方法需要更多手动设置，但提供了更大的灵活性，特别是当你想将智能体嵌入自定义 FastAPI 应用程序时。

确保你已通过 Google Cloud 认证（gcloud auth login 和 gcloud config set project <your-project-id>）。

项目结构¶

按如下方式组织你的项目文件：

your-project-directory/
├── capital_agent/
│   ├── __init__.py
│   └── agent.py       # 你的智能体代码（参见"智能体示例"标签页）
├── main.py            # FastAPI 应用入口
├── requirements.txt   # Python 依赖项
└── Dockerfile         # 容器构建指令

在 your-project-directory/ 的根目录下创建以下文件（main.py、requirements.txt、Dockerfile）。

代码文件¶

此文件使用 ADK 中的 get_fast_api_app() 来设置 FastAPI 应用程序：

main.py

import os

import uvicorn
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app

# 获取 main.py 所在的目录
AGENT_DIR = os.path.dirname(os.path.abspath(__file__))
# 示例会话服务 URI（例如 SQLite）
# 注意：使用 'sqlite+aiosqlite' 而不是 'sqlite'，因为 DatabaseSessionService 需要异步驱动
SESSION_SERVICE_URI = "sqlite+aiosqlite:///./sessions.db"
# CORS 的示例允许来源
ALLOWED_ORIGINS = ["http://localhost", "http://localhost:8080", "*"]
# 如果你打算提供 Web 界面则设置为 True，否则为 False
SERVE_WEB_INTERFACE = True

# 调用函数获取 FastAPI 应用实例
# 确保智能体目录名称（'capital_agent'）与你的智能体文件夹匹配
app: FastAPI = get_fast_api_app(
    agents_dir=AGENT_DIR,
    session_service_uri=SESSION_SERVICE_URI,
    allow_origins=ALLOWED_ORIGINS,
    web=SERVE_WEB_INTERFACE,
)

# 如果需要，你可以在下面添加更多 FastAPI 路由或配置
# 示例：
# @app.get("/hello")
# async def read_root():
#     return {"Hello": "World"}

if __name__ == "__main__":
    # 使用 Cloud Run 提供的 PORT 环境变量，默认为 8080
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

注意：我们将 agent_dir 指定为 main.py 所在的目录，并使用 os.environ.get("PORT", 8080) 以兼容 Cloud Run。

列出必要的 Python 包：

requirements.txt

google-adk
# 添加你的智能体所需的其他依赖项

定义容器镜像：

Dockerfile

FROM python:3.13-slim
WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

RUN adduser --disabled-password --gecos "" myuser && \
    chown -R myuser:myuser /app

COPY . .

USER myuser

ENV PATH="/home/myuser/.local/bin:$PATH"

CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port $PORT"]

定义多个智能体¶

你可以在同一个 Cloud Run 实例中定义和部署多个智能体，方法是在 your-project-directory/ 的根目录下创建单独的文件夹。每个文件夹代表一个智能体，并且必须在其配置中定义一个 root_agent。

示例结构：

your-project-directory/
├── capital_agent/
│   ├── __init__.py
│   └── agent.py       # 包含 `root_agent` 定义
├── population_agent/
│   ├── __init__.py
│   └── agent.py       # 包含 `root_agent` 定义
└── ...

使用 `gcloud` 部署¶

在终端中导航到 your-project-directory。

gcloud run deploy capital-agent-service \
--source . \
--region $GOOGLE_CLOUD_LOCATION \
--project $GOOGLE_CLOUD_PROJECT \
--allow-unauthenticated \
--set-env-vars="GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT,GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION,GOOGLE_GENAI_USE_ENTERPRISE=$GOOGLE_GENAI_USE_ENTERPRISE"
# 添加你的智能体可能需要的其他必要环境变量

capital-agent-service：你要为 Cloud Run 服务指定的名称。
--source .：指示 gcloud 从当前目录中的 Dockerfile 构建容器镜像。
--region：指定部署区域。
--project：指定 GCP 项目。
--allow-unauthenticated：允许公开访问该服务。对于私有服务，请移除此标志。
--set-env-vars：将必要的环境变量传递给正在运行的容器。确保你包含了 ADK 和你的智能体所需的所有变量（如果不使用应用默认凭据，则包括 API 密钥等）。

gcloud 将构建 Docker 镜像，将其推送到 Google Artifact Registry，并将其部署到 Cloud Run。完成后，它将输出已部署服务的 URL。

有关部署选项的完整列表，请参阅 gcloud run deploy 参考文档。

adk CLI¶

adk deploy cloud_run 命令将你的智能体代码部署到 Google Cloud Run。

确保你已通过 Google Cloud 认证（gcloud auth login 和 gcloud config set project <your-project-id>）。

设置环境变量¶

可选但推荐：设置环境变量可以使部署命令更简洁。

# 设置你的 Google Cloud 项目 ID
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

# 设置你期望的 Google Cloud 位置
export GOOGLE_CLOUD_LOCATION="us-central1" # 示例位置

# 设置 Cloud Run 服务名称（可选）
export SERVICE_NAME="capital-agent-service"

命令用法¶

此部署命令应从你的智能体代码所在目录运行，即你的 package.json 文件所在的位置。

最简命令¶

npx adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION

包含可选标志的完整命令¶

npx adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--with_ui

选项¶

--project TEXT：（必填）你的 Google Cloud 项目 ID（例如 $GOOGLE_CLOUD_PROJECT）。
--region TEXT：（必填）用于部署的 Google Cloud 位置（例如 $GOOGLE_CLOUD_LOCATION、us-central1）。
--service_name TEXT：（可选）Cloud Run 服务的名称（例如 $SERVICE_NAME）。默认为 adk-default-service-name。
--port INTEGER：（可选）ADK API 服务器将在容器内监听的端口号。默认为 8000。
--with_ui：（可选）如果包含此标志，则在部署智能体 API 服务器的同时部署 ADK 开发 UI。默认情况下，只部署 API 服务器。
--temp_folder TEXT：（可选）指定用于存储部署过程中生成的中间文件的目录。默认为系统临时目录中带时间戳的文件夹。（注意：除非排查问题，否则通常不需要此选项。）
--help：显示帮助信息并退出。

经过身份验证的访问¶

在部署过程中，你可能会收到提示：Allow unauthenticated invocations to [your-service-name] (y/N)?。

输入 y 以允许无需身份验证即可公开访问你的智能体 API 端点。
输入 N（或按 Enter 使用默认值）以要求身份验证（例如，使用"测试你的智能体"部分所示的身份令牌）。

命令成功执行后，将把你的智能体部署到 Cloud Run 并提供已部署服务的 URL。

adk CLI¶

adkgo 命令位于 google/adk-go 仓库的 cmd/adkgo 目录下。在使用之前，你需要从 adk-go 仓库的根目录构建它：

go build ./cmd/adkgo

adkgo deploy cloudrun 命令可自动部署你的应用程序。你不需要提供自己的 Dockerfile。

智能体代码结构¶

使用 adkgo 工具时，你的 main.go 文件必须使用启动器框架。这是因为该工具会编译你的代码，然后使用特定的命令行参数（如 web、api、a2a）运行生成的可执行文件来启动所需的服务。启动器被设计为可以正确解析这些参数。

你的 main.go 应如下所示：

main.go

// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "strings"

    "google.golang.org/adk/v2/agent"
    "google.golang.org/adk/v2/agent/llmagent"
    "google.golang.org/adk/v2/cmd/launcher"
    "google.golang.org/adk/v2/cmd/launcher/full"
    "google.golang.org/adk/v2/model/gemini"
    "google.golang.org/adk/v2/tool"
    "google.golang.org/adk/v2/tool/functiontool"
    "google.golang.org/genai"
)

type getCapitalCityArgs struct {
    Country string `json:"country" jsonschema:"The country for which to find the capital city."`
}

func getCapitalCity(ctx agent.Context, args getCapitalCityArgs) (string, error) {
    capitals := map[string]string{
        "united states": "Washington, D.C.",
        "canada":        "Ottawa",
        "france":        "Paris",
        "japan":         "Tokyo",
    }
    capital, ok := capitals[strings.ToLower(args.Country)]
    if !ok {
        return "", fmt.Errorf("couldn't find the capital for %s", args.Country)
    }

    return capital, nil
}

func main() {
    ctx := context.Background()

    model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{
        APIKey: os.Getenv("GOOGLE_API_KEY"),
    })
    if err != nil {
        log.Fatalf("Failed to create model: %v", err)
    }

    capitalTool, err := functiontool.New(
        functiontool.Config{
            Name:        "get_capital_city",
            Description: "Retrieves the capital city for a given country.",
        },
        getCapitalCity,
    )
    if err != nil {
        log.Fatalf("Failed to create function tool: %v", err)
    }

    geoAgent, err := llmagent.New(llmagent.Config{
        Name:        "capital_agent",
        Model:       model,
        Description: "Agent to find the capital city of a country.",
        Instruction: "I can answer your questions about the capital city of a country.",
        Tools:       []tool.Tool{capitalTool},
    })
    if err != nil {
        log.Fatalf("Failed to create agent: %v", err)
    }

    config := &launcher.Config{
        AgentLoader: agent.NewSingleLoader(geoAgent),
    }

    l := full.NewLauncher()
    err = l.Execute(ctx, config, os.Args[1:])
    if err != nil {
        log.Fatalf("run failed: %v\n\n%s", err, l.CommandLineSyntax())
    }
}

工作原理¶

adkgo 工具将你的 main.go 编译为面向 Linux 的静态链接二进制文件。
它生成一个 Dockerfile，将该二进制文件复制到一个最小容器中。
它使用 gcloud 构建并部署该容器到 Cloud Run。
部署完成后，它会启动一个本地代理，安全地连接到你的新服务。

确保你已通过 Google Cloud 认证（gcloud auth login 和 gcloud config set project <your-project-id>）。

设置环境变量¶

可选但推荐：设置环境变量可以使部署命令更简洁。

# 设置你的 Google Cloud 项目 ID
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

# 设置你期望的 Google Cloud 位置
export GOOGLE_CLOUD_LOCATION="us-central1"

# 设置你的智能体主 Go 文件路径
export AGENT_PATH="./examples/go/cloud-run/main.go"

# 设置 Cloud Run 服务名称
export SERVICE_NAME="capital-agent-service"

命令用法¶

./adkgo deploy cloudrun \
    -p $GOOGLE_CLOUD_PROJECT \
    -r $GOOGLE_CLOUD_LOCATION \
    -s $SERVICE_NAME \
    --proxy_port=8081 \
    --server_port=8080 \
    -e $AGENT_PATH \
    --a2a --api --webui

必填参数¶

-p, --project_name：你的 Google Cloud 项目 ID（例如 $GOOGLE_CLOUD_PROJECT）。
-r, --region：用于部署的 Google Cloud 位置（例如 $GOOGLE_CLOUD_LOCATION、us-central1）。
-s, --service_name：Cloud Run 服务的名称（例如 $SERVICE_NAME）。
-e, --entry_point_path：包含你的智能体源代码的主 Go 文件路径（例如 $AGENT_PATH）。

可选参数¶

--proxy_port：认证代理监听的本地端口。默认为 8081。
--server_port：服务器将在 Cloud Run 容器内监听的端口号。默认为 8080。
--a2a：如果包含此标志，则启用 Agent2Agent 通信。默认启用。
--a2a_agent_url：在公共智能体卡中公布的 A2A 智能体卡 URL。此标志仅在与 --a2a 标志一起使用时有效。
--api：如果包含此标志，则部署 ADK API 服务器。默认启用。
--webui：如果包含此标志，则在部署智能体 API 服务器的同时部署 ADK 开发 UI。默认启用。
--temp_dir：构建产物的临时目录。默认为 os.TempDir()。
--help：显示帮助信息并退出。

经过身份验证的访问¶

服务默认以 --no-allow-unauthenticated 方式部署。

命令成功执行后，将把你的智能体部署到 Cloud Run 并提供一个本地 URL，通过代理访问该服务。

Java 的 gcloud CLI¶

你可以使用标准的 gcloud run deploy 命令和 Dockerfile 部署 Java 智能体。这是目前将 Java 智能体部署到 Google Cloud Run 的推荐方式。

确保你已通过 Google Cloud 认证。具体来说，请在终端中运行命令 gcloud auth login 和 gcloud config set project <your-project-id>。

项目结构¶

按如下方式组织你的项目文件：

your-project-directory/
├── src/
│   └── main/
│       └── java/
│             └── agents/
│                 ├── capitalagent/
│                     └── CapitalAgent.java    # 你的智能体代码
├── pom.xml                                    # Java adk 和 adk-dev 依赖项
└── Dockerfile                                 # 容器构建指令

在项目目录的根目录下创建 pom.xml 和 Dockerfile。你的智能体代码文件（CapitalAgent.java）位于如上所示的目录中。

代码文件¶

这是我们的智能体定义。这与 LLM 智能体中的代码相同，但有两个注意事项：
- 智能体现在被初始化为全局公共静态最终变量。
- 智能体的定义可以在静态方法中暴露，也可以在声明时内联。
请参阅 examples 仓库中的 CapitalAgent 示例代码。

在 pom.xml 文件中添加以下依赖项和插件。

pom.xml

<dependencies>
  <dependency>
     <groupId>com.google.adk</groupId>
     <artifactId>google-adk</artifactId>
     <version>1.6.0</version>
  </dependency>
  <dependency>
     <groupId>com.google.adk</groupId>
     <artifactId>google-adk-dev</artifactId>
     <version>1.6.0</version>
  </dependency>
</dependencies>

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <version>3.2.0</version>
  <configuration>
    <mainClass>com.google.adk.web.AdkWebServer</mainClass>
    <classpathScope>compile</classpathScope>
  </configuration>
</plugin>

定义容器镜像：

Dockerfile

# Use an official Maven image with a JDK. Choose a version appropriate for your project.
FROM maven:3.8-openjdk-17 AS builder

WORKDIR /app

COPY pom.xml .
RUN mvn dependency:go-offline -B

COPY src ./src

# Expose the port your application will listen on.
# Cloud Run will set the PORT environment variable, which your app should use.
EXPOSE 8080

# The command to run your application.
# Use a shell so ${PORT} expands and quote exec.args so agent source-dir is passed correctly.
ENTRYPOINT ["sh", "-c", "mvn compile exec:java \
    -Dexec.mainClass=com.google.adk.web.AdkWebServer \
    -Dexec.classpathScope=compile \
    -Dexec.args='--server.port=${PORT:-8080} --adk.agents.source-dir=target'"]

使用 `gcloud` 部署¶

在终端中导航到 your-project-directory。

gcloud run deploy capital-agent-service \
--source . \
--region $GOOGLE_CLOUD_LOCATION \
--project $GOOGLE_CLOUD_PROJECT \
--allow-unauthenticated \
--set-env-vars="GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT,GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION,GOOGLE_GENAI_USE_ENTERPRISE=$GOOGLE_GENAI_USE_ENTERPRISE"
# 添加你的智能体可能需要的其他必要环境变量

capital-agent-service：你要为 Cloud Run 服务指定的名称。
--source .：指示 gcloud 从当前目录中的 Dockerfile 构建容器镜像。
--region：指定部署区域。
--project：指定 GCP 项目。
--allow-unauthenticated：允许公开访问该服务。对于私有服务，请移除此标志。
--set-env-vars：将必要的环境变量传递给正在运行的容器。确保你包含了 ADK 和你的智能体所需的所有变量（如果不使用应用默认凭据，则包括 API 密钥等）。

gcloud 将构建 Docker 镜像，将其推送到 Google Artifact Registry，并将其部署到 Cloud Run。完成后，它将输出已部署服务的 URL。

有关部署选项的完整列表，请参阅 gcloud run deploy 参考文档。

测试你的智能体¶

智能体部署到 Cloud Run 后，你可以通过已部署的 UI（如果启用）与之交互，也可以使用 curl 等工具直接与其 API 端点交互。你需要使用部署后提供的服务 URL。

UI 测试API 测试（curl）

UI 测试¶

如果你在部署时启用了 UI：

adk CLI： 你在部署过程中包含了相应标志（Go 语言为 --webui，Python 或 TypeScript 为 --with_ui）。
gcloud CLI： 你在 main.py 中设置了 SERVE_WEB_INTERFACE = True。

你只需在 Web 浏览器中导航到部署后提供的 Cloud Run 服务 URL 即可测试你的智能体。

# 示例 URL 格式
# https://your-service-name-abc123xyz.a.run.app

ADK 开发 UI 允许你在浏览器中直接与智能体交互、管理会话和查看执行详情。

要验证你的智能体是否按预期工作，你可以：

从下拉菜单中选择你的智能体。
输入一条消息并验证你是否收到了智能体的预期响应。

如果你遇到任何异常行为，请查看 Cloud Run 控制台日志。

API 测试（curl）¶

你可以使用 curl 等工具与智能体的 API 端点交互。这对于编程交互或在未部署 UI 的情况下非常有用。

你需要使用部署后提供的服务 URL，如果你的服务未设置为允许未认证访问，还可能需要身份令牌进行身份验证。

设置应用 URL¶

将示例 URL 替换为你实际部署的 Cloud Run 服务 URL。

export APP_URL="YOUR_CLOUD_RUN_SERVICE_URL"
# 示例：export APP_URL="https://adk-default-service-name-abc123xyz.a.run.app"

获取身份令牌（如果需要）¶

如果你的服务需要身份验证（即你在使用 gcloud 时未使用 --allow-unauthenticated，或在使用 adk 时对提示回答了"N"），请获取身份令牌。

export TOKEN=$(gcloud auth print-identity-token)

如果你的服务允许未认证访问，你可以省略以下 curl 命令中的 -H "Authorization: Bearer $TOKEN" 请求头。

列出可用应用¶

验证已部署的应用名称。

curl -X GET -H "Authorization: Bearer $TOKEN" $APP_URL/list-apps

（如果需要，请根据此输出调整以下命令中的 app_name。默认值通常是智能体目录名称，例如 capital_agent）。

创建或更新会话¶

初始化或更新特定用户和会话的状态。将 capital_agent 替换为你的实际应用名称（如果不同）。user_123 和 session_abc 是示例标识符；你可以将它们替换为你想要的用户和会话 ID。

curl -X POST -H "Authorization: Bearer $TOKEN" \
    $APP_URL/apps/capital_agent/users/user_123/sessions/session_abc \
    -H "Content-Type: application/json" \
    -d '{"preferred_language": "English", "visit_count": 5}'

运行智能体¶

向你的智能体发送提示。将 capital_agent 替换为你的应用名称，并根据需要调整用户/会话 ID 和提示内容。

curl -X POST -H "Authorization: Bearer $TOKEN" \
    $APP_URL/run_sse \
    -H "Content-Type: application/json" \
    -d '{
    "app_name": "capital_agent",
    "user_id": "user_123",
    "session_id": "session_abc",
    "new_message": {
        "role": "user",
        "parts": [{
        "text": "What is the capital of Canada?"
        }]
    },
    "streaming": false
    }'

如果你想接收服务器推送事件（SSE），请将 "streaming" 设置为 true。
响应将包含智能体的执行事件，包括最终答案。

部署到 Cloud Run¶

智能体示例¶

环境变量¶

前提条件¶

密钥¶

Cloud Build 权限¶

GOOGLE_API_KEY 密钥条目¶

读取权限¶

部署载荷¶

部署命令¶

adk CLI¶

设置环境变量¶

命令用法¶

最简命令¶

包含可选标志的完整命令¶

参数¶

选项¶

传递 gcloud CLI 参数¶

语法示例¶

示例¶

经过身份验证的访问¶

Python 的 gcloud CLI¶

项目结构¶

代码文件¶

定义多个智能体¶

使用 gcloud 部署¶

adk CLI¶

设置环境变量¶

命令用法¶

最简命令¶

包含可选标志的完整命令¶

选项¶

经过身份验证的访问¶

adk CLI¶

智能体代码结构¶

工作原理¶

设置环境变量¶

命令用法¶

必填参数¶

可选参数¶

经过身份验证的访问¶

Java 的 gcloud CLI¶

项目结构¶

代码文件¶

使用 gcloud 部署¶

测试你的智能体¶

UI 测试¶

API 测试（curl）¶

设置应用 URL¶

获取身份令牌（如果需要）¶

列出可用应用¶

创建或更新会话¶

运行智能体¶

使用 `gcloud` 部署¶

使用 `gcloud` 部署¶