Ringkasan Interactions API

Interactions API menyediakan antarmuka stateful terpadu untuk membangun aplikasi AI generatif dan alur kerja agentic menggunakan model Gemini dan agen yang dihosting di Gemini Enterprise Agent Platform. generateContent API tetap didukung sepenuhnya bersama dengan Interactions API.

Mengapa menggunakan Interactions API?

Interactions API memberikan beberapa keuntungan utama untuk membangun aplikasi AI generatif dan alur kerja agentic:

  • Satu API untuk model dan agen: Satu endpoint dan pola terpadu untuk memanggil model Gemini standar serta agen khusus secara langsung (seperti Gemini Deep Research Agent dan agen kustom terkelola).
  • Kemampuan baru yang siap pakai: Fitur seperti status percakapan sisi server opsional menggunakan previous_interaction_id, langkah-langkah eksekusi yang dapat diamati untuk proses debug dan rendering UI, serta eksekusi latar belakang untuk tugas yang berjalan lama menggunakan background=true.

Cara kerja Interactions API

Interactions API berpusat pada resource Interaction. Interaction mewakili giliran lengkap dalam percakapan atau tugas dan bertindak sebagai catatan sesi yang berisi urutan kronologis eksekusi steps:

  • user_input: Pesan input, file multimodal, atau hasil alat yang disediakan untuk giliran. Interaksi tersimpan yang diambil dengan interactions.get mencakup langkah-langkah user_input untuk konteks lengkap, sedangkan respons interactions.create hanya menampilkan langkah-langkah yang dihasilkan selama giliran tersebut.
  • thought: Ringkasan penalaran perantara yang dihasilkan oleh model atau agen saat merencanakan responsnya.
  • Langkah panggilan alat dan hasil: Pemanggilan dan output alat sisi klien atau sisi server (seperti function_call dan function_result).
  • model_output: Teks akhir, JSON terstruktur, atau konten multimodal yang dihasilkan oleh model atau agen.

Saat Anda memanggil interactions.create, Agent Platform akan memproses input Anda, menjalankan alat sisi server atau agent loop yang dikonfigurasi, dan menampilkan resource Interaction yang dihasilkan. Untuk contoh kode di Python, TypeScript/JavaScript, dan REST, lihat panduan developer Interactions API.

Model yang didukung

Model Gemini berikut mendukung Interactions API:

Klik untuk meluaskan model yang didukung

Selain model Gemini dalam daftar sebelumnya, Interactions API mendukung model musik generatif berikut: * lyria-3-clip-preview dan lyria-3-pro-preview: Model musik generatif untuk klip audio fidelitas tinggi dan komposisi lagu lengkap (hanya didukung dalam interaksi stateless dengan store=false).

Agen yang didukung

Anda dapat memanggil agen berikut melalui Interactions API dengan menentukan parameter agent, bukan model:

  • antigravity-preview-05-2026: Agen otonom tujuan umum yang dirancang untuk penalaran multi-langkah, coding, operasi file, dan penggunaan alat.
  • deep-research-preview-04-2026: Agen Deep Research Gemini yang dirancang untuk sintesis dan riset web multi-langkah yang otonom.
  • Agen terkelola kustom yang di-deploy di Agent Platform.

Fitur dan spesifikasi

Bagian berikut menjelaskan kemampuan inti, spesifikasi teknis, dan pertimbangan operasional untuk Interactions API.

Pengelolaan status

Secara default, Interactions API menyimpan interaksi di server (store=true) selama 7 hari sehingga Anda dapat merangkai percakapan multi-turn dengan previous_interaction_id dan menjalankan tugas latar belakang asinkron (background=true). Untuk memilih eksekusi stateless dan mendukung alur kerja Zero Data Retention (ZDR), tetapkan store=false. Untuk mengetahui detailnya, lihat Mengelola penyimpanan sesi dan status percakapan.

Batas permintaan dan multimodal

