シェル サンドボックスのクイックスタート

シェル サンドボックスは、Agent Platform インスタンスに接続された、管理対象の分離された Linux コンテナです。サンドボックスは、エージェントから送信されたシェル コマンドを実行し、stdout、stderr、終了コードを返します。独自のインフラストラクチャで実行されるものはなく、サンドボックスが削除されるとコンテナは破棄されます。

エージェントが信頼できないシェル コマンドや生成されたシェル コマンドを実行したり、パッケージをインストールしたり、ファイルを操作したり、環境を公開せずにコマンドライン ツールを操作したりする必要がある場合は、シェル サンドボックスを使用します。

制限事項

• send_command() と execute_code() は、シェル サンドボックスでは機能しません。これらのメソッドは、コード実行サンドボックスを対象としており、シェル コンテナが受け入れない Python ペイロードを送信します。シェル サンドボックスで /exec を使用します。

始める前に

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

プロジェクトを設定する

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

必要なロールを取得する

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

• プロジェクトに対する Agent Platform ユーザー（roles/aiplatform.user）。

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

Agent Platform モジュールを含む SDK をインストールします。

pip install "google-cloud-aiplatform[agent_engines]"

認証

アプリケーションのデフォルト認証情報を使用して認証するには:

gcloud auth application-default login

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

シェル サンドボックスを使用するには、まず Agent Platform インスタンスを作成します。シェル サンドボックスを使用するためにエージェントをデプロイする必要はありません。デプロイなしで Agent Platform インスタンスを作成するには、数秒かかります。

import vertexai

client = vertexai.Client(project='PROJECT_ID', location='LOCATION')

agent_engine = client.agent_engines.create()
agent_engine_name = agent_engine.api_resource.name

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

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。

• LOCATION: Agent Platform インスタンスの Google Cloud リージョン。サポートされているリージョンをご覧ください。

シェル サンドボックスを作成する

サンドボックスを作成する際は、次のいずれかを指定する必要があります。

• 環境が設定された spec（shell_environment）
• config.sandbox_environment_template（指定しない場合は、デフォルトのテンプレートが作成されます）。詳細については、サンドボックス間でテンプレートを再利用するをご覧ください。
• config.sandbox_environment_snapshot

次の例では、サンドボックス仕様で shell_environment を渡します。

engine = (
    "projects/PROJECT_ID/locations/LOCATION"
    "/reasoningEngines/INSTANCE_ID"
)

operation = client.agent_engines.sandboxes.create(
    name=engine,
    spec={"shell_environment": {}},
    config={
        "display_name": "my-shell-sandbox",
        "wait_for_completion": True,
        "ttl": "3600s",
    },
)
sandbox = operation.response
print(sandbox.name, sandbox.state)

サンドボックスの準備が整うと、次のようなレスポンスが出力されます。

projects/.../sandboxEnvironments/1035360621853409280 SandboxState.STATE_RUNNING

通常、サンドボックスは 20 秒ほどで STATE_RUNNING に到達します。

コマンドを実行する

サンドボックスでシェルコマンドを実行するには、ヘルパー関数 execute_bash() を使用します。この関数は、コマンドをコンテナに送信します。

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="echo hello && whoami && pwd",
)
print(result)

コマンドは stdout、stderr、returncode、duration_ms を返します。

{'stdout': 'hello\nappuser\n/workspace\n', 'stderr': '', 'returncode': 0, 'duration_ms': 8}

execute_bash() は独自の認証情報で認証されるため、サービス アカウントや署名付き JWT は必要ありません。

省略可: cwd を明示的に設定して作業ディレクトリを選択し、timeout を設定してコマンドの実行時間を制限できます。それ以外の場合、サンドボックスは独自のデフォルト（/workspace とサンドボックスの制限時間）を使用します。

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="pytest -q",
    cwd="/workspace/app",
    timeout=120,
)

コマンドが失敗したかどうかを確認するには、returncode と stderr を調べます。

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="ls /nope",
)
print(result)

{'stdout': '', 'stderr': "ls: cannot access '/nope': No such file or directory\n", 'returncode': 2, 'duration_ms': 5}

コンテナ環境を使用する場合は、次の点を考慮してください。

• コマンドは権限のないユーザー appuser として実行されます。sudo はありません。
• 各コマンドは新しいシェルで実行されるため、cd とシェル変数は呼び出し間で引き継がれません。1 つのコマンドでチェーンするか、/workspace の下のファイルに状態を書き込みます。
• テンプレートで有効にしない限り、アウトバウンド インターネット アクセスはオフになっています。

クリーンアップ

サンドボックスを削除して課金を停止するには、次のコマンドを実行します。

client.agent_engines.sandboxes.delete(name=sandbox.name)
print("Sandbox deleted.")

次のステップ

• サンドボックスを管理する
• サンドボックス テンプレートを管理する