Managed Agents API di lingkungan sandbox Agent Platform

Managed Agents API di Agent Platform beroperasi dengan sandbox Linux standar yang terisolasi. Dalam container eksekusi yang aman dan terkelola sepenuhnya ini, agen kustom dapat melakukan penalaran, merencanakan alur kerja, menjalankan perintah bash, dan membaca atau menulis file secara langsung.

Setiap lingkungan sandbox menyediakan sistem dan kontrol inti berikut:

  • Sistem file persisten: Mempertahankan file, logika agen, dan status eksekusi dengan aman di seluruh interaksi multi-turn.

  • Terminal Bash: Menyediakan lingkungan yang aman untuk menjalankan perintah terminal, menjalankan skrip kustom, dan memproses file lokal.

  • Isolasi jaringan: Dinonaktifkan secara default. Anda dapat secara eksplisit mendeklarasikan allowlist jaringan agar agen dapat mengakses resource internet publik atau mendownload library eksternal.

  • Integrasi yang dapat diperluas: Mendukung pengimporan kemampuan kustom secara dinamis, termasuk API web standar, server Model Context Protocol (MCP), atau keahlian dari Skill Registry.

Izin dan keamanan sandbox

Untuk mempertahankan batas keamanan standar perusahaan, sandbox jarak jauh beroperasi berdasarkan model izin berikut:

  • Isolasi jaringan: Secara default, sandbox beroperasi tanpa akses jaringan eksternal. Aktifkan konektivitas secara eksplisit dengan menetapkan daftar yang diizinkan untuk domain dalam konfigurasi lingkungan Anda. Lihat Mengonfigurasi akses jaringan untuk mengetahui contoh daftar yang diizinkan.

  • Eksekusi hak istimewa terendah: Setelah akses jaringan diaktifkan, container tidak memiliki kredensial atau izin administratif dengan hak istimewa. Secara default, alat ini hanya dapat mengkueri lokasi internet yang dapat diakses secara publik.

  • Cakupan data untuk pemasangan Cloud Storage dan Skill Registry: Saat Anda melampirkan sumber data eksternal dari Cloud Storage atau Skill Registry, lingkungan akan dilengkapi dengan token otorisasi yang cakupannya dipersempit dan dirancang untuk hanya mengakses direktori atau skill tertentu yang ditentukan dalam konfigurasi agen. Sandbox tidak berisi kredensial ambien dan tidak dapat mengakses repositori atau file lain dalam project Anda.

  • Cakupan kredensial MCP: Konfigurasi header untuk server Model Context Protocol (MCP), yang berisi token autentikasi backend, hanya dikirimkan saat mengakses endpoint MCP tertentu yang ditentukan dalam konfigurasi Anda.

Pengelolaan eksekusi dan siklus proses

Parameter standar ini mengatur eksekusi dan siklus proses sandbox:

  • Lingkungan sandbox: Agen berjalan dengan lingkungan sandbox yang terkelola sepenuhnya, menggunakan harness Antigravity untuk orkestrasi.

  • Time to live (TTL) sandbox: Lingkungan sandbox memiliki time to live (TTL) standar selama 7 hari. Setiap interaksi baru akan otomatis mereset timer ini untuk memastikan agen yang aktif tetap tersedia.

  • Persistensi konfigurasi agen: Backend menyimpan konfigurasi agen secara persisten, dan konfigurasi tersebut akan tetap ada hingga Anda mengirim permintaan DELETE eksplisit ke Agents API.

  • Kolaborasi agen: Beberapa agen berbagi lingkungan yang sama saat Anda memberikan env_id yang sama selama interaksi.

Software yang telah diinstal sebelumnya

Sandbox berisi kumpulan utilitas Linux standar:

Kategori Paket/Alat
Alat UNIX
  • bc
  • curl
  • fd-find
  • gawk
  • gcloud CLI
  • git
  • htop
  • iproute2
  • jq
  • lsof
  • procps
  • ripgrep
  • rsync
  • tree
  • unzip
  • wget
  • which
Paket Python 3.11
  • ast-grep-cli
  • beautifulsoup4
  • google-genai
  • numpy
  • pandas
  • pyyaml
  • requests
Paket Global Node.js 20
  • create-next-app
  • create-vite
  • typescript

Agen dapat menginstal paket tambahan saat runtime menggunakan pip install atau npm install saat akses jaringan diaktifkan. Paket ini tetap ada dalam snapshot lingkungan dan tetap tersedia untuk interaksi yang menggunakan kembali env_id yang sama.

Arsitektur pemasangan skill

Saat Anda mengonfigurasi keahlian eksternal dari sumber seperti Skill Registry dalam base_environment.sources agen, resource ini dilampirkan langsung ke sistem file sandbox. Sistem akan menempatkan setiap skill dalam direktori target yang ditentukan, dengan mempertahankan struktur direktori paket skill asli. Pengaturan ini membantu memastikan bahwa file keterampilan individual tetap dapat ditemukan oleh agen.

Contoh konfigurasi sumber

Contoh berikut melampirkan tiga keterampilan dari Skill Registry:

"sources": [
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/pdf-skill",
    "target": "/.agent/skills/"
  },
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/finance-skill",
    "target": "/.agent/skills/"
  },
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/git-skill",
    "target": "/.agent/other-skills/"
  }
]

Struktur sistem file sandbox setelah pemasangan

Setelah lingkungan sandbox disediakan, file akan dipasang dan distrukturkan dalam container sebagai berikut:

/ (root)
└── .agent/
    ├── skills/                    <-- Mount Target for pdf-skill & finance-skill
    │   ├── pdf-skill/             <-- Preserved skill directory
    │   │   ├── SKILL.md
    │   │   └── scripts/
    │   └── finance-skill/         <-- Preserved skill directory
    │       ├── SKILL.md
    │       └── scripts/
    └── other-skills/              <-- Mount Target for git-skill
        └── git-skill/             <-- Preserved skill directory
            ├── SKILL.md
            └── scripts/

Alat bawaan sandbox

Saat berjalan di lingkungan terkelola, agen memiliki akses ke beberapa alat default:

Nama alat Deskripsi
bash Menjalankan perintah shell di terminal sandbox dan menampilkan output.
file_system Membaca, menulis, dan menghapus konten file, serta mencantumkan konten direktori.

Langkah berikutnya

Ringkasan

Pelajari Managed Agents API di Agent Platform, lingkungan berbasis konfigurasi dan mengutamakan REST untuk membangun agen otonom.

Panduan

Pelajari cara membuat, memperbarui, mencantumkan, mendapatkan, dan menghapus agen menggunakan REST API.

Panduan

Pelajari cara berinteraksi dengan agen saat runtime, mengelola status sesi, dan mengganti konfigurasi secara dinamis.