Interactions API

Interactions API adalah 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-giliran multi-modal 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 kemampuan gemini-interactions-api untuk memberi asisten Anda akses langsung 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 tersimpan (diambil melalui interactions.get) juga mencakup langkah user_input untuk konteks lengkap, meskipun respons interactions.create hanya menampilkan langkah yang dihasilkan model.

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

Mengakses output dengan properti praktis SDK

Meskipun Interactions API menampilkan linimasa langkah eksekusi yang terstruktur (seperti pemikiran, kueri penelusuran, dan panggilan fungsi), Anda tidak perlu menelusuri langkah-langkah secara manual untuk mendapatkan respons model akhir.

Google GenAI SDK menyediakan properti praktis langsung pada objek Interaction yang ditampilkan untuk mengakses output untuk berbagai modalitas:

Properti praktis SDK Jenis Nilai yang Ditampilkan Deskripsi
interaction.output_text String Menampilkan blok teks terakhir dalam respons model. Jika respons dibagi di beberapa blok TextContent berturut-turut, respons akan otomatis digabungkan. Respons tidak menyertakan blok teks sebelumnya yang dipisahkan oleh konten non-teks (seperti pemikiran, gambar, audio, atau panggilan alat). Untuk respons multimodal yang kompleks atau disisipkan, Anda harus melakukan iterasi secara manual atas steps.
interaction.output_image ImageContent atau None Menampilkan blok gambar terakhir yang dihasilkan oleh model dalam permintaan saat ini.
interaction.output_audio AudioContent atau None Menampilkan blok audio terakhir yang dihasilkan oleh model dalam permintaan saat ini.

Untuk kasus penggunaan lanjutan—seperti merender proses berpikir perantara, memeriksa panggilan alat langkah demi langkah, atau melakukan debug—Anda masih dapat memeriksa dan menelusuri linimasa interaction.steps mentah secara manual.

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 observabilitas.

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

Jika tidak menginginkannya, 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 tersimpan kapan saja menggunakan metode penghapusan yang ditemukan 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.5 Flash Model gemini-3.5-flash
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 seterusnya.
  • Di JavaScript, ini adalah paket @google/genai dari versi 1.33.0 dan seterusnya.

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 di 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 menyediakan 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 beban kerja produksi, Anda harus terus menggunakan standar generateContent API. API ini tetap menjadi jalur yang direkomendasikan untuk deployment yang stabil, dan kami akan terus mengembangkan dan mempertahankannya secara aktif.

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