使用 GitLab 对 Google Agent Engine 进行安全且快速的部署

Source: GitLab Blog

在本教程中，您将学习如何使用 GitLab 原生的 Google Cloud 集成和 CI/CD 流水线，将使用 Google 的 Agent Development Kit (ADK) 构建的 AI 代理部署到 Agent Engine。我们将涵盖：

• IAM 配置
• 流水线设置
• 测试已部署的代理

什么是 Agent Engine 以及它为何重要？

Agent Engine 是 Google Cloud 为 AI 代理专门设计的托管运行时。可以把它看作是代理的生产环境——它们在这里驻留、运行并可扩展，而您无需管理底层基础设施。

• 处理基础设施、扩展、会话管理和内存存储。
• 与 Google Cloud Logging、Monitoring 和 IAM 原生集成。

为什么使用 GitLab 部署到 Agent Engine？

部署 AI 代理可能会很棘手：安全考虑、CI/CD 编排以及云权限常常会产生摩擦。GitLab 能简化整个流程并提升安全性：

前置条件

在开始之前，请确保您拥有：

1. Google Cloud 项目，并启用以下 API
   • Cloud Storage API
   • Vertex AI API
2. GitLab 项目，用于您的源代码和 CI/CD 流水线。
3. Google Cloud Storage 存储桶，用于暂存部署。
4. Google Cloud IAM 集成 已在 GitLab 中配置（见下文 步骤 1）。

第一步 – 配置 IAM 集成

安全部署的基础是使用 Workload Identity Federation 在 GitLab 与 Google Cloud 之间进行正确的 IAM 配置。

在 GitLab 中

1. 前往 Settings > Integrations。
2. 找到 Google Cloud IAM integration。
3. 提供以下信息：

GitLab 将为您生成一段脚本。复制该脚本并在 Google Cloud Shell 中运行，以在两平台之间建立 Workload Identity Federation。

添加所需角色

为将要部署到 Agent Engine 的服务主体添加以下角色：

• roles/aiplatform.user
• roles/storage.objectAdmin

示例 gcloud 命令

# Set variables (replace placeholders with your values)
GCP_PROJECT_ID=""
GCP_PROJECT_NUMBER=""
GCP_WORKLOAD_IDENTITY_POOL=""

# Grant Vertex AI user role
gcloud projects add-iam-policy-binding "${GCP_PROJECT_ID}" \
  --member="principalSet://iam.googleapis.com/projects/${GCP_PROJECT_NUMBER}/locations/global/workloadIdentityPools/${GCP_WORKLOAD_IDENTITY_POOL}/attribute.developer_access/true" \
  --role='roles/aiplatform.user'

# Grant Cloud Storage object admin role
gcloud projects add-iam-policy-binding "${GCP_PROJECT_ID}" \
  --member="principalSet://iam.googleapis.com/projects/${GCP_PROJECT_NUMBER}/locations/global/workloadIdentityPools/${GCP_WORKLOAD_IDENTITY_POOL}/attribute.developer_access/true" \
  --role='roles/storage.objectAdmin'

第2步 – 创建 CI/CD 流水线

在仓库根目录创建一个 .gitlab-ci.yml 文件。

stages:
  - test
  - deploy

cache:
  paths:
    - .cache/pip
  key: ${CI_COMMIT_REF_SLUG}

variables:
  GCP_PROJECT_ID: ""
  GCP_REGION: "us-central1"
  STORAGE_BUCKET: ""
  AGENT_NAME: "Canada City Advisor"
  AGENT_ENTRY: "canada_city_advisor"

image: google/cloud-sdk:slim

# Security‑scanning templates
include:
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml
  - template: Jobs/SAST.gitlab-ci.yml
  - template: Jobs/Secret-Detection.gitlab-ci.yml

