Managed Agents API di lingkungan sandbox Agent Platform

Managed Agents API di Agent Platform beroperasi dengan sandbox Linux standar yang terisolasi. Dalam penampung eksekusi yang aman dan terkelola sepenuhnya ini, agen kustom dapat melakukan penalaran, merencanakan alur kerja, mengeksekusi perintah bash, serta 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 mendeklarasikan jaringan allowlist secara eksplisit untuk mengizinkan agen 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 skill dari Skill Registry.

Izin dan keamanan sandbox

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

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

  • Eksekusi hak istimewa terendah: Setelah akses jaringan diaktifkan, penampung tidak memiliki kredensial atau izin administratif dengan hak istimewa. Secara default, hanya dapat mengirimkan kueri ke lokasi internet yang dapat diakses secara publik.

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

  • Pencakupan kredensial MCP: Konfigurasi header untuk server Model Context Protocol (MCP), yang berisi token autentikasi backend, hanya ditransmisikan 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 sudah diinstal sebelumnya

Sandbox berisi set 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 di 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 menempatkan setiap skill dalam target direktori yang ditentukan, dengan mempertahankan struktur direktori paket skill asli. Organisasi ini membantu memastikan bahwa file keterampilan individu 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 disusun 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.