Back to Details

agent-platform-migrate-from-ai-studio

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrating from Gemini API in AI Studio to Agent Platform

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

Use this skill when you need to transition an application from the developer-centric Google AI Studio ecosystem (
generativelanguage.googleapis.com
) to the enterprise-grade Google Cloud Agent Platform (
aiplatform.googleapis.com
).
当您需要将应用从面向开发者的Google AI Studio生态系统（
generativelanguage.googleapis.com
）迁移至企业级Google Cloud Agent Platform（
aiplatform.googleapis.com
）时，可使用此技能。

When to Invoke This Skill

何时调用此技能

  • You want to migrate an application from Google AI Studio to Agent Platform (formerly Vertex AI).
  • You have Google Cloud credits (e.g., the $300 Welcome Free Trial) that you want to apply toward Gemini API inferencing costs.
  • You need to unify your inferencing pipelines, IAM permissions, telemetry, and billing with existing Google Cloud infrastructure (Compute Engine, Cloud SQL, BigQuery).
  • You are deploying open-source orchestration engines (like OpenClaw or ADK agents) on Google Cloud VMs, and want the entire system to run under a unified Google Cloud billing structure.
  • 您希望将应用从Google AI Studio迁移到Agent Platform（原Vertex AI）。
  • 您拥有Google Cloud信用额度（例如300美元欢迎免费试用额度），希望将其用于Gemini API推理成本。
  • 您需要将推理流水线、IAM权限、遥测数据和计费与现有Google Cloud基础设施（Compute Engine、Cloud SQL、BigQuery）统一。
  • 您正在Google Cloud虚拟机上部署开源编排引擎（如OpenClaw或ADK Agent），并希望整个系统在统一的Google Cloud计费结构下运行。

Gemini API Comparison

Gemini API对比

Feature / ControlGoogle AI Studio (Gemini Developer API)Agent Platform (Enterprise Gemini API)
API Endpoint
generativelanguage.googleapis.com
aiplatform.googleapis.com
Target AudienceDevelopers, startups, students, researchers building production apps.Enterprise production, MLOps engineers
GCP Credit SupportNo (GCP credits/Free Trial cannot be applied)Yes (Fully covered by Welcome or custom credits)
Data PrivacyData may be reviewed to improve Google productsPrompts/responses are never used for training
Security & IAMAPI key, OAuthGoogle Cloud IAM (Service Accounts, OAuth 2.0, VPC-SC)
Compliance & SLAsNone (Best-effort availability)24/7 Enterprise Support, SLAs, HIPAA, SOC2
Throughput OptionsShared / Rate-limitedPay-as-you-go OR Provisioned Throughput
MLOps EcosystemBasic prompt managementModel Registry, Model Monitoring, Pipeline Evaluation
Inferencing ScopeGlobal endpoints onlyBoth Global and strict Regional endpoints
See Google Cloud Documentation to learn more about the differences between the two offerings.
功能/控制项Google AI Studio（Gemini开发者API）Agent Platform（企业级Gemini API）
API端点
generativelanguage.googleapis.com
aiplatform.googleapis.com
目标受众开发者、初创企业、学生、研究人员，用于构建生产应用。企业级生产环境、MLOps工程师
GCP信用额度支持不支持（GCP信用额度/免费试用无法使用）支持（完全适用欢迎信用额度或自定义信用额度）
数据隐私数据可能会被用于改进Google产品提示词/响应绝不会用于模型训练
安全与IAMAPI密钥、OAuthGoogle Cloud IAM（服务账号、OAuth 2.0、VPC-SC）
合规性与SLA无（尽力而为的可用性）7×24小时企业支持、SLA、HIPAA、SOC2合规
吞吐量选项共享/速率限制按需付费或预配置吞吐量
MLOps生态系统基础提示词管理模型注册表、模型监控、流水线评估
推理范围仅全局端点全局及严格区域端点
查看 Google Cloud文档 了解这两种服务的更多差异。

Migration Guide

迁移指南

Billing and Credits

计费与信用额度