deploy-agent:
  stage: deploy
  identity: google_cloud          # Enables keyless auth via Workload Identity Federation
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  before_script:
    - gcloud config set core/disable_usage_reporting true
    - gcloud config set component_manager/disable_update_check true
    - pip install -q --no-cache-dir --upgrade pip google-genai google-cloud-aiplatform -r requirements.txt --break-system-packages
  script:
    - gcloud config set project $GCP_PROJECT_ID
    - adk deploy agent_engine \
        --project=$GCP_PROJECT_ID \
        --region=$GCP_REGION \
        --staging_bucket=gs://$STORAGE_BUCKET \
        --display_name="$AGENT_NAME" \
        $AGENT_ENTRY

流水线概览

关键说明

• identity: google_cloud 通过工作负载身份联合实现 无密钥认证。
• 安全扫描器作为模板包含进来，默认即运行，无需额外配置。
• adk deploy agent_engine 抽象了打包和部署的复杂性。
• 缓存通过保留 pip 依赖，加快后续运行速度。

第3步 – 部署与验证

1. 将你的代理代码 以及 .gitlab-ci.yml 文件提交到 GitLab。

2. 前往 CI /CD > Pipelines 监控执行情况。

3. 观察：

   • Test stage – 安全扫描完成。
   • Deploy stage – 你的代理已推送到 Agent Engine。

4. 当流水线成功后，在 Google Cloud Console 中验证部署：

   • 前往 Vertex AI > Agent Engine。
   • 找到已部署的代理。
   • 记录 resource name（后续测试需要使用）。

第4步 – 测试已部署的代理

您可以使用简单的 curl 请求来测试代理。您需要三项信息：

示例 curl 命令

AGENT_ID="projects//locations/us-central1/agents/"
ENDPOINT="https://us-central1-aiplatform.googleapis.com/v1/${AGENT_ID}:predict"

# Get an access token (if you’re using a service account with keyless auth, you can skip this step)
ACCESS_TOKEN=$(gcloud auth print-access-token)

curl -X POST "${ENDPOINT}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "instances": [
          {"text": "Hello, Agent!"}
        ]
      }'

如果一切设置正确，您将收到来自代理的 JSON 响应。

🎉 完成！

您现在已经：

• 已在 GitLab 与 Google Cloud 之间配置安全的 IAM 集成。
• 构建了一个 CI/CD 流水线，用于运行安全扫描并部署您的 ADK 代理。
• 已将代理部署到 Agent Engine 并验证其存在。
• 使用简单的 curl 请求测试了实时端点。

随时对您的代理进行迭代，推送新更改，让 GitLab 自动处理测试和部署。祝构建愉快！

项目配置

• 项目 ID：您的 Google Cloud 项目
• 位置：您部署的地区（例如，us-central1）

PROJECT_ID=""
LOCATION="us-central1"
AGENT_ID=""
TOKEN=$(gcloud auth print-access-token)

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/reasoningEngines/${AGENT_ID}:streamQuery" \
  -d '{
    "input": {
      "message": "I make $85,000 per year and I prefer cities with mild winters and a vibrant cultural scene. I also want to be near the coast if possible. What Canadian cities would you recommend?",
      "user_id": "demo‑user"
    }
  }' | jq -r '.content.parts[0].text'

如果一切配置正确，您的代理将根据提供的预算和生活方式偏好，返回个性化的城市推荐。

此方法的安全优势

• 无长期凭证 – 工作负载身份联合完全消除服务账户密钥。
• 自动化漏洞扫描 – 每次部署在进入生产环境前都会被扫描。
• 完整审计追踪 – GitLab 保持对谁在何时部署了什么的完整可视性。
• 最小特权原则 – 细粒度 IAM 角色将访问限制在仅所需范围。

摘要

将 AI 代理部署到生产环境并不一定复杂。将 GitLab 的 DevSecOps 平台与 Google Cloud 的 Agent Engine 结合使用，您将获得：

• 一个托管运行时，负责扩展和基础设施。
• 内置安全扫描，无需额外工具。
• 通过原生云集成实现免密认证。
• 与现代 AI 开发工作流相匹配的简化部署流程。

观看完整演示

[Link to demo video]

准备自己动手尝试吗？

使用本教程的完整代码示例，立即开始。

还不是 GitLab 客户吗？ 通过 免费试用 探索 DevSecOps 平台。