Interactions API

Interactions API adalah primitif standar baru untuk membangun dengan Gemini, yang direkomendasikan untuk semua project baru. API ini dioptimalkan untuk alur kerja agen, pengelolaan status sisi server, dan percakapan multi-modal dan multi-giliran yang kompleks. API generateContent asli tetap didukung sepenuhnya.

Mengapa menggunakan Interactions API?

  • Pengelolaan histori sisi server: Alur multi-giliran yang disederhanakan melalui previous_interaction_id. Server mengaktifkan status secara default (store=true), tetapi Anda dapat memilih perilaku tanpa status dengan menetapkan store=false.
  • Langkah eksekusi yang dapat diamati: Langkah-langkah yang diketik memudahkan proses debug alur yang kompleks dan merender UI untuk peristiwa perantara (seperti pemikiran atau widget penelusuran).
  • Dibuat untuk alur kerja agen: Dukungan native untuk penggunaan alat multi-langkah, orkestrasi, dan alur penalaran yang kompleks melalui langkah-langkah eksekusi yang diketik.
  • Tugas latar belakang dan berjalan lama: Mendukung operasi yang memakan waktu seperti Deep Think dan Deep Research ke proses latar belakang menggunakan background=true.
  • Akses ke model dan kemampuan baru: Ke depannya, model baru di luar keluarga utama inti, beserta kemampuan dan alat agen baru, akan diluncurkan secara eksklusif di Interactions API.

Gunakan Interactions API jika Anda memulai project baru, membuat aplikasi agen, atau memerlukan pengelolaan percakapan sisi server. Gunakan generateContent jika Anda memiliki integrasi yang ada dan sesuai dengan kebutuhan Anda, atau jika Anda memerlukan fitur yang belum tersedia di Interactions API, seperti Batch API atau caching eksplisit.

Mulai

  • Menyiapkan agen coding: Hubungkan ke Gemini Docs MCP dan instal keterampilan gemini-interactions-api untuk memberikan akses langsung kepada asisten Anda ke dokumen developer dan praktik terbaik terbaru. Menyiapkan agen coding →
  • Bermigrasi dari generateContent: Jika Anda memiliki integrasi yang ada, ikuti Panduan Migrasi untuk bertransisi ke Interactions API.
  • Coba panduan memulai: Mulai dengan contoh kerja minimal di panduan memulai Interactions API.

Panduan Fitur

Pelajari kemampuan spesifik Interactions API melalui panduan ini. Anda dapat menggunakan tombol di halaman ini untuk beralih antara generateContent dan Interactions API:

Cara kerja Interactions API

Interactions API berpusat pada resource inti: Interaction. Interaction mewakili giliran lengkap dalam percakapan atau tugas. Tindakan ini berfungsi sebagai catatan sesi, yang berisi seluruh histori interaksi sebagai urutan kronologis langkah eksekusi. Langkah-langkah ini mencakup pemikiran model, panggilan dan hasil alat sisi server atau sisi klien (seperti function_call dan function_result), serta model_output akhir. Resource yang disimpan (diambil melalui interactions.get) juga mencakup langkah-langkah user_input untuk konteks lengkap, meskipun respons interactions.create hanya menampilkan langkah-langkah yang dibuat model.

Saat melakukan panggilan ke interactions.create, Anda membuat resource Interaction baru.

Pengelolaan status sisi server

Anda dapat menggunakan id interaksi yang telah selesai dalam panggilan berikutnya menggunakan previous_interaction_id parameter untuk melanjutkan percakapan. Server menggunakan ID ini untuk mengambil histori percakapan, sehingga Anda tidak perlu mengirim ulang seluruh histori chat.

Parameter previous_interaction_id hanya mempertahankan histori percakapan (input dan output) menggunakan previous_interaction_id. Parameter lainnya bercakupan interaksi dan hanya berlaku untuk interaksi tertentu yang saat ini Anda buat:

  • tools
  • system_instruction
  • generation_config (termasuk thinking_level, temperature, dll.)

Artinya, Anda harus menentukan ulang parameter ini di setiap interaksi baru jika ingin menerapkannya. Pengelolaan status sisi server ini bersifat opsional; Anda juga dapat beroperasi dalam mode tanpa status dengan mengirimkan histori percakapan lengkap di setiap permintaan.

Penyimpanan dan retensi data

Secara default, API menyimpan semua objek Interaksi (store=true) untuk menyederhanakan penggunaan fitur pengelolaan status sisi server (dengan previous_interaction_id), eksekusi latar belakang (menggunakan background=true), dan tujuan observasi.

  • Paket Berbayar: Sistem menyimpan interaksi selama 55 hari.
  • Paket Gratis: Sistem menyimpan interaksi selama 1 hari.

