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

Autopilot Standard

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

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

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

Agent Sandbox は、実行するコードに対して強力なプロセス、ストレージ、ネットワークの分離を提供することで、これらのリスクを軽減します。このドキュメントでは、GKE Autopilot クラスタまたは Standard クラスタで Agent Sandbox を実行する手順について説明します。

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

費用

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

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

始める前に

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

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 REPOSITORY_NAME="python-sandbox-repo"
export PYTHON_SANDBOX_IMG="${GKE_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${REPOSITORY_NAME}/sandbox-runtime:latest"
export AGENT_SANDBOX_VERSION="v0.1.0"
```
これらの環境変数の説明は次のとおりです。
- PROJECT_ID: 現在の Google Cloud プロジェクトの ID。この変数を定義すると、GKE クラスタなどのすべてのリソースが正しいプロジェクトに作成されます。
- CLUSTER_NAME: GKE クラスタの名前（例: agent-sandbox-cluster）。
- GKE_LOCATION: GKE クラスタと Artifact Registry リポジトリが作成される Google Cloud リージョン（例: us-central1）。イメージの pull レイテンシが短縮されるため、これらをコロケーションすることをおすすめします。
- REPOSITORY_NAME: Python サンプルアプリのコンテナイメージが保存される Artifact Registry リポジトリの名前（例: python-sandbox-repo）。
- PYTHON_SANDBOX_IMG: ビルドして push する Python サンドボックスコンテナイメージの固有識別子。
- AGENT_SANDBOX_VERSION: クラスタにデプロイする Agent Sandbox コントローラのバージョン。
Agent Sandbox をデプロイする

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

GKE クラスタを作成する

次に、GKE クラスタを作成します。このクラスタは、Agent Sandbox コントローラとサンプルサンドボックスアプリをデプロイして実行する Kubernetes 環境を提供します。

Autopilot クラスタまたは Standard クラスタを作成できます。
Autopilot
gcloud CLI を使用して Autopilot クラスタを作成するには、次のコマンドを実行します。
```
gcloud container clusters create-auto ${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --project=${PROJECT_ID}
```
Standard
gcloud CLI を使用して Standard クラスタを作成するには、次のコマンドを実行します。
```
gcloud container clusters create ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}
```
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
```
Deployment を確認する

マニフェストを適用したら、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 コントローラが実行されているので、シェルコマンドを実行するための安全なサンドボックス環境を提供するサンプルウェブサーバーアプリをデプロイできます。

これを行うには、まずアプリのコンテナイメージをビルドし、クラスタがアクセスできる非公開の Artifact Registry リポジトリに保存する必要があります。

イメージが使用可能になったら、2 段階のプロセスでデプロイします。まず、SandboxTemplate を定義します。これは、サンドボックス環境の再利用可能なブループリントとして機能します。次に、SandboxClaim を作成します。これは、Agent Sandbox コントローラにコンテナイメージを pull し、テンプレートに基づいて新しい Pod として実行するように指示するリクエストです。最後に、実行中のアプリをテストして、正しく動作することを確認します。

Artifact Registry リポジトリを作成する

次の手順では、コンテナイメージを保存する非公開の Artifact Registry リポジトリを作成し、それにアクセスするように Docker を構成する方法について説明します。
1. Python サンドボックスアプリのコンテナイメージを保存する Artifact Registry リポジトリを作成します。
```
gcloud artifacts repositories create $REPOSITORY_NAME \
    --repository-format=docker \
    --location=$GKE_LOCATION
```
2. Artifact Registry で Docker クライアントを認証します。この操作により、 Google Cloud 認証情報を使用して、イメージを限定公開リポジトリに安全に push し、そこからイメージを pull できます。
```
gcloud auth configure-docker "${GKE_LOCATION}-docker.pkg.dev"
```
Python サンプルアプリをビルドして push する

次に、Agent Sandbox リポジトリからサンプルコードをダウンロードする必要があります。このコードは、基本的な Python ウェブサーバーを含むコンテナイメージをビルドします。

このウェブサーバーは、Agent Sandbox のコア機能をデモンストレートするように設計されており、シェルコマンドを JSON ペイロードとして受け入れる /execute エンドポイントを公開します。このエンドポイントにコマンドを送信すると、サーバーは安全なサンドボックス環境内でコマンドを実行し、出力を返します。

