Interactions API

Jeśli obecnie tworzysz aplikacje za pomocą klasycznego interfejsu generateContent API, nowy Interactions API to doskonała opcja aktualizacji. Jest zalecany w przypadku wszystkich nowych projektów i zoptymalizowany pod kątem procesów agentowych, zarządzania stanem po stronie serwera oraz złożonych rozmów wieloetapowych i wielomodowych. Oryginalny interfejs generateContent API jest nadal w pełni obsługiwany.

Dlaczego warto korzystać z interfejsu Interactions API?

  • Zarządzanie historią po stronie serwera: uproszczone przepływy wieloetapowe za pomocą previous_interaction_id. Serwer domyślnie włącza stan (store=true), ale możesz włączyć zachowanie bezstanowe, ustawiając store=false.
  • Widoczne kroki wykonania: wpisane kroki ułatwiają debugowanie złożonych przepływów i renderowanie interfejsu użytkownika dla zdarzeń pośrednich (takich jak przemyślenia czy widżety wyszukiwania).
  • Stworzone z myślą o przepływach pracy agenta: natywna obsługa wieloetapowego korzystania z narzędzi, orkiestracji i złożonych przepływów rozumowania za pomocą wpisywanych kroków wykonywania.
  • Długotrwałe zadania i zadania w tle: umożliwia przenoszenie czasochłonnych operacji, takich jak Deep Think i Deep Research, do procesów w tle za pomocą background=true.
  • Dostęp do nowych modeli i funkcji: w przyszłości nowe modele wykraczające poza podstawową rodzinę modeli głównych, a także nowe funkcje i narzędzia oparte na agentach będą wprowadzane wyłącznie w interfejsie Interactions API.

Użyj interfejsu API Interactions, jeśli rozpoczynasz nowy projekt, tworzysz aplikacje oparte na agentach lub potrzebujesz zarządzania rozmowami po stronie serwera. Użyj generateContent, jeśli masz już integrację, która spełnia Twoje potrzeby, lub jeśli potrzebujesz funkcji, która jest jeszcze niedostępna w interfejsie Interactions API, np. interfejsu Batch API lub jawnego buforowania.

Rozpocznij

Przewodniki po funkcjach

Z tych przewodników dowiesz się więcej o konkretnych możliwościach interfejsu Interactions API. Na tych stronach możesz przełączać się między interfejsem generateContent a interfejsem Interactions API za pomocą przełącznika:

Jak działa interfejs Interactions API

Interfejs API interakcji opiera się na podstawowym zasobie: Interaction. Symbol Interaction oznacza pełną turę w rozmowie lub zadaniu. Działa on jako zapis sesji, zawierający całą historię interakcji w postaci chronologicznej sekwencji kroków wykonania. Obejmują one przemyślenia modelu, wywołania narzędzi po stronie serwera lub po stronie klienta i wyniki (np. function_call i function_result) oraz ostateczną model_output. Zapisany zasób (pobrany za pomocą interactions.get) zawiera też user_input kroki, które zapewniają pełny kontekst, ale odpowiedź interactions.create zawiera tylko kroki wygenerowane przez model.

Gdy dzwonisz na numer interactions.create, tworzysz nowy zasób Interaction.

Dostęp do danych wyjściowych za pomocą właściwości pakietu SDK

Interfejs API interakcji zwraca uporządkowaną oś czasu z krokami wykonania (takimi jak przemyślenia, zapytania i wywołania funkcji), ale nie musisz ręcznie przechodzić przez te kroki, aby uzyskać ostateczną odpowiedź modelu.

Pakiety SDK generatywnej AI od Google udostępniają wygodne właściwości bezpośrednio w zwróconym obiekcie Interaction, aby uzyskać dostęp do danych wyjściowych dla różnych rodzajów danych:

Wygodna właściwość pakietu SDK Typ zwracanej wartości Opis
interaction.output_text Ciąg znaków Zwraca ostatnie bloki tekstu w odpowiedzi modelu. Jeśli odpowiedź jest podzielona na kilka kolejnych bloków TextContent, są one automatycznie łączone. Nie obejmuje wcześniejszych bloków tekstu oddzielonych treściami innymi niż tekst (np. przemyśleniami, obrazami, dźwiękami lub wywołaniami narzędzi). W przypadku złożonych lub przeplatanych odpowiedzi multimodalnych musisz ręcznie iterować po steps.
interaction.output_image ImageContent lub None Zwraca ostatni blok obrazu wygenerowany przez model w bieżącym żądaniu.
interaction.output_audio AudioContent lub None Zwraca ostatni blok audio wygenerowany przez model w bieżącym żądaniu.

W przypadku zaawansowanych zastosowań, takich jak renderowanie pośrednich procesów myślowych, sprawdzanie wywołań narzędzi krok po kroku czy debugowanie, możesz nadal ręcznie sprawdzać i przeglądać surową oś czasu interaction.steps.

Zarządzanie stanem po stronie serwera

W kolejnym wywołaniu możesz użyć id zakończonej interakcji, korzystając z parametru previous_interaction_id, aby kontynuować rozmowę. Serwer używa tego identyfikatora do pobierania historii rozmów, dzięki czemu nie musisz ponownie wysyłać całej historii czatu.

Parametr previous_interaction_id zachowuje tylko historię rozmowy (dane wejściowe i wyjściowe) za pomocą previous_interaction_id. Pozostałe parametry mają zakres interakcji i mają zastosowanie tylko do konkretnej interakcji, którą obecnie generujesz:

  • tools
  • system_instruction
  • generation_config (w tym thinking_level, temperature itp.)

