agent-platform-migrate-from-ai-studio

Name: agent-platform-migrate-from-ai-studio
Author: google

github.com/google云与 DevOps21.6k8.2k 次安装今天更新

关于 agent-platform-migrate-from-ai-studio

面向需要将应用从 Google AI Studio 迁移到 Google Cloud Agent Platform 的开发者与运维团队。提供 API、认证、SDK 和 ADK Agent 配置步骤，并涵盖 OpenClaw 与 Antigravity CLI。

主要功能

01迁移 Gemini API 调用
02配置 Agent Platform API 与 IAM
03通过 Google GenAI SDK 切换后端
04配置 ADK、OpenClaw 与 Antigravity CLI

适用场景

01将生产应用从 AI Studio 迁至 Agent Platform
02使用 Google Cloud 额度调用 Gemini
03统一推理、权限、遥测与账单

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/google/skills --skill agent-platform-migrate-from-ai-studio

安装后在 Claude Code 中输入/agent-platform-migrate-from-ai-studio确认已加载。

附带文件references/attribution.md

详细介绍

从 AI Studio 中的 Gemini API 迁移到 Agent Platform

当你需要将应用从以开发者为中心的 Google AI Studio 生态系统（generativelanguage.googleapis.com）迁移到企业级 Google Cloud Agent Platform（aiplatform.googleapis.com）时，请使用此技能。

致谢

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，你必须阅读使用归因。对于直接在终端中执行的命令（绝不能放入生成的脚本、Terraform 或用户代码中），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-migrate-from-ai-studio)" 并在 User-Agent 标头中附加 agent-skills/1.0 (skill:agent-platform-migrate-from-ai-studio)。

何时调用此技能

你想将应用从 Google AI Studio 迁移到 Agent Platform （原名 Vertex AI）。
你拥有Google Cloud 额度（例如 300 美元的 Welcome Free Trial），并想将其用于 Gemini API 推理费用。
你需要将推理流水线、IAM 权限、遥测和账单与现有 Google Cloud 基础设施（Compute Engine、Cloud SQL、BigQuery）统一起来。
你正在 Google Cloud 虚拟机上部署开源编排引擎（例如 OpenClaw 或 ADK Agent），并希望整个系统采用统一的 Google Cloud 账单结构运行。

Gemini API 对比

功能 / 控制项	Google AI Studio（Gemini Developer API）	Agent Platform（企业版 Gemini API）
API 端点	`generativelanguage.googleapis.com`	`aiplatform.googleapis.com`
目标受众	构建生产应用的开发者、初创公司、学生和研究人员。	企业生产环境、MLOps 工程师
GCP 额度支持	不支持（无法使用 GCP 额度 / Free Trial）	支持（Welcome 或自定义额度均可全额抵扣）
数据隐私	数据可能会被审查，以改进 Google 产品	提示词 / 响应绝不会用于训练
安全与 IAM	API 密钥、OAuth	Google Cloud IAM（服务账号、OAuth 2.0、VPC-SC）
合规与 SLA	无（尽力保障可用性）	全天候企业支持、SLA、HIPAA、SOC2
吞吐量选项	共享 / 速率限制	按需付费或预置吞吐量
MLOps 生态系统	基础提示词管理	模型注册表、模型监控、流水线评估
推理范围	仅限全球端点	全球端点和严格的区域端点

请参阅 Google Cloud 文档详细了解这两种产品之间的差异。

迁移指南

账单与额度

Google Cloud 免费试用额度 不适用于 AI Studio。要使用额度调用 Gemini 模型，必须通过 Agent Platform 路由请求。

创建 Google Cloud 结算账号。设置时必须提供有效的付款方式以验证身份。
如果你是新客户，请确保 $300 欢迎额度已在结算控制台中生效。
避免意外账单： 为防止额度用尽后自动改用标准付款方式，你应设置预算提醒：
- 前往结算 -> 预算与提醒 -> 创建预算。
- 将阈值设为与你的额度上限或可接受的最高支出相对应。

