Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

管理 Agent Sandbox 儲存空間

自動駕駛標準

本文提供參考實作方式，說明如何管理 Agent Sandbox 的儲存空間，以滿足代理程式的資料生命週期需求。

請根據代理商的資料生命週期需求，選擇下列其中一種設定：

設定具狀態的工作區
設定時間點還原和擁有權轉移
設定暫時性工作區

如要進一步瞭解如何選擇儲存解決方案，請參閱「選擇 AI 代理程式工作負載的儲存空間」。

下列文件使用 dynamic-rwo StorageClass 進行自動磁碟類型選取，以佈建與節點機器類型相容的磁碟，而 Agent Sandbox Pod 會排定在這些節點上執行。為確保 GKE 為代理程式的儲存空間佈建 Hyperdisk Balanced 磁碟區，您必須在相容的機器系列 (例如 N4) 的節點上排定 Agent Sandbox，否則 GKE 會改用 pd-balanced。

本文將使用 ReadWriteOnce (RWO) 存取權，實作私有獨立工作區資料存取模式。在此模式下，代理程式會啟動，並使用專屬的獨立儲存空間目錄，且只有代理程式具有讀取和寫入權限。

除非另有說明，否則本文中的參考實作項目會使用直接建立沙箱，適用於可容忍啟動延遲時間達數秒的代理程式。如要讓有狀態或時間點還原的工作區達到次秒啟動延遲，您必須使用 GKE Agent Sandbox Warm Pools。如要將儲存空間繫結至已聲明的 Warm Pool Pod，需要自訂指令碼和具備權限的 DaemonSet。如需參考實作方式，請參閱這個 GitHub 範例。

其他存取模式

如要支援替代存取模式，可以修改設定中的磁碟區和快照定義：

協作工作區：將 accessModes 變更為 ReadWriteMany，並使用支援 RWX 的 StorageClass，例如 Filestore Multishares (Enterprise) (enterprise-multishare-rwx)。
探索分支工作區：以唯讀模式掛接範本資料夾，並提供可寫入的獨立暫存區。如為基礎範本，您必須使用支援多個唯讀附件的儲存空間，例如存取模式為 ReadOnlyMany (ROX) 的 Hyperdisk ML，或是存取模式為 RWX 的 Filestore Multishares。

事前準備

在叢集中啟用 Agent Sandbox。

設定具狀態的工作區

使用這個模式可保留代理程式檔案的最新狀態。當代理程式工作階段暫停或終止 (代理程式沙箱已刪除)，且代理程式必須保留狀態，並在代理程式工作階段啟動時 (代理程式沙箱已重新建立)，從最新狀態還原資料，這項功能就非常實用。

本節中的參考實作項目會直接建立沙箱，適用於可容忍啟動延遲時間超過數秒的代理程式。

這個方法會使用標準 GKE PersistentVolumeClaim (PVC) 資源，將沙箱連結至包含使用者資料的現有 PVC。

有狀態的工作區模式會依序發生下列事件：

佈建：管理員或自動調度管理工具會使用確定性 ID (例如 pvc-agent-1)，為每個代理程式工作階段手動佈建專屬 PVC。
參照：在沙箱資源中，您可以使用 volumes 區塊內的 persistentVolumeClaim 欄位，指定現有磁碟區的確切 claimName。
延遲時間：建立 Sandbox 時，GKE 必須將 Compute Engine 磁碟動態連結至節點 VM，這會導致標準的數秒延遲。
持續性：工作階段終止 (刪除沙箱) 時，GKE 會分離磁碟，但不會毀損 PVC，確保下一個工作階段能保留最新狀態。

如要設定有狀態的工作區，以便在工作階段之間保留資料，請完成下列小節中的步驟。

佈建持續性工作區 (PVC)

建立使用確定性 ID (例如 pvc-agent-1) 的私有 PersistentVolumeClaim (PVC)。

將下列資訊清單儲存為 pvc-agent-1.yaml：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-agent-1 # Derived directly from the deterministic assignment ID
  namespace: default
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: dynamic-rwo # Selects disk type compatible with the node machine family
  resources:
    requests:
      storage: 10Gi

套用資訊清單：
```
kubectl apply -f pvc-agent-1.yaml
```

