Agent Sandbox で AI コードの実行を分離する

Autopilot Standard

このドキュメントでは、Google Kubernetes Engine（GKE）クラスタに Agent Sandbox コントローラをインストールして実行する手順について説明します。また、信頼できないシェルコマンドをテストできるサンドボックス環境をクラスタにデプロイする方法についても説明します。

Agent Sandbox コントローラは、エフェメラル ランタイム環境の作成と管理のためのフレームワークを提供します。このアプローチでは、アプリの環境にテンプレートを定義し、必要に応じてそのインスタンスを作成できます。

Agent Sandbox は、大規模言語モデル（LLM）によって生成されたコードなど、信頼性の低いコードを実行するための安全で分離された環境を提供します。このタイプのコードをクラスタで直接実行すると、信頼できないコードが他のアプリや基盤となるクラスタノード自体にアクセスしたり、干渉する可能性があるため、セキュリティ上のリスクが生じます。

Agent Sandbox は、実行するコードに対して強力なプロセス、ストレージ、ネットワークの分離を提供することで、これらのリスクを軽減します。この分離は、アプリケーションとクラスタノードのオペレーティング システムの間に安全なバリアを作成するテクノロジーである gVisor を使用して実現されます。他のサンドボックス テクノロジー（Kata コンテナなど）を使用することもできますが、このドキュメントの例では gVisor のみを使用します。

このドキュメントでは、GKE Autopilot クラスタまたは Standard クラスタで Agent Sandbox を実行する手順について説明します。

Agent Sandbox はオープンソース プロジェクトです。プロジェクトに貢献する方法や、より詳細な技術情報については、Agent Sandbox オープンソース プロジェクトをご覧ください。

費用

このドキュメントの手順に沿って操作すると、 Google Cloudアカウントに料金が発生します。費用は、GKE クラスタを作成した時点で発生します。これらの費用には、料金ページで説明されている GKE のクラスタごとの料金と、Compute Engine VM の実行料金が含まれます。

不要な料金が発生しないように、このドキュメントの完了後に GKE を無効にするか、プロジェクトを削除してください。

始める前に

1. 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

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

3. Enable the Artifact Registry, Google Kubernetes Engine APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

4. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   環境変数を定義する

   このドキュメントで実行するコマンドを簡略化するために、Cloud Shell で環境変数を設定できます。Cloud Shell で、次のコマンドを実行して環境変数を定義します。

   export PROJECT_ID=$(gcloud config get project)
   export CLUSTER_NAME="agent-sandbox-cluster"
   export GKE_LOCATION="us-central1"
   export AGENT_SANDBOX_VERSION="v0.1.0"
   export NODE_POOL_NAME="agent-sandbox-node-pool"
   export MACHINE_TYPE="e2-standard-2"
   export PYTHON_CLIENT_VERSION="main"
   

   これらの環境変数の説明は次のとおりです。

   • PROJECT_ID: 現在の Google Cloud プロジェクトの ID。この変数を定義すると、GKE クラスタなどのすべてのリソースが正しいプロジェクトに作成されます。
   • CLUSTER_NAME: GKE クラスタの名前（例: agent-sandbox-cluster）。
   • GKE_LOCATION: GKE クラスタと Artifact Registry リポジトリが作成される Google Cloud リージョン（例: us-central1）。イメージの pull レイテンシが短縮されるため、これらをコロケーションすることをおすすめします。
   • AGENT_SANDBOX_VERSION: クラスタにデプロイする Agent Sandbox コントローラのバージョン。
   • NODE_POOL_NAME: サンドボックス化されたワークロードを実行するノードプールの名前（例: agent-sandbox-node-pool）。
   • MACHINE_TYPE: ノードプール内のノードのマシンタイプ（e2-standard-2 など）。さまざまなマシンシリーズとさまざまなオプションの選択の詳細については、マシン ファミリーのリソースと比較ガイドをご覧ください。
   • PYTHON_CLIENT_VERSION: インストールする Agentic Sandbox Python クライアントのバージョン。

   Agent Sandbox をデプロイする

   Google Cloud プロジェクトと Cloud Shell 環境が設定されたので、必要なインフラストラクチャをプロビジョニングして、Agent Sandbox をデプロイする準備ができました。

   GKE クラスタを作成する

   次に、gVisor が有効になっている GKE クラスタを作成します。このクラスタは、Agent Sandbox コントローラとサンプル サンドボックス アプリをデプロイして実行する Kubernetes 環境を提供します。gVisor は、信頼できないコードを安全に実行するためのサンドボックス テクノロジーを提供します。

   Autopilot クラスタまたは Standard クラスタを作成できます。 Autopilot では gVisor が自動的に有効になりますが、Standard クラスタでは gVisor 対応のノードプールを手動で作成する必要があります。

   Autopilot

   gcloud CLI を使用して Autopilot クラスタを作成するには、次のコマンドを実行します。

   gcloud container clusters create-auto ${CLUSTER_NAME} \
       --location=${GKE_LOCATION} \
       --project=${PROJECT_ID}
   

   Standard

   gcloud CLI を使用して Standard クラスタを作成するには、次の操作を行います。

   1. クラスタを作成します。

      gcloud container clusters create ${CLUSTER_NAME} \
          --location=${GKE_LOCATION}
      

   2. gVisor を有効にして、独立したノードプールを作成します。

      gcloud container node-pools create ${NODE_POOL_NAME} \
        --cluster=${CLUSTER_NAME} \
        --location=${GKE_LOCATION} \
        --machine-type=${MACHINE_TYPE} \
        --image-type=cos_containerd \
        --sandbox type=gvisor
      

   kubectl CLI がクラスタに接続できるように、クラスタの認証情報を取得します。このコマンドは、デフォルトで ~/.kube/config ディレクトリに保存されている Kubernetes 構成ファイルを更新します。この構成ファイルには、kubectl が GKE クラスタとやり取りするために必要な認証情報が含まれています。

   gcloud container clusters get-credentials ${CLUSTER_NAME} \
       --location=${GKE_LOCATION}
   

   Agent Sandbox コントローラをクラスタにデプロイする

   公式リリース マニフェストをクラスタに適用することで、Agent Sandbox コントローラとその必須コンポーネントをデプロイできます。これらのマニフェストは、クラスタに Agent Sandbox コントローラをデプロイして実行するために必要なすべてのコンポーネントをダウンロードするように Kubernetes に指示する構成ファイルです。

   次のコマンドを実行して、Agent Sandbox コントローラを GKE クラスタにデプロイします。

   kubectl apply \
   -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml \
   -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/extensions.yaml
   

   Agent Sandbox コントローラを確認する

   マニフェストを適用したら、agent-sandbox-system 名前空間で Agent Sandbox コントローラ Pod が正しく実行されていることを確認します。

   kubectl get pods -n agent-sandbox-system
   

   Pod の STATUS 列に「Running」、READY 列に「1/1」が表示されるまで待ちます。Pod が正常に実行されている場合、出力は次のようになります。

   NAME                         READY   STATUS    RESTARTS   AGE
   agent-sandbox-controller-0   1/1     Running   0          44d
   

   Agent Sandbox コントローラが実行されると、クラスタに作成した Sandbox リソースのサンドボックス環境を自動的に作成して管理できます。

   サンドボックス環境をデプロイする

   GKE クラスタで Agent Sandbox コントローラが実行されているので、サンプル サンドボックス環境のコンポーネントをデプロイする必要があります。このセクションでは、サンドボックス ブループリント（SandboxTemplate）を作成し、必要なネットワーキング ルーターをデプロイして、サンドボックスの操作に使用する Python クライアントをインストールする方法について説明します。

   サンドボックスを作成して操作するには、Agentic Sandbox Python クライアントを使用することをおすすめします。このクライアントは、サンドボックスの作成からクリーンアップまでのライフサイクル全体を簡素化するインターフェースを提供します。これは、サンドボックスの作成、使用、削除をプログラムで行うために使用できる Python ライブラリです。

   クライアントは、すべてのトラフィックの中央エントリ ポイントとしてサンドボックス ルーターを使用します。このドキュメントで説明する例では、クライアントは kubectl port-forward コマンドを使用してこのルーターへのトンネルを作成するため、パブリック IP アドレスを公開する必要はありません。kubectl port-forward の使用は安全なソリューションではなく、開発環境での使用に限定する必要があります。

   SandboxTemplate と SandboxWarmPool を作成する

   SandboxTemplate リソースと SandboxWarmPool リソースを作成して、サンドボックスの構成を定義します。SandboxTemplate は、Agent Sandbox コントローラが使用して、一貫性のある事前構成済みのサンドボックス環境を作成する再利用可能なブループリントとして機能します。SandboxWarmPool リソースは、指定された数の事前にウォームアップされた Pod が常に実行され、要求される準備ができていることを保証します。事前にウォームアップされたサンドボックスは、すでに初期化されている実行中の Pod です。この事前初期化により、新しいサンドボックスを 1 秒以内に作成できるようになり、通常のサンドボックスの起動時のレイテンシを回避できます。

   1. Cloud Shell で、次の内容を含むファイルを sandbox-template-and-pool.yaml という名前で作成します。

      apiVersion: extensions.agents.x-k8s.io/v1alpha1
      kind: SandboxTemplate
      metadata:
        name: python-runtime-template
        namespace: default
      spec:
        podTemplate:
          metadata:
            labels:
              sandbox: python-sandbox-example
          spec:
            runtimeClassName: gvisor
            containers:
            - name: python-runtime
              image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
              ports:
              - containerPort: 8888
              readinessProbe:
                httpGet:
                  path: "/"
                  port: 8888
                initialDelaySeconds: 0
                periodSeconds: 1
              resources:
                requests:
                  cpu: "250m"
                  memory: "512Mi"
                  ephemeral-storage: "512Mi"
            restartPolicy: "OnFailure"
      ---
      apiVersion: extensions.agents.x-k8s.io/v1alpha1
      kind: SandboxWarmPool
      metadata:
        name: python-sandbox-warmpool
        namespace: default
      spec:
        replicas: 2
        sandboxTemplateRef:
          name: python-runtime-template
      

   2. SandboxTemplate マニフェストと SandboxWarmPool マニフェストを適用します。

      kubectl apply -f sandbox-template-and-pool.yaml
      

   サンドボックス ルーターをデプロイする

   サンドボックス環境の作成と操作に使用する Python クライアントは、サンドボックス ルーターと呼ばれるコンポーネントを使用してサンドボックスと通信します。

   この例では、テストにクライアントのデベロッパー モードを使用します。このモードはローカル開発を目的としており、kubectl port-forward コマンドを使用して、ローカルマシンから、クラスタで実行されているサンドボックス ルーター サービスへの直接トンネルを確立します。このトンネリング アプローチでは、パブリック IP アドレスや複雑な上り（内向き）設定が不要になり、ローカル環境からのサンドボックスの操作が簡素化されます。

   サンドボックス ルーターをデプロイする手順は次のとおりです。

   1. Cloud Shell で、次の内容を含むファイルを sandbox-router.yaml という名前で作成します。

      # A ClusterIP Service to provide a stable endpoint for the router pods.
      apiVersion: v1
      kind: Service
      metadata:
        name: sandbox-router-svc
        namespace: default
      spec:
        type: ClusterIP
        selector:
          app: sandbox-router
        ports:
        - name: http
          protocol: TCP
          port: 8080 # The port the service will listen on
          targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile)
      ---
      # The Deployment to manage and run the router pods.
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: sandbox-router-deployment
        namespace: default
      spec:
        replicas: 2 # Run at least two replicas for high availability
        selector:
          matchLabels:
            app: sandbox-router
        template:
          metadata:
            labels:
              app: sandbox-router
          spec:
            # Ensure pods are spread across different zones for HA
            topologySpreadConstraints:
              - maxSkew: 1
                topologyKey: topology.kubernetes.io/zone
                whenUnsatisfiable: ScheduleAnyway
                labelSelector:
                  matchLabels:
                    app: sandbox-router
            containers:
            - name: router
              image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:v20251124-v0.1.0-10-ge26ddb2
              ports:
              - containerPort: 8080
              readinessProbe:
                httpGet:
                  path: /healthz
                  port: 8080
                initialDelaySeconds: 5
                periodSeconds: 5
              livenessProbe:
                httpGet:
                  path: /healthz
                  port: 8080
                initialDelaySeconds: 10
                periodSeconds: 10
              resources:
                requests:
                  cpu: "250m"
                  memory: "512Mi"
                limits:
                  cpu: "1000m"
                  memory: "1Gi"
            securityContext:
              runAsUser: 1000
              runAsGroup: 1000
      

   2. マニフェストを適用して、ルーターをクラスタにデプロイします。

      kubectl apply -f sandbox-router.yaml
      

   Python クライアントをインストールする

   サンドボックス ルーターなどのクラスタ内コンポーネントがデプロイされたので、最後の準備手順として、ローカルマシンに Agentic Sandbox Python クライアントをインストールします。このクライアントは、サンドボックスをプログラムで作成、使用、削除できる Python ライブラリです。次のセクションで、環境のテストに使用します。

   1. Python 仮想環境を作成してアクティブにします。

      python3 -m venv .venv
      source .venv/bin/activate
      

   2. agent-sandbox リポジトリからクライアント パッケージをインストールします。

      pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@${PYTHON_CLIENT_VERSION}#subdirectory=clients/python/agentic-sandbox-client"
      

   サンドボックスをテストする

   すべての設定コンポーネントが整ったので、Agentic Sandbox Python クライアントを使用してサンドボックスを作成し、操作できるようになりました。

   1. agent-sandbox ディレクトリに、次の内容の Python スクリプトを test_sandbox.py という名前で作成します。

      from agentic_sandbox import SandboxClient
      
      # Automatically tunnels to svc/sandbox-router-svc
      with SandboxClient(
          template_name="python-runtime-template",
          namespace="default"
      ) as sandbox:
          print(sandbox.run("echo 'Hello from the sandboxed environment!'").stdout
      )
      

   2. ターミナルから（仮想環境がアクティブな状態で）、テスト スクリプトを実行します。

      python3 test_sandbox.py
      

   サンドボックスから出力される「Hello from the sandboxed environment!」というメッセージが表示されます。

   これで完了です。安全なサンドボックス内でシェルコマンドが正常に実行されました。sandbox.run() メソッドを使用すると、任意のシェルコマンドを実行できます。Agent Sandbox は、クラスタのノードや他のワークロードを信頼できないコードから保護する安全なバリア内でコマンドを実行します。これにより、AI エージェントや自動化されたワークフローがタスクを実行するための安全で信頼性の高い方法が提供されます。

   スクリプトの実行時に、SandboxClient によってすべての手順が処理されます。SandboxClaim リソースを作成してサンドボックスを起動し、サンドボックスの準備が整うまで待機してから、sandbox.run() メソッドを使用して安全なコンテナ内で bash シェルコマンドを実行します。クライアントは、そのコマンドから stdout をキャプチャして出力します。サンドボックスは、プログラムの実行後に自動的に削除されます。

   リソースのクリーンアップ

   Google Cloud アカウントに課金されないようにするには、作成した GKE クラスタを削除する必要があります。

   gcloud container clusters delete $CLUSTER_NAME --location=$GKE_LOCATION --quiet
   

   次のステップ

   • Agent Sandbox オープンソース プロジェクトの詳細については、GitHub をご覧ください。
   • ワークロードのセキュリティ分離を提供する基盤となるテクノロジーについては、GKE Sandbox をご覧ください。
   • クラスタとワークロードのセキュリティ強化の詳細については、GKE セキュリティの概要をご覧ください。