Google Cloud Free Trial credits do not apply to AI Studio. To use your credits for Gemini models, you must route calls through the Agent Platform.
  1. Create a Google Cloud billing account. You must provide a valid payment method during setup to verify identity.
  2. If you are a new customer, ensure your $300 Welcome credit is active in the Billing Console.
  3. Avoid Billing Surprises: To prevent automatic fallback to your standard form of payment when credits are exhausted, you should establish a budget alert:
    • Go to Billing -> Budgets & Alerts -> Create Budget.
    • Set the threshold to map to your credit limit or maximum comfortable spend.
Google Cloud免费试用额度 不适用于AI Studio。 要将信用额度用于Gemini模型，您必须通过Agent Platform发起调用。
  1. 创建Google Cloud计费账号。设置过程中您必须提供有效的支付方式以验证身份。
  2. 如果您是新客户，请确保300美元欢迎信用额度在计费控制台中处于激活状态。
  3. 避免计费意外：为防止信用额度耗尽时自动切换为标准支付方式，您应设置预算告警：
    • 进入计费 -> 预算与告警 -> 创建预算。
    • 将阈值设置为您的信用额度上限或可接受的最高支出。

Enable the Agent Platform API

启用Agent Platform API

You must explicitly enable the Agent Platform API on your target Google Cloud Project. Run the following command via your local shell:
bash
gcloud services enable aiplatform.googleapis.com --project="YOUR_PROJECT_ID"
您必须在目标Google Cloud项目上显式启用Agent Platform API。在本地终端运行以下命令：
bash
gcloud services enable aiplatform.googleapis.com --project="YOUR_PROJECT_ID"

Authentication & Authorization (IAM)

身份验证与授权（IAM）

User Auth

用户身份验证

For local debugging or script execution, authenticate using Application Default Credentials (ADC).
Option 1 - Automated Script:
bash
bash <(curl -sSL https://storage.googleapis.com/cloud-samples-data/adc/setup_adc.sh)
Option 2 - Manual Setup:
bash
gcloud auth login
gcloud auth application-default login
Grant your user identity the required IAM role to perform inferencing calls:
bash
gcloud projects add-iam-policy-binding "YOUR_PROJECT_ID" \
    --member="user:YOUR_EMAIL@domain.com" \
    --role="roles/aiplatform.user"
对于本地调试或脚本执行，使用 应用默认凭据 (ADC)进行身份验证。
选项1 - 自动化脚本：
bash
bash <(curl -sSL https://storage.googleapis.com/cloud-samples-data/adc/setup_adc.sh)
选项2 - 手动设置：
bash
gcloud auth login
gcloud auth application-default login
为您的用户身份授予执行推理调用所需的IAM角色：
bash
gcloud projects add-iam-policy-binding "YOUR_PROJECT_ID" \
    --member="user:YOUR_EMAIL@domain.com" \
    --role="roles/aiplatform.user"

Service Auth

服务身份验证

When running your application on Google Cloud infrastructure such as a Compute Engine VM, authenticate using the machine's attached Service Account. For example, the Compute Engine Default Service Account.
  1. Grant the virtual machine's underlying Service Account the user role:
bash
gcloud projects add-iam-policy-binding "YOUR_PROJECT_ID" \
    --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --role="roles/aiplatform.user"
  1. Compute Engine Access Scopes: Legacy access scopes can override IAM bindings. When provisioning or modifying your GCE instance, you must verify that the VM access scope is configured to either Allow full access to all Cloud APIs (
    https://www.googleapis.com/auth/cloud-platform
    ) or explicitly includes the standard cloud-platform scope.
当您在Google Cloud基础设施（如Compute Engine虚拟机）上运行应用时，使用虚拟机附加的服务账号进行身份验证。例如， Compute Engine默认服务账号。
  1. 为虚拟机底层的服务账号授予用户角色：
bash
gcloud projects add-iam-policy-binding "YOUR_PROJECT_ID" \
    --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --role="roles/aiplatform.user"
  1. Compute Engine访问范围： 旧版访问范围可能会覆盖IAM绑定。在配置或修改GCE实例时，您必须验证VM访问范围已配置为允许访问所有Cloud API (
    https://www.googleapis.com/auth/cloud-platform
    )，或明确包含标准cloud-platform范围。

Use the Gemini API in Agent Platform

在Agent Platform中使用Gemini API

SDKs (Client Libraries)

SDK（客户端库）

You can continue to use the unified Google GenAI SDK (
google-genai
). This SDK works with both AI Studio and Agent Platform. You only need to switch the routing flags via your runtime environment variables to target the Agent Platform backend.
Set your target environment details:
bash
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="global"  # Or your chosen regional endpoint
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
Now, your standard python code shifts from using AI Studio to Agent Platform without altering the core initialization blocks:
python
from google import genai
您可以继续使用统一的 Google GenAI SDK (
google-genai
)。此SDK同时适用于AI Studio和Agent Platform。您只需通过运行时环境变量切换路由标志，即可指向Agent Platform后端。
设置目标环境详情：
bash
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="global"  # 或您选择的区域端点
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
现在，您的标准Python代码无需修改核心初始化代码块，即可从使用AI Studio切换到Agent Platform：
python
from google import genai

The client automatically picks up the GOOGLE_GENAI_USE_ENTERPRISE=TRUE environment flag

客户端会自动读取GOOGLE_GENAI_USE_ENTERPRISE=TRUE环境变量

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

Agent Development Kit (ADK)

Agent开发工具包（ADK）

To call Gemini models in Agent Platform from an Agent Development Kit agent, follow these steps.
  1. Authenticate to Google Cloud.
If running an ADK agent in Google Cloud (e.g. Agent Platform Runtime), use the agent's assigned service account. Alternatively, if running ADK locally, run:
bash
gcloud auth application-default login
  1. Set env variables. Ensure these are set no matter if your ADK agent is running in Google Cloud or locally:
bash
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="global"
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
  1. Initialize the ADK agent. You can use the same model string you used with AI Studio (e.g. 
    gemini-3-flash-preview
    ).
python
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],
)
To learn more about integrating ADK agents with Agent Platform, see the ADK documentation.
要从Agent开发工具包（ADK）Agent调用Agent Platform中的Gemini模型，请遵循以下步骤。
  1. 登录Google Cloud。
