コンピュータ使用のクイックスタート

このページでは、直接 API 呼び出しを行ってコンピュータ使用サンドボックス環境を作成して使用する方法について説明します。 このクイックスタートでは、次のタスクを行います。

  • サンドボックスにアクセスする Agent Platform インスタンスを作成する。
  • コンピュータ使用サンドボックスを作成する。
  • サンドボックスのアクセス トークンを生成する。
  • ステータスを確認するリクエストを送信する。
  • リソースをクリーンアップする。

始める前に

プロジェクトと環境を設定します。

プロジェクトを設定する

  1. アカウントにログインします。 Google Cloud を初めて使用する場合は、 アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。 Google Cloud新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Gemini Enterprise Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Gemini Enterprise Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

必要なロールを取得する

サンドボックスを使用してトークンを生成するには、次のロールが必要です。

  • プロジェクトに対する Agent Platform ユーザー（roles/aiplatform.user）。
  • トークン生成に使用されるサービス アカウントに対するサービス アカウント トークン作成者（roles/iam.serviceAccountTokenCreator）。
  • トークン生成に使用されるサービス アカウントには、プロジェクトに対する Agent Platform ユーザー（roles/aiplatform.user）ロールも必要です。

ライブラリをインストールする

Agent Platform SDK をインストールします。 posix-terminal pip install google-cloud-aiplatform>=1.112.0

Agent Platform インスタンスを作成する

サンドボックスを使用するには、まず Agent Platform インスタンスを作成します。

import vertexai
client = vertexai.Client(
    project='PROJECT_ID',
    location='LOCATION',
    http_options={
        "api_version": "v1beta1",
    }
)
agent_instance = client.agent_engines.create()
agent_instance_name = agent_instance.api_resource.name

次のように置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • LOCATION: インスタンスのリージョン（us-central1 など）。

コンピュータ使用のテンプレートを作成する

コンピュータ使用サンドボックスを作成するときに使用するサンドボックス テンプレートを作成します。

# Create a default Computer Use sandbox template
templates_client = client.agent_engines.sandboxes.templates
tmplt_operation = templates_client.create(
    name=agent_instance_name,
    display_name='DISPLAY_NAME',
    config={
        "default_container_environment": {
            "default_container_category": "DEFAULT_CONTAINER_CATEGORY_COMPUTER_USE",
        },
        "egress_control_config": {
            "internet_access": True,
        },
    },
)
template_name = tmplt_operation.response.name
print(f"Created template: {template_name}")

コンピュータ使用サンドボックスを作成する

テンプレートからサンドボックス環境を作成します。

# Create a sandbox environment referencing the template
create_operation = client.agent_engines.sandboxes.create(
    name=agent_instance_name,
    config={
        "sandbox_environment_template": template_name,
        "display_name": 'DISPLAY_NAME',
    }
)
sandbox = create_operation.response
print(f"Created sandbox environment: {sandbox.name}")

アクセス トークンを生成する

サンドボックスとやり取りするには、サービス アカウントを使用して JSON ウェブトークン（JWT）アクセス トークンを生成します。

service_account_email = "SERVICE_ACCOUNT_EMAIL"
access_token = client.agent_engines.sandboxes.generate_access_token(
    service_account_email=service_account_email,
)

SERVICE_ACCOUNT_EMAIL は、サービス アカウント トークン作成者のロールを持つサービス アカウントのメールアドレスに置き換えます。

サンドボックスにリクエストを送信する

HTTP GET リクエストをサンドボックス API サーバーに送信して、ステータスを確認します。

response = client.agent_engines.sandboxes.send_command(
    http_method="GET",
    access_token=access_token,
    sandbox_environment=sandbox
)
print(f"Sandbox response: {response.body}")

HTTP POST リクエストを送信して、特定のページに移動します。

data = {"command": "Page.navigate", "params": {"url": "https://example.com"}}

response = client.agent_engines.sandboxes.send_command(
    http_method="POST",
    path="cdp",
    access_token=access_token,
    request_dict=data,
    sandbox_environment=sandbox
)

次の表に、サンドボックスに送信できる追加のメソッドとパスを示します。

メソッド パス 説明
GET / サンドボックスのヘルスチェックを取得します。
POST /tabs 新しいタブを作成し、その詳細を返します。
GET /tabs 開いているすべてのタブの詳細を一覧表示します。
POST /tabs/{tab_id}/activate タブをアクティブに設定し、フォアグラウンドに表示します。
削除 /tabs/{tab_id} 特定のタブを閉じます。
GET /cdp_ws_endpoint CDP WebSocket エンドポイント パスを返します。
POST /cdp アクティブなタブで CDP コマンドを実行します。
POST /cdps アクティブなタブで複数の CDP コマンドを実行します。

サポートされている CDP コマンドと形式の詳細については、 CDP サイトをご覧ください。

クリーンアップ

課金されないようにするには、このクイックスタートで作成したリソースを削除します。

client.agent_engines.sandboxes.delete(name=sandbox.name)
agent_instance.delete()

次のステップ