Panduan memulai sandbox shell

Sandbox shell adalah container Linux terisolasi dan terkelola yang terlampir ke instance Agent Platform. Sandbox menjalankan perintah shell yang dikirim oleh agen Anda dan menampilkan stdout, stderr, dan kode keluar. Tidak ada yang berjalan di infrastruktur Anda sendiri, dan container akan dihancurkan saat sandbox dihapus.

Gunakan sandbox shell saat agen perlu menjalankan perintah shell yang tidak tepercaya atau dihasilkan, menginstal paket, memanipulasi file, atau menjalankan alat command line tanpa mengekspos lingkungan Anda.

Batasan

• send_command() dan execute_code() tidak berfungsi dengan sandbox shell. Metode ini menargetkan sandbox Eksekusi Kode dan mengirim payload Python, yang tidak diterima oleh container shell. Menggunakan /exec dengan sandbox shell.

Sebelum memulai

Menyiapkan project dan lingkungan Anda.

Menyiapkan project

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

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

Mendapatkan peran yang diperlukan

Untuk menggunakan sandbox, Anda memerlukan peran berikut:

• Pengguna Agent Platform (roles/aiplatform.user) di project.

Menginstal library

Instal SDK dengan modul Agent Platform:

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

Autentikasikan

Untuk melakukan autentikasi dengan Kredensial Default Aplikasi:

gcloud auth application-default login

Membuat instance Agent Platform

Untuk menggunakan sandbox shell, buat instance Agent Platform terlebih dahulu. Anda tidak perlu men-deploy agen untuk menggunakan sandbox shell. Tanpa deployment, pembuatan instance Platform Agen akan memerlukan waktu beberapa detik.

import vertexai

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

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

Ganti kode berikut:

• PROJECT_ID: Project ID Google Cloud Anda.

• LOCATION: Google Cloud Region untuk instance Agent Platform Anda. Lihat Wilayah yang didukung.

Membuat sandbox shell

Anda harus memberikan setidaknya salah satu hal berikut saat membuat sandbox:

• spec dengan set lingkungan (shell_environment)
• config.sandbox_environment_template (template default dibuat jika tidak ditentukan. Untuk mengetahui informasi selengkapnya, lihat Menggunakan kembali template di seluruh sandbox)
• config.sandbox_environment_snapshot

Contoh berikut meneruskan shell_environment dalam spesifikasi sandbox:

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)

Setelah sandbox siap, sandbox akan mencetak respons yang mirip dengan berikut ini:

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

Sandbox biasanya mencapai STATE_RUNNING dalam waktu sekitar 20 detik.

Menjalankan perintah

Untuk menjalankan perintah shell di sandbox, gunakan fungsi bantuan execute_bash(), yang mengirimkan perintah ke container:

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

Perintah ini menampilkan stdout, stderr, returncode, dan duration_ms:

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

execute_bash() mengautentikasi dengan kredensial Anda sendiri, sehingga Anda tidak memerlukan akun layanan atau JWT yang ditandatangani.

Opsional: Anda dapat menetapkan cwd secara eksplisit untuk memilih direktori kerja dan timeout untuk membatasi durasi perintah dapat berjalan. Jika tidak, sandbox akan menggunakan defaultnya sendiri (/workspace dan batas waktu sandbox):

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

Untuk mengetahui apakah perintah gagal, periksa returncode dan 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}

Saat menggunakan lingkungan penampung, pertimbangkan hal berikut:

• Perintah dijalankan sebagai pengguna tanpa hak istimewa appuser; tidak ada sudo.
• Setiap perintah berjalan di shell baru, sehingga variabel cd dan shell tidak diteruskan di antara panggilan. Rangkai dalam satu perintah, atau tulis status ke file di bawah /workspace.
• Akses internet keluar dinonaktifkan kecuali jika template mengaktifkannya.

Pembersihan

Untuk menghapus sandbox dan berhenti menimbulkan biaya, jalankan perintah berikut:

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

Langkah berikutnya

• Mengelola sandbox
• Mengelola template sandbox