サンドボックスを管理する

このページでは、Python SDK を使用してサンドボックス環境のライフサイクルを管理する方法について説明します。既存のサンドボックスの一覧表示、詳細の表示、一時停止と再開、不要になったサンドボックスの削除を行うことができます。

始める前に

サンドボックスを管理するには、プロジェクトに次のロールが必要です。

• Agent Platform ユーザー（roles/aiplatform.user）

サンドボックスを管理する

Agent Platform インスタンスに関連付けられているサンドボックス環境の一覧表示、詳細の表示、一時停止、再開、削除を行うことができます。一時停止と再開を使用すると、アイドル状態のサンドボックスのコンピューティング リソースのスケジュールを解除し、ファイル システムの状態や接続 ID を失うことなく、後でオンラインに戻すことができます。既存のサンドボックスの構成を変更するには、削除して新しいサンドボックスを作成する必要があります。

サンドボックスを一覧表示する

Agent Platform インスタンスに関連付けられているすべてのサンドボックスを一覧表示するには:

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
instance_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID'

sandboxes = client.sandboxes.list(name=instance_name)

for sandbox in sandboxes:
    print(sandbox.name)

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

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• LOCATION: Agent Platform インスタンスの Google Cloud リージョン。サポート対象の地域をご覧ください。
• INSTANCE_ID: Agent Platform インスタンス ID。

サンドボックスの詳細を表示する

特定のサンドボックスの構成とステータスを表示するには:

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

sandbox = client.sandboxes.get(name=sandbox_name)
print(sandbox)

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

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• LOCATION: Agent Platform インスタンスの Google Cloud リージョン。サポート対象の地域をご覧ください。
• INSTANCE_ID: サンドボックスを含む Agent Platform インスタンス ID。
• SANDBOX_ID: 既存のサンドボックス ID。

出力には、作成時間、状態（STATE_RUNNING など）、サンドボックス仕様などの詳細が含まれます。

サンドボックスを一時停止する

サンドボックスを一時停止すると、ディスクの状態と接続メタデータを保持しながら、コンピューティング リソースが解放されます。一時停止したサンドボックスは、実行中のサンドボックスよりも大幅に費用が低く、数秒で再開できます。サンドボックスが長時間アイドル状態になっているが、後で使用するためにセッション状態と接続 ID を保持する場合は、一時停止を使用します。

一時停止されたサンドボックスには次の特性があります。

• サンドボックス ID、接続メタデータ、Private Service Connect エンドポイントを保持します。
• 一時停止の時点で、コンテナ内のすべてのファイル システムの状態を保持します。
• STATE_PAUSED に移行します。再開するまで、データプレーン エンドポイントへのリクエストはエラーを返します。

実行中のサンドボックスを一時停止するには、次のコードを実行します。

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

pause_operation = client.sandboxes.pause(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_PAUSED.
    },
)
paused_sandbox = pause_operation.response
print(f"Sandbox {paused_sandbox.name} state: {paused_sandbox.state}")  # STATE_PAUSED

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

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• LOCATION: Agent Platform インスタンスの Google Cloud リージョン。サポート対象の地域をご覧ください。
• INSTANCE_ID: サンドボックスを含む Agent Platform インスタンス ID。
• SANDBOX_ID: 既存のサンドボックス ID。

サンドボックスを再開する

一時停止したサンドボックスを再開すると、コンピューティングがオンラインに戻ります。サンドボックスは、一時停止した時点と同じ ID、接続エンドポイント（Private Service Connect サービス アタッチメントを含む）、ファイル システムの状態を保持します。再開オペレーションが完了すると、データプレーン リクエストをサンドボックスに再度送信できます。

一時停止したサンドボックスを再開するには、次のコードを実行します。

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

resume_operation = client.sandboxes.resume(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_RUNNING.
    },
)
resumed_sandbox = resume_operation.response
print(f"Sandbox {resumed_sandbox.name} state: {resumed_sandbox.state}")  # STATE_RUNNING

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

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• LOCATION: Agent Platform インスタンスの Google Cloud リージョン。サポート対象の地域をご覧ください。
• INSTANCE_ID: サンドボックスを含む Agent Platform インスタンス ID。
• SANDBOX_ID: 一時停止中のサンドボックス ID。

注: 再開できるのは、STATE_PAUSED 状態のサンドボックスのみです。実行中のサンドボックスを再開しようとすると、FAILED_PRECONDITION が返されます。

サンドボックスを削除する

サンドボックス環境を明示的に削除してリソースを解放するには:

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

注: サンドボックスは、存在する間は課金されます。サンドボックスの作成時に config.ttl を設定すると、delete() を呼び出す前にプロセスがクラッシュした場合でも、TTL の有効期限が切れるとサンドボックスが自動的に削除されます。

監査ロギングとモニタリング

サンドボックスでコマンドを管理して実行すると、Agent Platform は aiplatform.googleapis.com サービス名と audited_resource モニタリング対象リソースタイプで Cloud Audit Logs に API レベルのアクティビティを記録します。

• 管理アクティビティ（ADMIN_WRITE）ログ: CreateSandboxEnvironment、PauseSandboxEnvironment、ResumeSandboxEnvironment、SnapshotSandboxEnvironment、DeleteSandboxEnvironment（aiplatform.sandboxEnvironments.* IAM 権限が必要）などのコントロール プレーンのライフサイクル変更に対して自動的に記録されます。
• データアクセス（ADMIN_READ）ログ: GetSandboxEnvironment や ListSandboxEnvironments などのメタデータ読み取りオペレーションが有効になっている場合に記録されます。
• データアクセス（DATA_WRITE）ログ: データプレーン コマンドの実行とアクセス認可呼び出し（ExecuteSandboxEnvironment、BidiExecuteSandboxEnvironment、AuthorizeSandboxEnvironmentAccess、ExecuteCode など）が有効になっている場合に記録されます。VPC Service Controls で保護されているリソースの場合、リクエストとレスポンスのペイロードは監査ログから除外されます。

次のオブザーバビリティと脅威検出の境界に注意してください。

• コンテナ内のプロセスとストリーム アクティビティ: Cloud Audit Logs は、コマンド実行を開始する API リクエストや接続を承認する API リクエストをログに記録しますが、コンテナ内で生成された個々の子プロセス、ファイル システムの変更、開いている WebSocket、Chrome DevTools Protocol（CDP）、PTY セッションを介して送信された後続のインタラクティブ フレームはログに記録しません。
• コンテナ stdout と stderr のロギング: Agent Runtime の Cloud Logging の自動収集（reasoning_engine_stdout や reasoning_engine_stderr など）は、親 ReasoningEngine インスタンスにのみ適用され、サンドボックスの子リソースからログを自動的に収集することはありません。コマンド出力（stdout、stderr、終了コード）は、親エージェントへの実行レスポンスで返されます。ここで、構造化エントリを検査して Cloud Logging に書き込むことができます。
• 脅威検出とネットワーク検査: サンドボックスは、gVisor カーネル分離と、アンビエント Google Cloud 認証情報のないサンドボックス内の非特権 ID を使用して、コンテナ化を適用します。異常な動作や不正なネットワーク下り（外向き）をモニタリングするには、DATA_WRITE 監査ログと親エージェントのエージェント異常検出を組み合わせ、VPC フローログ、Cloud Next Generation Firewall（Cloud NGFW）ルール ロギング、Secure Web Proxy 検査を使用して、Private Service Connect インターフェースを介してサンドボックスの下り（外向き）をルーティングします。詳細については、セキュリティ、ID、オブザーバビリティの境界をご覧ください。