如果在Google Cloud中运行ADK Agent（例如Agent Platform Runtime），使用Agent分配的服务账号。或者，如果在本地运行ADK，请执行：
bash
gcloud auth application-default login
  1. 设置环境变量。无论ADK Agent是在Google Cloud中运行还是本地运行，都必须设置这些变量：
bash
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="global"
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
  1. 初始化ADK Agent。您可以使用与AI Studio中相同的模型字符串（例如
    gemini-3-flash-preview
    ）。
python
from google.adk.agents.llm_agent import Agent

def get_current_time(city: str) -> dict:
    """返回指定城市的当前时间。"""
    return {"status": "success", "city": city, "time": "10:30 AM"}

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='root_agent',
    description="告知指定城市的当前时间。",
    instruction="您是一个乐于助人的助手，负责告知各个城市的当前时间。请使用'get_current_time'工具完成此任务。",
    tools=[get_current_time],
)
要了解更多关于ADK Agent与Agent Platform集成的信息，请 查看ADK文档。

Antigravity CLI

Antigravity CLI

Google Cloud users can now access Antigravity 2.0, including the Antigravity CLI, with Gemini Enterprise Agent Platform.
  1. Install the Antigravity CLI to your local environment.
  2. Start the Antigravity CLI.
    bash
    agy
  3. Follow the CLI setup prompts - select Use a Google Cloud Project.
  4. Complete the OAuth flow in the opened browser window using your authenticated Google Cloud Workspace or user identity.
  5. Copy the confirmation token, and paste it directly back into your terminal.
  6. Follow the prompts to enter your Google Cloud Project ID.
  7. Select your Google Cloud location (e.g. 
    global
    ).
  8. Optionally, run the 
    /model
    command to select a different Gemini model in Agent Platform.
Google Cloud用户现在可以通过Gemini Enterprise Agent Platform 访问 Antigravity 2.0，包括Antigravity CLI。
  1. 安装Antigravity CLI 到您的本地环境。
  2. 启动Antigravity CLI。
    bash
    agy
  3. 按照CLI设置提示操作 - 选择使用Google Cloud项目。
  4. 在打开的浏览器窗口中使用已认证的Google Cloud Workspace或用户身份完成OAuth流程。
  5. 复制确认令牌，并直接粘贴回终端。
  6. 按照提示输入您的Google Cloud项目ID。
  7. 选择您的Google Cloud位置（例如
    global
    ）。
  8. 可选地，运行
    /model
    命令以在Agent Platform中选择不同的Gemini模型。