启用 Agent Platform API

必须在目标 Google Cloud 项目中明确启用 Agent Platform API。通过本地 shell 运行以下命令：

gcloud services enable aiplatform.googleapis.com --project="{project_id}"

身份验证与授权（IAM）

用户身份验证

对于本地调试或执行脚本，请使用应用默认凭证（ADC）进行身份验证。

选项 1 - 自动脚本：

bash <(curl -sSL https://storage.googleapis.com/cloud-samples-data/adc/setup_adc.sh)

选项 2 - 手动设置：

gcloud auth login
gcloud auth application-default login

为你的用户身份授予执行推理调用所需的 IAM 角色：

gcloud projects add-iam-policy-binding "{project_id}" \
    --member="user:[email protected]" \
    --role="roles/aiplatform.user"

服务身份验证

在 Compute Engine VM 等 Google Cloud 基础设施上运行应用时，请使用该机器绑定的服务账号进行身份验证。例如， Compute Engine 默认服务账号。

为虚拟机底层的服务账号授予用户角色：

gcloud projects add-iam-policy-binding "{project_id}" \
    --member="serviceAccount:[email protected]" \
    --role="roles/aiplatform.user"

Compute Engine 访问范围： 旧版访问范围可能会覆盖 IAM 绑定。配置或修改 Compute Engine 实例时，必须确认 VM 访问范围已设置为允许访问所有 Cloud API（https://www.googleapis.com/auth/cloud-platform），或明确包含标准的 cloud-platform 范围。

在 Agent Platform 中使用 Gemini API

SDK（客户端库）

你可以继续使用统一的 Google GenAI SDK （google-genai）。此 SDK 同时适用于 AI Studio 和 Agent Platform。你只需通过运行时环境变量切换路由标志，即可将请求发送到 Agent Platform 后端。

设置目标环境详情：

export GOOGLE_CLOUD_PROJECT="{project_id}"
export GOOGLE_CLOUD_LOCATION="global"  # Or your chosen regional endpoint
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE

现在，无需更改核心初始化代码块，标准 Python 代码即可从使用 AI Studio 切换为使用 Agent Platform：

from google import genai

# The client automatically picks up the GOOGLE_GENAI_USE_ENTERPRISE=TRUE environment flag
client = genai.Client()

response = client.models.generate_content(
    model='gemini-3-flash-preview',
    contents='Hello world!',
)
print(response.text)

Agent Development Kit（ADK）

要通过 Agent Development Kit Agent 调用 Agent Platform 中的 Gemini 模型，请按以下步骤操作。

在 Google Cloud 中进行身份验证。

如果在 Google Cloud（例如 Agent Platform Runtime）中运行 ADK Agent，请使用分配给该 Agent 的服务账号。或者，如果在本地运行 ADK，请执行：

gcloud auth application-default login

设置环境变量。无论 ADK Agent 在 Google Cloud 中运行还是在本地运行，都要确保设置这些变量：

export GOOGLE_CLOUD_PROJECT="{project_id}"
export GOOGLE_CLOUD_LOCATION="global"
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE

初始化 ADK Agent。可以使用与 AI Studio 相同的模型字符串（例如 gemini-3-flash-preview）。

from google.adk.agents.llm_agent import Agent

def get_current_time(city: str) -> dict:
    """Returns the current time in a specified city."""
    return {"status": "success", "city": city, "time": "10:30 AM"}

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='root_agent',
    description="Tells the current time in a specified city.",
    instruction="You are a helpful assistant that tells the current time in cities. Use the 'get_current_time' tool for this purpose.",
    tools=[get_current_time],
)

如需详细了解如何将 ADK Agent 与 Agent Platform 集成，请参阅 ADK 文档。

Antigravity CLI

