使用 Agent Sandbox 隔離 AI 程式碼執行作業

本文提供操作說明，協助您在 Google Kubernetes Engine (GKE) 叢集上安裝及執行 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.

    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 叢集) 都是在正確的專案中建立。
    • ：GKE 叢集的名稱，例如 agent-sandbox-cluster。CLUSTER_NAME
    • GKE_LOCATION：要建立 GKE 叢集和 Artifact Registry 存放區的 Google Cloud 區域，例如 us-central1。建議您將兩者放在同一位置，因為這樣可縮短映像檔提取延遲時間。
    • 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 叢集。這個叢集提供 Kubernetes 環境，您將在其中部署及執行 Agent Sandbox 控制器和範例沙箱應用程式。gVisor 提供沙箱技術，可安全地執行不受信任的程式碼。

    您可以建立 Autopilot 或標準叢集。 Autopilot 會自動啟用 gVisor，但 Standard 叢集需要您手動建立啟用 gVisor 的節點集區：

    Autopilot

    如要使用 gcloud CLI 建立 Autopilot 叢集，請執行下列指令：

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

    標準

    如要使用 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 可以連線至叢集。這項指令會更新 Kubernetes 設定檔，該檔案預設儲存在 ~/.kube/config 目錄中。這個設定檔包含 kubectl 與 GKE 叢集互動時所需的憑證：

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

    將 Agent Sandbox 控制器部署至叢集

    您可以將正式發布的資訊清單套用至叢集，部署 Agent Sandbox 控制器及其必要元件。這些資訊清單是設定檔，可指示 Kubernetes 下載在叢集上部署及執行 Agent Sandbox 控制器所需的所有必要元件。

    執行下列指令，將 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 控制器 Pod 是否在 agent-sandbox-system 命名空間中正常運作：

    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 程式庫可讓您透過程式建立、使用及刪除沙箱。

    用戶端會使用 Sandbox Router 做為所有流量的中央進入點。在本文件所述的範例中，用戶端會使用 kubectl port-forward 指令建立通往這個路由器的通道，因此您不需要公開任何 IP 位址。請注意，使用 kubectl port-forward 並非安全解決方案，因此僅限於開發環境。

    建立 SandboxTemplate 和 SandboxWarmPool

    您現在可以建立 SandboxTemplate 和 SandboxWarmPool 資源，定義沙箱的設定。SandboxTemplate 可做為可重複使用的藍圖，Agent Sandbox 控制器會使用這個藍圖建立一致的預先設定沙箱環境。SandboxWarmPool 資源可確保指定數量的預先暖機 Pod 隨時處於執行狀態，並可供認領。預先暖機的沙箱是已初始化的執行中 Pod。這項預先初始化作業可讓您在不到一秒內建立新的沙箱，並避免啟動一般沙箱時的啟動延遲：

    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 指令，在本機電腦與叢集中執行的 Sandbox Router 服務之間建立直接通道。這種通道方法不需要公開 IP 位址或複雜的進入設定，可簡化從本機環境與沙箱互動的程序。

    請按照下列步驟部署 Sandbox Router：

    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 用戶端

    現在已部署 Sandbox Router 等叢集內元件，最後一個準備步驟是在本機安裝 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 目錄中，建立名為 test_sandbox.py 的 Python 指令碼，並加入下列內容：

      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!」訊息，這是沙箱輸出的內容。

    恭喜！您已在安全沙箱中成功執行 Shell 指令。使用 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 安全性總覽。