OpenClaw

OpenClaw

To configure an OpenClaw agent to use Gemini models in Agent Platform, Follow these steps.
  1. Install OpenClaw using OpenClaw's official instructions.
⚠️ Important: OpenClaw 2026.5.28 currently has a 
google-vertex
bug. Please use 2026.5.20 for now.
  1. Ensure that the runtime where OpenClaw is running (e.g. GCE VM with Service Account) has the 
    aiplatform.user
    IAM role - see Authentication and Authorization section above.
  2. Get the project number from the user's project ID. Outside of GCE, run:
bash
export PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format="value(projectNumber)")
echo "Project number: $PROJECT_NUMBER"
Within a GCE VM, run:
bash
export PROJECT_NUMBER=$(curl "http://metadata.google.internal/computeMetadata/v1/project/numeric-project-id" -H "Metadata-Flavor: Google")
echo "Project number: $PROJECT_NUMBER"
  1. From outside the GCE instance, generate 
    GOOGLE_APPLICATION_CREDENTIALS
    using the Google Cloud project number. Then, 
    scp
    these credentials to the GCE VM.
bash
mkdir -p ~/.config/gcloud
gcloud iam service-accounts keys create ~/.config/gcloud/application_default_credentials.json --iam-account="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
  1. Edit the configuration file that's usually located at: 
    ~/.openclaw/openclaw.json
    . Ensure you prefix the Gemini model with 
    google-vertex/
    .
    ⚠️ Important:
    • Do not use Gemini 3.5 models, since OpenClaw's 
      google-vertex
      provider does not support it yet. Older models work.
    • When using the Gemini 3 Flash Preview model in Agent Platform, always set the location to 
      global
      , NOT a regional endpoint.
json
{
  "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"
  }
}
  1. Restart OpenClaw.
bash
openclaw gateway restart
  1. Verify the OpenClaw connection to Agent Platform:
bash
openclaw models status
openclaw agent --agent main --message "Hello world!"
要配置OpenClaw Agent以使用Agent Platform中的Gemini模型，请遵循以下步骤。
  1. 按照OpenClaw官方说明安装OpenClaw。
⚠️ 重要提示：OpenClaw 2026.5.28当前存在
google-vertex
bug。请暂时使用2026.5.20版本。
  1. 确保运行OpenClaw的运行环境（例如带有服务账号的GCE虚拟机）拥有
    aiplatform.user
    IAM角色 - 请参阅上方的身份验证与授权部分。
  2. 从用户的项目ID获取项目编号。在GCE外部运行：
bash
export PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format="value(projectNumber)")
echo "Project number: $PROJECT_NUMBER"
在GCE虚拟机内部运行：
bash
export PROJECT_NUMBER=$(curl "http://metadata.google.internal/computeMetadata/v1/project/numeric-project-id" -H "Metadata-Flavor: Google")
echo "Project number: $PROJECT_NUMBER"
  1. 在GCE实例外部，使用Google Cloud项目编号生成
    GOOGLE_APPLICATION_CREDENTIALS
    。然后，通过
    scp
    将这些凭据传输到GCE虚拟机。
bash
mkdir -p ~/.config/gcloud
gcloud iam service-accounts keys create ~/.config/gcloud/application_default_credentials.json --iam-account="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
  1. 编辑通常位于以下路径的配置文件： 
    ~/.openclaw/openclaw.json
    。确保在Gemini模型前添加
    google-vertex/
    前缀。
    ⚠️ 重要提示：
    • 请勿使用Gemini 3.5模型，因为OpenClaw的
      google-vertex
      提供商目前尚不支持该模型。旧版模型可正常使用。
    • 当在Agent Platform中使用 Gemini 3 Flash Preview 模型时，请始终将位置设置为
      global
      ，而非区域端点。
json
{
  "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"
  }
}
  1. 重启OpenClaw。
bash
openclaw gateway restart
  1. 验证OpenClaw与Agent Platform的连接：
bash
openclaw models status
openclaw agent --agent main --message "Hello world!"

Additional Resources

额外资源