Eksekusi latar belakang

Untuk tugas yang berjalan lama seperti riset mendalam, penalaran kompleks, atau eksekusi agen multi-langkah, waktu tunggu koneksi dapat mengganggu permintaan HTTP standar (yang biasanya ditutup setelah 60 detik). Interactions API menyediakan eksekusi latar belakang untuk menjalankan tugas ini secara asinkron.

Agar interaksi berjalan hingga menyelesaikan tugas di server, tetapkan "background": true saat membuat interaksi. API akan segera menampilkan ID interaksi, yang dapat digunakan aplikasi klien untuk melakukan polling status, memproses streaming, atau menghubungkan kembali ke streaming yang terputus.

Eksekusi di latar belakang didukung untuk model Gemini standar (seperti gemini-3.6-flash dan gemini-3.1-pro-preview) dan Agen Terkelola (seperti antigravity-preview-05-2026).

Membuat interaksi latar belakang

Untuk memulai interaksi latar belakang, tetapkan parameter background ke true saat membuat resource.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.6-flash",
    input="Write a guide on space exploration.",
    background=True,
)
print(f"Created background interaction ID: {interaction.id}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.6-flash",
    input: "Write a guide on space exploration.",
    background: true,
});
console.log(`Created background interaction ID: ${interaction.id}`);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.6-flash",
    "input": "Write a guide on space exploration.",
    "background": true
  }'

Cara kerja eksekusi latar belakang

Saat Anda membuat interaksi latar belakang, tugas akan berjalan secara asinkron di server. Interaksi bertransisi melalui berbagai status eksekusi:

  • in_progress: Server sedang aktif menjalankan interaksi (seperti menjalankan kode atau melakukan riset).
  • requires_action: Interaksi telah dijeda dan menunggu input klien (seperti mengonfirmasi eksekusi alat atau menjawab pertanyaan).
  • completed: Interaksi berhasil diselesaikan dan output tersedia.
  • failed: Terjadi error selama eksekusi (seperti kegagalan alat atau batas kecepatan).
  • cancelled: Permintaan klien menghentikan eksekusi.

Kasus penggunaan

Gunakan eksekusi latar belakang untuk:

  • Eksekusi agen: Tugas yang memerlukan eksekusi kode, penjelajahan web, atau orkestrasi sub-agen (seperti antigravity-preview-05-2026).

  • Deep Research: Berjalan menggunakan deep-research-preview-04-2026 atau deep-research-max-preview-04-2026 yang memerlukan waktu beberapa menit.

  • Penalaran panjang: Tugas yang langkah-langkah pemikiran model melebihi batas koneksi HTTP standar.

Mengambil hasil

Dapatkan hasil interaksi latar belakang menggunakan polling atau streaming.

Pola polling (tidak memblokir)

Polling memeriksa status interaksi secara berkala menggunakan permintaan GET non-blocking hingga mencapai status terminal.