Interactions API menerapkan batas payload permintaan dan input multimodal berikut:

  • Batas payload permintaan: Payload permintaan HTTP yang dikompresi tidak boleh melebihi 256 MiB untuk permintaan interactions.create sinkron dan streaming. Jika service_tier ditetapkan ke deferred (yang mengharuskan background dan store ditetapkan ke true), permintaan yang tidak dikompresi tidak boleh melebihi 9,75 MiB.
  • Batas URI untuk file Cloud Storage: Permintaan interaksi model Gemini standar mendukung hingga 100 URI Cloud Storage (gs://) yang berbeda per permintaan, termasuk URI yang diteruskan dari giliran percakapan sebelumnya melalui previous_interaction_id. Interaksi agen terkelola, model Gemini Omni, dan model Lyria 3 dikecualikan dari batas 100 URI ini. Untuk izin dan penanganan URI multi-turn, lihat Mengakses file Cloud Storage yang diupload.
  • Batas item dan token multimodal: Model Gemini standar menerima jumlah item per modalitas yang sama dengan generateContent (hingga 3.000 gambar dan PDF yang digabungkan, 1.000 file audio, 10 video, dan hingga 6.500 file multimodal gabungan jika menyertakan file teks biasa), yang dibatasi oleh jendela konteks 1.048.576 token model. File Cloud Storage individual tidak boleh melebihi 2 GiB dikurangi 500 KiB, dan URL HTTP atau HTTPS publik tidak boleh melebihi 15 MiB. Untuk mengirim lebih dari 100 file dalam satu permintaan, teruskan lampiran tambahan secara inline dalam batas payload permintaan atau panggil generateContent.

Alat dan grounding yang didukung

Alat bawaan, penyedia grounding, dan kemampuan penelusuran berikut didukung untuk model Gemini 3 di Interactions API:

  • Grounding dengan Google Penelusuran dan Web Grounding untuk Enterprise: Melakukan grounding respons model dengan informasi web real-time dari Google Penelusuran atau Web Grounding untuk Enterprise.
  • Agent Search dan RAG Engine di Gemini Enterprise Agent Platform: Melakukan grounding respons model terhadap penyimpanan data dan repositori dokumen perusahaan pribadi menggunakan Agent Search dan RAG Engine.
  • Exa Web Search: Melakukan grounding pada respons model dengan hasil penelusuran web dari API penelusuran Exa.
  • Penelusuran Web Paralel: Melakukan grounding respons model dengan data web publik real-time yang disediakan oleh API penelusuran Parallel Web Systems.
  • Konteks URL: Mengambil dan menganalisis konten dari URL web publik yang disertakan dalam perintah Anda.
  • Eksekusi kode: Memungkinkan model membuat dan mengeksekusi kode Python di lingkungan sandbox yang aman.
  • Penggunaan komputer: Memungkinkan alur kerja otomatisasi browser dan antarmuka pengguna.
  • Pemanggilan fungsi: Memungkinkan model terhubung ke alat, API, dan database eksternal dengan menampilkan argumen fungsi terstruktur.

Interactions API mendukung Web Grounding for Enterprise dan Grounding dengan Google Penelusuran. Penggunaan fitur ini oleh Anda juga tunduk pada Persyaratan Khusus Layanan.

Penagihan

Penggunaan Interactions API ditagih berdasarkan konsumsi token.

Penagihan untuk permintaan yang terganggu atau tidak terpenuhi ditangani sebagai berikut:

  • Pembatalan manual: Jika interaksi dibatalkan sebelum selesai (misalnya, dengan mengirimkan permintaan pembatalan), Anda akan dikenai biaya untuk token yang digunakan hingga titik pembatalan.
  • Permintaan gagal: Jika permintaan interaksi gagal karena error sistem internal atau kegagalan backend, Anda tidak akan dikenai biaya untuk permintaan yang gagal.

Keamanan dan kepatuhan

Interactions API mendukung kontrol keamanan, sertifikasi kepatuhan, dan konfigurasi endpoint berikut:

  • Endpoint: Interactions API mendukung endpoint global (locations/global di aiplatform.googleapis.com) serta endpoint multi-region us dan eu (locations/us di aiplatform.us.rep.googleapis.com dan locations/eu di aiplatform.eu.rep.googleapis.com). Endpoint satu region (seperti us-central1 atau europe-west1) tidak didukung.
  • Residensi data: Interactions API mendukung residensi data untuk pemrosesan ML (sedang digunakan) dan data interaksi tersimpan dalam penyimpanan (store=true) saat Anda menggunakan endpoint multi-region us dan eu (locations/us dan locations/eu). Permintaan yang dikirim ke endpoint global tidak memberikan jaminan residensi data.
  • Kunci enkripsi yang dikelola pelanggan (CMEK): Interactions API mendukung CMEK untuk data interaksi yang disimpan melalui profil penayangan (dengan scope ditetapkan ke INTERACTIONS_API) di multi-region us dan eu. Endpoint global tidak didukung untuk CMEK.
  • Kontrol Layanan VPC (VPC-SC): Interactions API mendukung VPC-SC untuk membantu mengamankan perimeter API Anda dan mengurangi risiko pemindahan data yang tidak sah.
  • Transparansi Akses (AXT): Interactions API mendukung log AXT untuk visibilitas hampir real-time saat personel Google mengakses konten interaksi yang disimpan.
  • Sertifikasi keamanan dan kepatuhan: Interactions API memenuhi persyaratan FedRAMP High dalam batas otorisasi FedRAMP High Google Cloud . Interactions API tidak mematuhi persyaratan Department of Defense (DoD) Impact Level 5 (IL5) atau International Traffic in Arms Regulations (ITAR).

SDK yang didukung

Anda dapat mengakses Interactions API menggunakan Google Gen AI SDK terpadu atau panggilan REST langsung:

  • Python: google-genai versi 2.3.0 atau yang lebih baru
  • TypeScript/JavaScript: @google/genai versi 2.3.0 atau yang lebih baru
  • Go: google.golang.org/genai
  • Java: com.google.genai:google-genai

SDK lama (google-cloud-aiplatform, @google-cloud/vertexai, dan google-generativeai) tidak mendukung Interactions API.

Langkah berikutnya