由於儲存空間級別使用動態磁碟區繫結，磁碟尚未連接至任何節點。在排定要求該節點的 Pod 之前，節點會維持 Pending 狀態。

部署 Agent Sandbox

部署 Sandbox 自訂資源，並參照確定性 PVC。

將下列資訊清單儲存為 sandbox-agent-1.yaml：

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: sandbox-agent-1 # Traceable sandbox name
  namespace: default
spec:
  replicas: 1
  podTemplate:
    spec:
      runtimeClassName: gvisor # Required
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
        runAsUser: 1000
        fsGroup: 1000 # Grant group access to the volume
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: agent
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        volumeMounts:
        - name: workspace-disk
          mountPath: /workspace # Mounts the private disk into the container
        resources:
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      volumes:
      - name: workspace-disk
        persistentVolumeClaim:
          claimName: pvc-agent-1 # Binds this specific Sandbox to Agent 1's PVC
      restartPolicy: OnFailure

套用資訊清單：
```
kubectl apply -f sandbox-agent-1.yaml
```

GKE 會驗證節點容量並連結磁碟，這需要幾秒鐘的時間。容器會在使用者空間 gVisor 核心內初始化。

從代理程式寫入資料

將文字檔寫入已掛接的磁碟，模擬執行工作區內檔案修改作業的 AI 代理。

# Set the active Pod name
POD_NAME=sandbox-agent-1

# Write a state file to the persistent directory
kubectl exec $POD_NAME -- sh -c "echo 'Workspace State Saved - Agent 1' > /workspace/modified_data.txt"

# Confirm the file exists on the disk
kubectl exec $POD_NAME -- cat /workspace/modified_data.txt

結束代理程式工作階段

如要模擬代理程式閒置時縮減或終止工作階段，請刪除 Sandbox 資源，但保留基礎儲存空間。

kubectl delete sandbox sandbox-agent-1

GKE 會卸載並分離磁碟。pvc-agent-1 PVC 會保留下來，資料也會一併保存。

重新啟用服務專員工作階段

如要重新啟用工作階段，請重新部署參照相同 PVC 的全新 Sandbox 資源。

kubectl apply -f sandbox-agent-1.yaml

磁碟會重新連結 (導致連結延遲)，且容器會啟動。

確認資料保留狀態

檢查新建立的沙箱容器，確認先前的工作階段資料已保留。

# Set the active Pod name of the new session
NEW_POD_NAME=sandbox-agent-1

# Read the file from the newly booted sandbox
kubectl exec -it $NEW_POD_NAME -- cat /workspace/modified_data.txt

輸出內容應顯示 Workspace State Saved - Agent 1。

清除所用資源

刪除 Agent Sandbox 和相關聯的永久磁碟區要求：

kubectl delete sandbox sandbox-agent-1
kubectl delete pvc pvc-agent-1

設定時間點還原和擁有權轉移

使用這個模式複製資料集，即可平行執行實驗、偵錯或獨立作業。代理程式的工作區會從歷史資料集 (或共用狀態) 初始化，並將後續修改內容儲存至獨立的私人可寫入層，不會修改基本範本。

本節中的參考實作項目使用直接沙箱建立作業，適用於可容忍啟動延遲時間超過數秒的代理程式。這種做法會依賴協調器，在啟動新的沙箱工作階段前，從歷來 VolumeSnapshot 動態佈建新的 PersistentVolumeClaim (PVC)。

建立 VolumeSnapshotClass

建立 VolumeSnapshotClass，指定 CSI 驅動程式和刪除政策。如果是 Hyperdisk，請使用 pd.csi.storage.gke.io 驅動程式。

將下列資訊清單儲存為 1-snapshot-class.yaml：

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: standard-rwo-snapshot
driver: pd.csi.storage.gke.io
deletionPolicy: Delete

套用資訊清單：
```
kubectl apply -f 1-snapshot-class.yaml
```

佈建初始工作區

建立代理程式執行初始作業的磁碟區。

將下列資訊清單儲存為 2-source-pvc.yaml：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: agent-source-pvc
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: dynamic-rwo
  resources:
    requests:
      storage: 10Gi

套用資訊清單：
```
kubectl apply -f 2-source-pvc.yaml
```

產生州別資料

部署沙箱 Pod，將資料寫入磁碟區。

