Mengelola sandbox

Halaman ini menunjukkan cara mengelola siklus proses lingkungan sandbox menggunakan Python SDK. Anda dapat mencantumkan sandbox yang ada, melihat detailnya, menjeda dan melanjutkannya, atau menghapusnya jika tidak lagi diperlukan.

Sebelum memulai

Untuk mengelola sandbox, Anda memerlukan peran berikut di project Anda:

  • Pengguna Agent Platform (roles/aiplatform.user)

Mengelola sandbox

Anda dapat mencantumkan, melihat detail, menjeda, melanjutkan, dan menghapus lingkungan sandbox yang terkait dengan instance Agent Platform. Dengan fitur jeda dan lanjutkan, Anda dapat membatalkan jadwal resource komputasi untuk sandbox yang tidak ada aktivitas dan mengaktifkannya kembali nanti tanpa kehilangan status sistem file atau identitas koneksi. Untuk mengubah konfigurasi sandbox yang ada, Anda harus menghapusnya dan membuat yang baru.

Mencantumkan sandbox

Untuk mencantumkan semua sandbox yang terkait dengan instance Agent Platform:

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
instance_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID'

sandboxes = client.sandboxes.list(name=instance_name)

for sandbox in sandboxes:
    print(sandbox.name)

Ganti kode berikut:

  • PROJECT_ID: Project ID Google Cloud Anda.
  • LOCATION: Region Google Cloud instance Agent Platform Anda. Lihat Wilayah yang didukung.
  • INSTANCE_ID: ID instance Agent Platform.

Melihat detail sandbox

Untuk melihat konfigurasi dan status sandbox tertentu:

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

sandbox = client.sandboxes.get(name=sandbox_name)
print(sandbox)

Ganti kode berikut:

  • PROJECT_ID: Project ID Google Cloud Anda.
  • LOCATION: Region Google Cloud instance Agent Platform Anda. Lihat Wilayah yang didukung.
  • INSTANCE_ID: ID instance Agent Platform yang berisi sandbox Anda.
  • SANDBOX_ID: ID sandbox yang ada.

Output-nya mencakup detail seperti waktu pembuatan, status (misalnya, STATE_RUNNING), dan spesifikasi sandbox.

Menjeda sandbox

Menjeda sandbox akan merilis resource komputasinya sekaligus mempertahankan status disk dan metadata koneksi. Sandbox yang dijeda jauh lebih murah daripada yang berjalan dan dapat dilanjutkan dalam hitungan detik. Gunakan jeda saat sandbox tidak ada aktivitas dalam waktu lama, tetapi Anda ingin mempertahankan status sesi dan identitas koneksi untuk digunakan nanti.

Sandbox yang dijeda memiliki karakteristik berikut:

  • Mempertahankan ID sandbox, metadata koneksi, dan endpoint Private Service Connect apa pun.
  • Mempertahankan semua status sistem file dalam container pada saat dijeda.
  • Transisi ke STATE_PAUSED. Permintaan ke endpoint bidang data akan menampilkan error hingga Anda melanjutkan.

Untuk menjeda sandbox yang sedang berjalan, jalankan kode berikut:

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

pause_operation = client.sandboxes.pause(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_PAUSED.
    },
)
paused_sandbox = pause_operation.response
print(f"Sandbox {paused_sandbox.name} state: {paused_sandbox.state}")  # STATE_PAUSED

Ganti kode berikut:

  • PROJECT_ID: Project ID Google Cloud Anda.
  • LOCATION: Region Google Cloud instance Agent Platform Anda. Lihat Wilayah yang didukung.
  • INSTANCE_ID: ID instance Agent Platform yang berisi sandbox Anda.
  • SANDBOX_ID: ID sandbox yang ada.

Melanjutkan sandbox

Melanjutkan sandbox yang dijeda akan membuat komputasinya kembali online. Sandbox mempertahankan ID, endpoint koneksi (termasuk lampiran layanan Private Service Connect), dan status sistem file yang sama seperti saat dijeda. Permintaan bidang data dapat dibuat ke sandbox lagi segera setelah operasi dilanjutkan.

