Ringkasan Interactions API

Interactions API menyediakan antarmuka terpadu dan stateful untuk membangun aplikasi AI generatif dan alur kerja agentic menggunakan model dan agen Gemini yang dihosting di Gemini Enterprise Agent Platform. Meskipun ada tumpang-tindih fitur dengan API generateContent yang ada, API generateContent tetap didukung sepenuhnya.

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 terkelola kustom).
  • Kemampuan baru yang siap digunakan: 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.
  • Tempat peluncuran fitur baru: Ke depannya, semua model baru, kemampuan multimodal, alat, dan fitur agentik akan didukung di Interactions API.

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 eksekusi kronologis steps:

  • user_input: Pesan input, file multimodal, atau hasil alat yang diberikan 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-langkah panggilan dan hasil alat: 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 atau agent loop sisi server yang dikonfigurasi, dan menampilkan resource Interaction yang dihasilkan.

Model yang didukung

Model Gemini berikut mendukung Interactions API:

Klik untuk meluaskan model yang didukung

Selain model yang tercantum di atas, Interactions API mendukung model multimodal dan pembuatan audio khusus berikut:

  • gemini-omni-flash-preview: Model multimodal berperforma tinggi untuk pembuatan, pengeditan, dan kontrol sinematik video percakapan.
  • 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 tanpa status 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, pengodean, operasi file, dan penggunaan alat.
  • deep-research-preview-04-2026: Agen Deep Research Gemini dirancang untuk penelitian dan sintesis web multi-langkah yang bersifat 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 permintaan sehingga Anda dapat memanfaatkan fitur pengelolaan status sisi server dengan menggunakan previous_interaction_id. Anda dapat memilih untuk menggunakan perilaku tanpa status dengan menyetel store=false.

Alat dan perujukan yang didukung

Alat bawaan, penyedia perujukan, 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 repositori dokumen dan penyimpanan data perusahaan pribadi menggunakan Agent Search dan RAG Engine.
  • xAI Search: Menghubungkan model ke penelusuran sosial real-time dan perujukan pengetahuan.
  • Penelusuran Paralel: Melakukan grounding respons model dengan data web publik real-time yang disediakan oleh API penelusuran Parallel Web Systems.
  • Eksekusi kode: Memungkinkan model membuat dan mengeksekusi kode Python di lingkungan sandbox yang aman.
  • Panggilan fungsi: Memungkinkan model terhubung ke alat, API, dan database eksternal dengan menampilkan argumen fungsi terstruktur.

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

Penagihan

Penggunaan Interactions API ditagih berdasarkan penggunaan token.

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

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

Keamanan dan kepatuhan

Selama Pratinjau, Interactions API memiliki pertimbangan keamanan, kepatuhan, dan residensi data berikut:

  • Sertifikasi keamanan & kepatuhan: Pratinjau Interactions API tidak mendukung FedRAMP atau kunci enkripsi yang dikelola pelanggan (CMEK), dan tidak mematuhi persyaratan Impact Level 5 (IL5) Departemen Pertahanan (DoD) atau International Traffic in Arms Regulations (ITAR).
  • Kontrol Layanan VPC: Pratinjau Interactions API mendukung Kontrol Layanan VPC (VPC-SC) untuk mengamankan perimeter API Anda.
  • Residensi data: Pratinjau Interactions API tidak mendukung Residensi data dan tidak membuat komitmen apa pun untuk penyimpanan sesi.
  • Endpoint: Pratinjau Interactions API hanya mendukung endpoint global (locations/global).

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
  • Buka: 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