將下列資訊清單儲存為 3-source-sandbox.yaml：

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: agent-session-v1
  namespace: default
spec:
  replicas: 1
  podTemplate:
    spec:
      runtimeClassName: gvisor
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
        runAsUser: 1000
        fsGroup: 1000 # Grant group access to the volume
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: agent
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        volumeMounts:
        - name: workspace
          mountPath: /workspace
        resources:
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      volumes:
      - name: workspace
        persistentVolumeClaim:
          claimName: agent-source-pvc
      restartPolicy: OnFailure

套用資訊清單：
```
kubectl apply -f 3-source-sandbox.yaml
```

等待 Pod 執行，然後寫入狀態檔案：

POD_NAME=agent-session-v1
kubectl exec $POD_NAME -- sh -c "echo 'Point-in-Time Snapshot - v1' > /workspace/state.txt"

封存歷來狀態 (CSI VolumeSnapshot)

觸發 CSI VolumeSnapshot，凍結目前狀態。建立快照時，請遵循磁碟快照最佳做法。

將下列資訊清單儲存為 4-volume-snapshot.yaml：

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: agent-session-v1-snapshot
spec:
  volumeSnapshotClassName: standard-rwo-snapshot
  source:
    persistentVolumeClaimName: agent-source-pvc

套用資訊清單：

kubectl apply -f 4-volume-snapshot.yaml

從快照還原磁碟區

部署新的 PVC，並將 dataSource 指向 CSI VolumeSnapshot。

將下列資訊清單儲存為 5-restored-pvc.yaml：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: agent-restored-pvc
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: dynamic-rwo
  dataSource:
    name: agent-session-v1-snapshot
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  resources:
    requests:
      storage: 10Gi

套用資訊清單：
```
kubectl apply -f 5-restored-pvc.yaml
```

啟動還原的 Agent Sandbox 工作階段

佈建參照新還原 PVC 的全新 Sandbox 資源。

將下列資訊清單儲存為 6-restored-sandbox.yaml：

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: agent-session-v2-restored
  namespace: default
spec:
  replicas: 1
  podTemplate:
    spec:
      runtimeClassName: gvisor
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
        runAsUser: 1000
        fsGroup: 1000 # Grant group access to the volume
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: agent
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        volumeMounts:
        - name: workspace
          mountPath: /workspace
        resources:
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      volumes:
      - name: workspace
        persistentVolumeClaim:
          claimName: agent-restored-pvc
      restartPolicy: OnFailure

套用資訊清單：

kubectl apply -f 6-restored-sandbox.yaml

驗證持續性和還原功能

確認代理程式可以讀取歷史資料。

NEW_POD_NAME=agent-session-v2-restored
kubectl exec $NEW_POD_NAME -- cat /workspace/state.txt

預期輸出內容：Point-in-Time Snapshot - v1

清除所用資源

刪除 Agent Sandbox、PVC 和 VolumeSnapshot：

kubectl delete sandbox agent-session-v1
kubectl delete sandbox agent-session-v2-restored
kubectl delete pvc agent-source-pvc
kubectl delete pvc agent-restored-pvc
kubectl delete volumesnapshot agent-session-v1-snapshot
kubectl delete volumesnapshotclass standard-rwo-snapshot

設定暫時性工作區

當代理程式需要儲存空間磁碟區來儲存暫存檔案時，請使用臨時工作區模式。刪除 Agent Sandbox 時，不需要保留任何資料。

設定啟動時間少於一秒

使用 Agent Sandbox Warm Pools 在背景預先佈建空白磁碟區。

定義 SandboxTemplate

在 volumeClaimTemplate 區塊中定義臨時儲存空間備份。

將下列資訊清單儲存為 stateless-template.yaml：

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: stateless-sandbox-template
  namespace: default
spec:
  podTemplate:
    spec:
      runtimeClassName: gvisor
      automountServiceAccountToken: false
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 1000 # Grant group access to the volume
      nodeSelector:
        sandbox.gke.io/runtime: gvisor
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule"
      containers:
      - name: agent
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        volumeMounts:
        - name: ephemeral-disk
          mountPath: /workspace
        resources:
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
  volumeClaimTemplates:
  - metadata:
      name: ephemeral-disk
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: dynamic-rwo # Selects disk type compatible with node machine family
      resources:
        requests:
          storage: 10Gi