次の手順では、リポジトリのクローンを作成し、コンテナイメージをビルドして、プライベート Artifact Registry リポジトリに push する方法について説明します。
1. GitHub から agent-sandbox リポジトリのクローンを作成します。このリポジトリには、Python アプリのコードが含まれています。
```
git clone https://github.com/kubernetes-sigs/agent-sandbox.git
```
2. Python アプリの Dockerfile とソースコードが含まれるディレクトリに移動します。
```
cd agent-sandbox/examples/python-runtime-sandbox
```
3. Docker を使用してアプリのコンテナイメージをビルドします。-t フラグは、このドキュメントの冒頭で PYTHON_SANDBOX_IMG 環境変数で定義された名前でイメージにタグを付けます。
```
docker build -t $PYTHON_SANDBOX_IMG .
```
4. GKE クラスタがアクセスできるように、コンテナイメージを限定公開の Artifact Registry リポジトリに push します。
```
docker push $PYTHON_SANDBOX_IMG
```
SandboxTemplate を作成する

SandboxTemplate リソースを作成して、サンドボックスの構成を定義します。このテンプレートは、Agent Sandbox コントローラが使用して、一貫性のある事前構成済みのサンドボックス環境を作成する再利用可能なブループリントとして機能します。SandboxTemplate リソースを作成すると、サンドボックスを一度定義して、後でその複数のインスタンスを作成できます。
1. Cloud Shell で、次の内容を含むファイルを sandbox-template.yaml という名前で作成します。このマニフェストは、サンドボックスの作成に使用できる再利用可能なブループリントとして機能する SandboxTemplate リソースを定義します。SandboxTemplate と SandboxClaim は同じ Namespace に存在している必要があります。
```
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        # The selector in the wait command looks for this label.
        sandbox: python-sandbox-example
    spec:
      # Optional, must have gVisor enabled node
      # runtimeClassName: gvisor
      containers:
      - name: python-runtime
        image: IMAGE_PLACEHOLDER
        ports:
        - containerPort: 8888
        readinessProbe:
          httpGet:
            path: "/"
            port: 8888
          initialDelaySeconds: 0
          periodSeconds: 1
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
            ephemeral-storage: "512Mi"
      restartPolicy: "OnFailure"
```
2. Python アプリのイメージパスを使用してマニフェストを更新します。
```
sed -i "s|IMAGE_PLACEHOLDER|${PYTHON_SANDBOX_IMG}|g" sandbox-template.yaml
```
3. SandboxTemplate マニフェストを適用します。
```
kubectl apply -f sandbox-template.yaml
```
SandboxClaim を作成してサンドボックスを作成する

再利用可能なブループリントが作成されたので、SandboxClaim リソースをクラスタに適用して、実行側のサンドボックスを作成します。この要求は SandboxTemplate を参照し、テンプレートの構成に基づいて Sandbox リソースとその対応する Pod を作成するように Agent Sandbox コントローラに指示します。
1. 次の内容で sandbox-claim.yaml という名前のファイルを作成します。SandboxClaim リソースは、python-runtime-template に基づく新しいサンドボックスをリクエストします。複数の SandboxClaims を作成できますが、各 SandboxClaim 名は実行中の他の SandboxClaims と重複しないようにする必要があります。
```
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: python-sandbox-example
  namespace: default
spec:
  sandboxTemplateRef:
    name: python-runtime-template
```
2. テンプレートに基づいて Sandbox リソースの作成をトリガーするには、SandboxClaim マニフェストを適用します。
```
kubectl apply -f sandbox-claim.yaml
```
3. Sandbox リソースの準備ができていることを確認します。
```
kubectl wait --for=condition=Ready sandbox/python-sandbox-example --namespace default --timeout=120s
```
  出力は次のようになります。
```
sandbox.agents.x-k8s.io/python-sandbox-example condition met
```
4. kubectl get sandbox コマンドを実行して、サンドボックスの詳細を表示します。
```
kubectl get sandbox
```
5. 続行する前に、サンドボックス化された Pod がトラフィックを受け入れる準備ができていることを確認します。
```
kubectl wait --for=condition=ready pod --selector=sandbox=python-sandbox-example --namespace default --timeout=120s
```
  出力は次のようになります。
```
pod/python-sandbox-example condition met
```
サンドボックスをテストする