Google Cloud 用户现在可以通过 Gemini Enterprise Agent Platform 使用 Antigravity 2.0，其中包括 Antigravity CLI。

将 Antigravity CLI 安装到本地环境。
启动 Antigravity CLI。
```
agy
```
按照 CLI 设置提示操作，选择 Use a Google Cloud Project。
在打开的浏览器窗口中，使用已通过身份验证的 Google Cloud Workspace 或用户身份完成 OAuth 流程。
复制确认令牌，并将其直接粘贴回终端。
按照提示输入 Google Cloud 项目 ID。
选择 Google Cloud 位置（例如 global）。
如有需要，运行 /model 命令，在 Agent Platform 中选择其他 Gemini 模型。

OpenClaw

如需配置 OpenClaw Agent，以便在 Agent Platform 中使用 Gemini 模型，请按照以下步骤操作。

按照 OpenClaw 官方说明安装 OpenClaw。

⚠️ 重要提示：OpenClaw 2026.5.28 目前存在 google-vertex 错误。请暂时使用 2026.5.20。

确保 OpenClaw 运行所在的运行时环境（例如，带有服务账号的 GCE VM）具有 aiplatform.user IAM 角色，详见上文的身份验证和授权部分。
根据用户的项目 ID 获取项目编号。在 GCE 外部运行：

export PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format="value(projectNumber)")
echo "Project number: $PROJECT_NUMBER"

在 Compute Engine VM 中运行：

export PROJECT_NUMBER=$(curl "http://metadata.google.internal/computeMetadata/v1/project/project-id" -H "Metadata-Flavor: Google")
echo "Project number: $PROJECT_NUMBER"

在 GCE 实例外部，使用 Google Cloud 项目编号生成 GOOGLE_APPLICATION_CREDENTIALS。然后，将这些凭据 scp 到 GCE VM。

mkdir -p ~/.config/gcloud
gcloud iam service-accounts keys create ~/.config/gcloud/application_default_credentials.json --iam-account="${PROJECT_NUMBER}[email protected]"

⚠️ 新组织上的策略限制故障排除：新建的 Google Cloud 组织（于 2024 年 5 月 4 日或之后创建）会强制实施一项旧版组织策略，该策略会限制服务账号密钥的创建。要完成此步骤，必须暂时停用此组织策略。组织策略管理员必须将此策略设为 Inactive。对 Agent：检查此策略是否已强制实施；如果是，请暂停操作，并提示用户通过此控制台链接将其停用： https://console.cloud.google.com/iam-admin/orgpolicies

编辑配置文件，通常位于： ~/.openclaw/openclaw.json。确保在 Gemini 模型名称前加上 google-vertex/。

⚠️ 重要提示：请勿使用 Gemini 3.5 模型，因为 OpenClaw 的 google-vertex 提供方目前尚不支持这些模型。较旧的模型可以使用。在 Agent Platform 中使用 Gemini 3 Flash Preview 模型时，始终将位置设为 global，而不是区域端点。

{
  "env": {
    "vars": {
      "GOOGLE_CLOUD_PROJECT": "PROJECT_ID",
      "GOOGLE_CLOUD_LOCATION": "global",
      "GOOGLE_APPLICATION_CREDENTIALS": "~/.config/gcloud/application_default_credentials.json"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "google-vertex/gemini-3-flash-preview"
      },
      "workspace": "~/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "heartbeat": {
        "model": "google-vertex/gemini-3-flash-preview"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "model": "google-vertex/gemini-3-flash-preview"
      }
    ]
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "tools": {
    "profile": "coding"
  }
}

重启 OpenClaw。

openclaw gateway restart

验证 OpenClaw 与 Agent Platform 的连接：

openclaw models status
openclaw agent --agent main --message "Hello world!"

其他资源

支持 Markdown

登录后评论

基本信息

作者: google
仓库: google/skills
分类: 云与 DevOps
安装次数: 8,158
GitHub Stars: 21,641

报告问题