Untuk melanjutkan sandbox yang dijeda, jalankan kode berikut:

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

resume_operation = client.sandboxes.resume(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_RUNNING.
    },
)
resumed_sandbox = resume_operation.response
print(f"Sandbox {resumed_sandbox.name} state: {resumed_sandbox.state}")  # STATE_RUNNING

Ganti kode berikut:

  • PROJECT_ID: Project ID Google Cloud Anda.
  • LOCATION: Region Google Cloud instance Agent Platform Anda. Lihat Wilayah yang didukung.
  • INSTANCE_ID: ID instance Agent Platform yang berisi sandbox Anda.
  • SANDBOX_ID: ID sandbox yang dijeda.

Menghapus sandbox

Untuk menghapus lingkungan sandbox secara eksplisit dan mengosongkan resource:

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

Pemantauan dan log audit

Saat Anda mengelola dan menjalankan perintah di sandbox, Agent Platform mencatat aktivitas tingkat API di Cloud Audit Logs dengan nama layanan aiplatform.googleapis.com dan jenis resource yang dipantau audited_resource:

  • Log Aktivitas Admin (ADMIN_WRITE): Direkam secara otomatis untuk mutasi siklus proses bidang kontrol, termasuk CreateSandboxEnvironment, PauseSandboxEnvironment, ResumeSandboxEnvironment, SnapshotSandboxEnvironment, dan DeleteSandboxEnvironment (memerlukan izin IAM aiplatform.sandboxEnvironments.*).
  • Log Akses Data (ADMIN_READ): Dicatat saat diaktifkan untuk operasi baca metadata, termasuk GetSandboxEnvironment dan ListSandboxEnvironments.
  • Log Akses Data (DATA_WRITE): Dicatat saat diaktifkan untuk eksekusi perintah bidang data dan panggilan otorisasi akses, termasuk ExecuteSandboxEnvironment, BidiExecuteSandboxEnvironment, AuthorizeSandboxEnvironmentAccess, dan ExecuteCode. Untuk resource yang dilindungi oleh Kontrol Layanan VPC, payload permintaan dan respons dihilangkan dari log audit.

Perhatikan batasan kemampuan observasi dan deteksi ancaman berikut:

  • Aktivitas proses dan streaming dalam container: Cloud Audit Logs mencatat permintaan API yang memulai eksekusi perintah atau mengizinkan koneksi, tetapi tidak mencatat setiap proses turunan yang dihasilkan di dalam container, modifikasi sistem file, atau frame interaktif berikutnya yang dikirim melalui sesi WebSocket, Chrome DevTools Protocol (CDP), atau PTY yang terbuka.
  • Logging container stdout dan stderr: Pengumpulan Cloud Logging otomatis untuk Agent Runtime (seperti reasoning_engine_stdout dan reasoning_engine_stderr) hanya berlaku untuk instance ReasoningEngine induk dan tidak otomatis mengumpulkan log dari resource turunan sandbox. Output perintah (stdout, stderr, dan kode keluar) ditampilkan dalam respons eksekusi ke agen induk, tempat Anda dapat memeriksa dan menulis entri terstruktur ke Cloud Logging.
  • Deteksi ancaman dan pemeriksaan jaringan: Sandbox menerapkan pembatasan melalui isolasi kernel gVisor dan identitas dalam sandbox tanpa hak istimewa tanpa kredensial Google Cloud ambien. Untuk memantau perilaku anomali atau egress jaringan yang tidak sah, gabungkan log audit DATA_WRITE dengan Agent anomaly detection pada agen induk dan rute egress sandbox melalui antarmuka Private Service Connect dengan Log Aliran Traffic VPC, logging aturan Cloud Next Generation Firewall (Cloud NGFW), dan pemeriksaan Secure Web Proxy. Untuk mengetahui detailnya, lihat Batas keamanan, identitas, dan kemampuan observasi.