啟動沙箱暖集區

將下列資訊清單儲存為 stateless-warmpool.yaml：

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: stateless-warmpool
  namespace: default
spec:
  replicas: 5 # Keep five standby Pods with pre-attached empty disks
  sandboxTemplateRef:
    name: stateless-sandbox-template

套用這兩個資訊清單：

kubectl apply -f stateless-template.yaml
kubectl apply -f stateless-warmpool.yaml

領取沙箱

定義在使用者啟動工作階段時觸發的 SandboxClaim。

將下列資訊清單儲存為 stateless-sandbox-claim.yaml：

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: agent-1-claim
spec:
  sandboxTemplateRef:
    name: stateless-sandbox-template

套用資訊清單：

kubectl apply -f stateless-sandbox-claim.yaml

確認執行時間不到一秒

擷取 Agent Sandbox Pod 名稱，並確認 /workspace 目錄已掛接，可立即使用：

export POD_NAME=$(kubectl get sandboxclaim agent-1-claim -o jsonpath='{.status.sandbox.name}')
kubectl exec $POD_NAME -- ls -la /workspace

終止代理程式工作階段

如要結束代理程式工作階段並釋出已聲明的沙箱，請刪除 SandboxClaim 資源：

kubectl delete sandboxclaim agent-1-claim

清除所用資源

刪除沙箱暖集區和沙箱範本：

kubectl delete sandboxwarmpool stateless-warmpool
kubectl delete sandboxtemplate stateless-sandbox-template

設定多秒啟動

如要實作可容許數秒延遲的暫時性工作區，請不要使用 Warm Pool，直接建立 Agent Sandbox。

定義無狀態 Agent Sandbox

將下列資訊清單儲存為 sandbox-direct-stateless.yaml：

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: sandbox-direct-stateless
  namespace: default
spec:
  replicas: 1
  podTemplate:
    spec:
      runtimeClassName: gvisor
      automountServiceAccountToken: false
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 1000 # Grant group access to the volume
      nodeSelector:
        sandbox.gke.io/runtime: gvisor
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule"
      containers:
      - name: agent
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        volumeMounts:
        - name: ephemeral-disk
          mountPath: /workspace
        resources:
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      restartPolicy: OnFailure
  volumeClaimTemplates:
  - metadata:
      name: ephemeral-disk
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: dynamic-rwo
      resources:
        requests:
          storage: 10Gi

部署 Agent Sandbox

如要動態佈建磁碟並附加至排定的節點，請套用資訊清單：

kubectl apply -f sandbox-direct-stateless.yaml

驗證啟動延遲和執行作業

監控 Pod 狀態，觀察 Pod 轉換為 Running 狀態前的附加延遲：

kubectl get pods -w

Pod 執行後，請擷取 Pod 名稱，並確認 /workspace 目錄可用：

POD_NAME=sandbox-direct-stateless
kubectl exec $POD_NAME -- ls -la /workspace

終止代理程式工作階段

刪除 Sandbox 資源，自動終止 Pod 並銷毀其暫時性儲存空間：

kubectl delete sandbox sandbox-direct-stateless

管理 Agent Sandbox 儲存空間 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

其他存取模式

事前準備

設定具狀態的工作區

佈建持續性工作區 (PVC)

部署 Agent Sandbox

從代理程式寫入資料

結束代理程式工作階段

重新啟用服務專員工作階段

確認資料保留狀態

清除所用資源

設定時間點還原和擁有權轉移

建立 VolumeSnapshotClass

佈建初始工作區

產生州別資料

封存歷來狀態 (CSI VolumeSnapshot)

從快照還原磁碟區

啟動還原的 Agent Sandbox 工作階段

驗證持續性和還原功能

清除所用資源

設定暫時性工作區

設定啟動時間少於一秒

定義 SandboxTemplate

啟動沙箱暖集區

領取沙箱

確認執行時間不到一秒

終止代理程式工作階段

清除所用資源

設定多秒啟動

定義無狀態 Agent Sandbox

部署 Agent Sandbox

驗證啟動延遲和執行作業

終止代理程式工作階段

後續步驟

管理 Agent Sandbox 儲存空間