サンプルアプリが安全なサンドボックス内で実行されているので、テストして正しく動作していることを確認できます。次の手順では、kubectl port-forward コマンドを使用して Cloud Shell 環境からサンドボックス Pod に安全に接続する方法について説明します。次に、クローンを作成したリポジトリに含まれている tester.py スクリプトを使用して、アプリの /execute エンドポイントにテストコマンドを送信し、成功レスポンスが返されることを確認します。
1. Pod へのポート転送を設定します。ポート転送を使用すると、ローカルの Cloud Shell 環境からサンドボックス内で実行されているウェブサーバーアプリに通信できます。
```
POD_NAME="python-sandbox-example"
kubectl port-forward "pod/${POD_NAME}" 8888:8888 &
PF_PID=$!
trap "kill $PF_PID" EXIT
sleep 3
```
2. テストスクリプトに必要な requests ライブラリをインストールします。
```
pip3 install requests
```
3. agent-sandbox/examples/python-runtime-sandbox ディレクトリにある tester.py スクリプトを実行して、サンドボックスエンドポイントを確認します。
```
python3 tester.py 127.0.0.1 8888
```
  tester.py スクリプトは、アプリが応答していることを確認するヘルスチェックと、echo 'hello world' シェルコマンドをサンドボックスに送信するコマンド実行テストという 2 つの主要なテストを実行します。
  
  出力は次のようになります。
```
    $ python3 tester.py 127.0.0.1 8888
--- Testing Health Check endpoint ---
Sending GET request to http://127.0.0.1:8888/
Handling connection for 8888
Health check successful!
Response JSON: {'status': 'ok', 'message': 'Sandbox Runtime is active.'}

--- Testing Execute endpoint ---
Sending POST request to http://127.0.0.1:8888/execute with payload: {'command': "echo 'hello world'"}
Handling connection for 8888
Execute command successful!
Response JSON: {'stdout': 'hello world\n', 'stderr': '', 'exit_code': 0}
```
これで完了です。GKE クラスタに安全なサンドボックス環境が正常にデプロイされました。このアプリの /execute エンドポイントに任意のシェルコマンドを送信できるようになりました。Agent Sandbox は、クラスタのノードや他のワークロードを信頼できないコードから保護する安全なバリア内でコマンドを実行します。Agent Sandbox は、AI エージェントや自動化されたワークフローがタスクを実行するための安全で信頼性の高い方法を提供します。

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

テストが完了したら、サンドボックスを破棄してコンピューティングリソースを解放します。
1. 作成した SandboxClaim リソースを削除します。
```
kubectl delete -f sandbox-claim.yaml
```
  このアクションは、実行中の Pod を終了して Sandbox リソースを削除するようにコントローラに指示します。
2. 次のコマンドを実行して、リソースが削除されたことを確認します。
```
kubectl get sandbox,pod -n default
```
  しばらくすると、サンドボックス環境が正常にクリーンアップされたことを確認する No resources found メッセージが表示されます。
リソースのクリーンアップ

Google Cloud アカウントに課金されないようにするには、このドキュメント全体で作成したリソースを削除します。次の手順では、GKE クラスタ、Artifact Registry リポジトリ、およびそのリポジトリに含まれるコンテナイメージを削除する方法について説明します。
1. GKE クラスタを削除します。
```
gcloud container clusters delete $CLUSTER_NAME --location=$GKE_LOCATION --quiet
```
2. Artifact Registry に push したコンテナイメージを削除します。
```
gcloud artifacts docker images delete $PYTHON_SANDBOX_IMG --delete-tags --quiet
```
3. Artifact Registry リポジトリを削除します。
```
gcloud artifacts repositories delete $REPOSITORY_NAME --location=$GKE_LOCATION --quiet
```
次のステップ
- Agent Sandbox オープンソースプロジェクトの詳細については、GitHub をご覧ください。
- ワークロードのセキュリティ分離を提供する基盤となるテクノロジーについては、GKE Sandbox をご覧ください。
- クラスタとワークロードのセキュリティ強化の詳細については、GKE セキュリティの概要をご覧ください。

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

費用

始める前に

環境変数を定義する

Agent Sandbox をデプロイする

GKE クラスタを作成する

Autopilot

Standard

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

Deployment を確認する

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

Artifact Registry リポジトリを作成する

Python サンプルアプリをビルドして push する

`SandboxTemplate` を作成する

`SandboxClaim` を作成してサンドボックスを作成する

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

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

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

次のステップ

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

費用

始める前に

環境変数を定義する

Agent Sandbox をデプロイする

GKE クラスタを作成する

Autopilot

Standard

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

Deployment を確認する

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

Artifact Registry リポジトリを作成する

Python サンプルアプリをビルドして push する

SandboxTemplate を作成する

SandboxClaim を作成してサンドボックスを作成する

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

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

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

次のステップ

`SandboxTemplate` を作成する

`SandboxClaim` を作成してサンドボックスを作成する