Jika tidak menginginkan hal ini, Anda dapat menetapkan store=false dalam permintaan. Kontrol ini terpisah dari pengelolaan status; Anda dapat memilih untuk tidak menyimpan interaksi apa pun. Namun, perhatikan bahwa store=false tidak kompatibel dengan background=true dan mencegah penggunaan previous_interaction_id untuk giliran berikutnya.

Anda dapat menghapus interaksi yang disimpan kapan saja menggunakan metode penghapusan yang terdapat di Referensi API. Anda hanya dapat menghapus interaksi jika mengetahui ID interaksi.

Setelah periode retensi berakhir, data Anda akan otomatis dihapus.

Sistem memproses objek Interaksi sesuai dengan persyaratan.

Praktik terbaik

  • Rasio hit cache: Menggunakan previous_interaction_id untuk melanjutkan percakapan memungkinkan sistem lebih mudah memanfaatkan caching implisit untuk histori percakapan, yang meningkatkan performa dan mengurangi biaya.
  • Mencampur interaksi: Anda memiliki fleksibilitas untuk mencampur dan mencocokkan interaksi Agen dan Model dalam percakapan. Misalnya, Anda dapat menggunakan agen khusus, seperti agen Deep Research, untuk pengumpulan data awal, lalu menggunakan model Gemini standar untuk tugas lanjutan seperti meringkas atau memformat ulang, dengan menautkan langkah-langkah ini dengan previous_interaction_id.

Model &agen yang didukung

Nama Model Jenis ID Model
Gemini 3.1 Flash-Lite Model gemini-3.1-flash-lite
Pratinjau Gemini 3.1 Flash-Lite Model gemini-3.1-flash-lite-preview
Pratinjau Gemini 3.1 Pro Model gemini-3.1-pro-preview
Pratinjau Gemini 3 Flash Model gemini-3-flash-preview
Gemini 2.5 Pro Model gemini-2.5-pro
Gemini 2.5 Flash Model gemini-2.5-flash
Gemini 2.5 Flash-lite Model gemini-2.5-flash-lite
Pratinjau Klip Lyria 3 Model lyria-3-clip-preview
Pratinjau Lyria 3 Pro Model lyria-3-pro-preview
Pratinjau Deep Research Agen deep-research-pro-preview-12-2025
Pratinjau Deep Research Agen deep-research-preview-04-2026
Pratinjau Deep Research Agen deep-research-max-preview-04-2026

SDK

Anda dapat menggunakan Google GenAI SDK versi terbaru untuk mengakses Interactions API.

  • Di Python, ini adalah paket google-genai dari versi 1.55.0 dan yang lebih baru.
  • Di JavaScript, ini adalah paket @google/genai dari versi 1.33.0 dan yang lebih baru.

Anda dapat mempelajari lebih lanjut cara menginstal SDK di halaman Library.

Batasan

  • Status beta: Interactions API dalam versi beta/pratinjau. Fitur dan skema dapat berubah.
  • MCP jarak jauh: Gemini 3 tidak mendukung MCP jarak jauh, tetapi akan segera hadir.

Fitur berikut didukung oleh generateContent API, tetapi belum tersedia di Interactions API:

Perubahan yang dapat menyebabkan gangguan

Interactions API saat ini berada dalam tahap beta awal. Kami secara aktif mengembangkan dan menyempurnakan kemampuan API, skema resource, dan antarmuka SDK berdasarkan penggunaan dunia nyata dan masukan developer. Oleh karena itu, perubahan yang dapat menyebabkan gangguan mungkin terjadi.

Perubahan yang dapat menyebabkan gangguan yang ada:

  • Skema langkah: Array langkah baru menggantikan array output, yang memberikan linimasa terstruktur dari setiap giliran interaksi.

Untuk mempelajari perubahan yang dapat menyebabkan gangguan terbaru dan memahami cara bermigrasi, lihat Panduan migrasi perubahan yang dapat menyebabkan gangguan (Mei 2026).

Potensi pembaruan lainnya dapat mencakup perubahan pada skema untuk input dan output, tanda tangan metode SDK dan struktur objek, serta perilaku fitur tertentu.

Untuk workload produksi, Anda harus terus menggunakan API standar generateContent. API ini tetap menjadi jalur yang direkomendasikan untuk deployment yang stabil, dan kami akan terus aktif mengembangkan dan mempertahankannya.

Masukan

Masukan Anda sangat penting untuk pengembangan Interactions API. Sampaikan pendapat Anda, laporkan bug, atau minta fitur di Forum Komunitas Developer AI Google kami.

Langkah berikutnya