Oznacza to, że jeśli chcesz, aby te parametry były stosowane, musisz ponownie określić je w każdej nowej interakcji. Zarządzanie stanem po stronie serwera jest opcjonalne. Możesz też działać w trybie bezstanowym, wysyłając w każdym żądaniu pełną historię rozmowy.

Przechowywanie danych

Domyślnie interfejs API przechowuje wszystkie obiekty Interaction (store=true), aby uprościć korzystanie z funkcji zarządzania stanem po stronie serwera (z previous_interaction_id), wykonywania w tle (za pomocą background=true) i obserwacji.

  • Wersja płatna: system przechowuje interakcje przez 55 dni.
  • Poziom bezpłatny: system przechowuje interakcje przez 1 dzień.

Jeśli nie chcesz, aby tak się stało, możesz w swojej prośbie ustawić store=false. Ta kontrola jest niezależna od zarządzania stanem. Możesz zrezygnować z przechowywania danych w przypadku dowolnej interakcji. Pamiętaj jednak, że store=false jest niezgodny z background=true i uniemożliwia używanie previous_interaction_id w kolejnych turach.

Zapisane interakcje możesz w każdej chwili usunąć za pomocą metody usuwania opisanej w dokumentacji interfejsu API. Interakcje możesz usuwać tylko wtedy, gdy znasz ich identyfikator.

Po wygaśnięciu okresu przechowywania Twoje dane zostaną automatycznie usunięte.

System przetwarza obiekty Interaction zgodnie z warunkami.

Sprawdzone metody

  • Współczynnik trafień w pamięci podręcznej: używanie symbolu previous_interaction_id do kontynuowania rozmów ułatwia systemowi korzystanie z niejawnego buforowania historii rozmów, co zwiększa wydajność i obniża koszty.
  • Mieszanie interakcji: możesz mieszać interakcje z agentem i modelem w ramach jednej rozmowy. Możesz na przykład użyć specjalistycznego agenta, takiego jak agent Deep Research, do wstępnego zbierania danych, a następnie użyć standardowego modelu Gemini do wykonywania kolejnych zadań, takich jak podsumowywanie lub formatowanie, łącząc te kroki za pomocą znaku previous_interaction_id.

Obsługiwane modele i agenci

Nazwa modelu Typ Identyfikator modelu
Gemini 3.5 Flash Model gemini-3.5-flash
Gemini 3.1 Flash-Lite Model gemini-3.1-flash-lite
Gemini 3.1 Pro (wersja testowa) Model gemini-3.1-pro-preview
Gemini 3 Flash (wersja testowa) 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
Podgląd klipu z Lyrii 3 Model lyria-3-clip-preview
Lyria 3 Pro (wersja testowa) Model lyria-3-pro-preview
Wersja testowa Deep Research Agent deep-research-pro-preview-12-2025
Wersja testowa Deep Research Agent deep-research-preview-04-2026
Wersja testowa Deep Research Agent deep-research-max-preview-04-2026

Pakiety SDK

Aby uzyskać dostęp do interfejsu API interakcji, możesz użyć najnowszej wersji pakietów SDK Google GenAI.

  • W Pythonie jest to pakiet google-genai od wersji 1.55.0.
  • W przypadku JavaScriptu jest to pakiet @google/genai od wersji 1.33.0.

Więcej informacji o instalowaniu pakietów SDK znajdziesz na stronie Biblioteki.

Ograniczenia

  • Stan wersji beta: interfejs Interactions API jest dostępny w wersji beta lub w wersji zapoznawczej. Funkcje i schematy mogą ulec zmianie.
  • Zdalne MCP: Gemini 3 nie obsługuje zdalnego MCP. Ta funkcja będzie dostępna wkrótce.

Te funkcje są obsługiwane przez interfejs API generateContent, ale nie są jeszcze dostępne w interfejsie API interakcji:

Zmiany powodujące niezgodność

Interfejs Interactions API jest obecnie w fazie wczesnych testów beta. Aktywnie rozwijamy i udoskonalamy możliwości interfejsu API, schematy zasobów i interfejsy SDK na podstawie rzeczywistego wykorzystania i opinii deweloperów. W związku z tym mogą wystąpić zmiany powodujące niezgodność.

Istniejące zmiany powodujące niezgodność:

  • Schemat kroków: nowa tablica kroków zastępuje tablicę wyników, zapewniając uporządkowaną oś czasu każdej interakcji.

Najnowsze zmiany powodujące niezgodność i informacje o sposobie migracji znajdziesz w przewodniku po migracji dotyczącej zmian powodujących niezgodność (maj 2026 r.).

Inne potencjalne aktualizacje mogą obejmować zmiany schematów danych wejściowych i wyjściowych, sygnatur metod pakietu SDK i struktur obiektów oraz konkretnych zachowań funkcji.

W przypadku zadań produkcyjnych należy nadal używać standardowego interfejsu API generateContent. Jest to nadal zalecana ścieżka wdrażania stabilnych wersji, dlatego będziemy ją aktywnie rozwijać i utrzymywać.

Prześlij opinię

Twoja opinia jest kluczowa dla rozwoju interfejsu API do interakcji. Podziel się swoimi przemyśleniami, zgłoś błędy lub poproś o funkcje na naszym forum społeczności deweloperów Google AI.

Co dalej?