Shell 沙箱快速入門導覽課程

Shell 沙箱是附加至 Agent Platform 執行個體的受管理獨立 Linux 容器。沙箱會執行代理傳送的殼層指令，並傳回 stdout、stderr 和結束代碼。您自己的基礎架構不會執行任何作業，且容器會在沙箱刪除時一併銷毀。

如果代理程式需要執行不受信任或產生的殼層指令、安裝套件、操控檔案，或驅動指令列工具，但不想公開環境，請使用殼層沙箱。

限制

• send_command() 和 execute_code() 無法搭配 Shell 沙箱使用。這些方法會以程式碼執行沙箱為目標，並傳送 Python 酬載，但殼層容器不接受這類酬載。搭配使用 /exec 與 Shell 沙箱。

事前準備

設定專案和環境。

設定專案

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

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 Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

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 Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

取得必要角色

如要使用沙箱，您必須具備下列角色：

• 專案的 Agent Platform 使用者 (roles/aiplatform.user)。

安裝程式庫

使用 Agent Platform 模組安裝 SDK：

pip install "google-cloud-aiplatform[agent_engines]"

驗證

如要使用應用程式預設憑證進行驗證，請按照下列步驟操作：

gcloud auth application-default login

建立 Agent Platform 執行個體

如要使用 Shell 沙箱，請先建立 Agent Platform 執行個體。您不需要部署代理程式，即可使用 Shell 沙箱。 建立 Agent Platform 執行個體時，如果沒有部署作業，應該只需要幾秒鐘。

import vertexai

client = vertexai.Client(project='PROJECT_ID', location='LOCATION')

agent_engine = client.agent_engines.create()
agent_engine_name = agent_engine.api_resource.name

更改下列內容：

• PROJECT_ID： Google Cloud 專案 ID。

• LOCATION：Agent Platform 執行個體的 Google Cloud 區域。請參閱「支援的區域」。

建立殼層沙箱

建立沙箱時，您至少需要提供下列其中一項：

• spec，並設定環境 (shell_environment)
• config.sandbox_environment_template (如未指定，系統會建立預設範本。詳情請參閱「在沙箱之間重複使用範本」一文。
• config.sandbox_environment_snapshot

以下範例會在沙箱規格中傳遞 shell_environment：

engine = (
    "projects/PROJECT_ID/locations/LOCATION"
    "/reasoningEngines/INSTANCE_ID"
)

operation = client.agent_engines.sandboxes.create(
    name=engine,
    spec={"shell_environment": {}},
    config={
        "display_name": "my-shell-sandbox",
        "wait_for_completion": True,
        "ttl": "3600s",
    },
)
sandbox = operation.response
print(sandbox.name, sandbox.state)

沙箱就緒時，會顯示類似以下內容的回應：

projects/.../sandboxEnvironments/1035360621853409280 SandboxState.STATE_RUNNING

沙箱通常會在 20 秒內達到 STATE_RUNNING。

執行指令

如要在沙箱中執行殼層指令，請使用輔助函式 execute_bash()，將指令傳送至容器：

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="echo hello && whoami && pwd",
)
print(result)

這項指令會傳回 stdout、stderr、returncode 和 duration_ms：

{'stdout': 'hello\nappuser\n/workspace\n', 'stderr': '', 'returncode': 0, 'duration_ms': 8}

execute_bash() 會使用您自己的憑證進行驗證，因此不需要服務帳戶或簽署的 JWT。

選用：您可以明確設定 cwd，選擇目前使用的目錄，並設定 timeout，限制指令的執行時間。否則，沙箱會使用自己的預設值 (/workspace 和沙箱的時間限制)：

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="pytest -q",
    cwd="/workspace/app",
    timeout=120,
)

如要瞭解指令是否失敗，請檢查 returncode 和 stderr：

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="ls /nope",
)
print(result)

{'stdout': '', 'stderr': "ls: cannot access '/nope': No such file or directory\n", 'returncode': 2, 'duration_ms': 5}

使用容器環境時，請注意下列事項：

• 指令會以無權限使用者 appuser 的身分執行，不會有 sudo。
• 每個指令都會在新殼層中執行，因此 cd 和殼層變數不會在呼叫之間傳遞。將這些指令串連成一個指令，或將狀態寫入 /workspace 下的檔案。
• 除非範本啟用連出網際網路存取權，否則這項功能會處於關閉狀態。

清除所用資源

如要刪除沙箱並停止產生費用，請執行下列指令：

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

後續步驟

• 管理沙箱
• 管理沙箱範本