Interfejs Interactions API

Interfejs Interactions API to nowy standard tworzenia aplikacji z użyciem Gemini, zalecany w przypadku wszystkich nowych projektów. Jest on zoptymalizowany pod kątem przepływów pracy z agentami, zarządzania stanem po stronie serwera oraz złożonych rozmów wielomodowych i wieloetapowych. Oryginalny generateContent API jest nadal w pełni obsługiwany.

Dlaczego warto używać interfejsu Interactions API?

  • Zarządzanie historią po stronie serwera: uproszczone przepływy wieloetapowe dzięki parametrowi previous_interaction_id. Serwer domyślnie włącza stan (store=true), ale możesz włączyć zachowanie bezstanowe, ustawiając store=false.
  • Obserwowalne kroki wykonania: kroki z określonym typem ułatwiają debugowanie złożonych przepływów i renderowanie interfejsu użytkownika na potrzeby zdarzeń pośrednich (takich jak przemyślenia czy widżety wyszukiwania).
  • Stworzony z myślą o przepływach pracy agentowych: natywna obsługa wieloetapowego korzystania z narzędzi, koordynacji i złożonych przepływów rozumowania dzięki krokom wykonania z określonym typem.
  • Długotrwałe zadania i zadania w tle: obsługa przenoszenia czasochłonnych operacji, takich jak Deep Think i Deep Research, do procesów w tle za pomocą parametru background=true.
  • Dostęp do nowych modeli i funkcji: w przyszłości nowe modele wykraczające poza podstawową rodzinę modeli, a także nowe funkcje i narzędzia agentów będą dostępne wyłącznie w interfejsie Interactions API.

Użyj interfejsu Interactions API, jeśli rozpoczynasz nowy projekt, tworzysz aplikacje z agentami 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 nie jest jeszcze dostępna w interfejsie Interactions API, np. interfejsu Batch API lub jawnego buforowania.

Rozpocznij

  • Skonfiguruj agenta kodowania: połącz się z Gemini Docs MCP i zainstaluj umiejętność gemini-interactions-api, aby zapewnić asystentowi bezpośredni dostęp do najnowszej dokumentacji dla programistów i sprawdzonych metod. Konfigurowanie agenta kodowania →
  • Migracja z generateContent: jeśli masz już integrację, postępuj zgodnie z instrukcjami w przewodniku po migracji, aby przejść na interfejs Interactions API.
  • Wypróbuj krótkie wprowadzenie: zacznij od minimalnego działającego przykładu w krótkim wprowadzeniu do interfejsu Interactions API.

Przewodniki po funkcjach

W tych przewodnikach znajdziesz informacje o konkretnych funkcjach interfejsu Interactions API. Na tych stronach możesz użyć przełącznika, aby przełączać się między interfejsami generateContent i Interactions API:

Jak działa interfejs Interactions API

Interfejs Interactions API opiera się na podstawowym zasobie: Interaction. Interaction reprezentuje pełny etap rozmowy lub zadania. Działa jako rekord sesji, który zawiera całą historię interakcji jako chronologiczną sekwencję kroków wykonania. Te kroki obejmują przemyślenia modelu, wywołania narzędzi po stronie serwera lub po stronie klienta oraz wyniki (takie jak function_call i function_result) oraz końcowy model_output. Przechowywany zasób (pobierany za pomocą interactions.get) zawiera też kroki user_input w celu uzyskania pełnego kontekstu, chociaż odpowiedź interactions.create zwraca tylko kroki wygenerowane przez model.

Gdy wywołujesz interactions.create, tworzysz nowy zasób Interaction.

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

Chociaż interfejs Interactions API zwraca uporządkowaną oś czasu kroków wykonania (takich jak przemyślenia, zapytania i wywołania funkcji), nie musisz ręcznie przechodzić przez te kroki, aby uzyskać ostateczną odpowiedź modelu.

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

Właściwość wygody 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, automatycznie je łączy. Nie obejmuje wcześniejszych bloków tekstu oddzielonych treściami innymi niż tekst (takimi jak przemyślenia, obrazy, dźwięk czy wywołania 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 dźwięku wygenerowany przez model w bieżącym żądaniu.

W zaawansowanych przypadkach użycia – takich jak renderowanie pośrednich procesów myślowych, sprawdzanie wywołań narzędzi krok po kroku czy debugowanie – nadal możesz ręcznie sprawdzać i przechodzić przez nieprzetworzoną oś czasu interaction.steps.

Zarządzanie stanem po stronie serwera

Aby kontynuować rozmowę, możesz użyć parametru previous_interaction_id w kolejnym wywołaniu, podając id zakończonej interakcji. Serwer używa tego identyfikatora do pobierania historii rozmowy, 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ą parametru previous_interaction_id. Pozostałe parametry są zakresowe 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 je ponownie określić w każdej nowej interakcji. Zarządzanie stanem po stronie serwera jest opcjonalne. Możesz też działać w trybie bezstanowym, wysyłając pełną historię rozmowy w każdym żądaniu.

Przechowywanie danych

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

  • Płatny poziom: 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 ustawić store=false w żądaniu. To ustawienie jest niezależne od zarządzania stanem. Możesz zrezygnować z przechowywania dowolnej interakcji. Pamiętaj jednak, że store=false jest niezgodne z background=true i uniemożliwia używanie previous_interaction_id w kolejnych etapach.

Przechowywane interakcje możesz w każdej chwili usunąć za pomocą metody delete, którą znajdziesz w dokumentacji interfejsu API. Interakcje możesz usuwać tylko wtedy, gdy znasz ich identyfikator.

Po upływie 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 parametru previous_interaction_id do kontynuowania rozmów umożliwia systemowi łatwiejsze korzystanie z niejawnego buforowania historii rozmowy, co zwiększa wydajność i zmniejsza koszty.
  • Łączenie interli: możesz dowolnie łączyć interakcje agenta i modelu w ramach rozmowy. Na przykład do wstępnego zbierania danych możesz użyć wyspecjalizowanego agenta, takiego jak agent Deep Research, a następnie użyć standardowego modelu Gemini do wykonywania zadań uzupełniających, takich jak podsumowywanie lub formatowanie, łącząc te kroki za pomocą parametru 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 Flash-Lite (wersja testowa) Model gemini-3.1-flash-lite-preview
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
Lyria 3 Clip (wersja testowa) Model lyria-3-clip-preview
Lyria 3 Pro (wersja testowa) Model lyria-3-pro-preview
Deep Research (wersja testowa) Agent deep-research-pro-preview-12-2025
Deep Research (wersja testowa) Agent deep-research-preview-04-2026
Deep Research (wersja testowa) Agent deep-research-max-preview-04-2026

Pakiety SDK

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

  • W Pythonie jest to pakiet google-genai w wersji 1.55.0 lub nowszej.
  • W JavaScript jest to pakiet @google/genai w wersji 1.33.0 lub nowszej.

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

Ograniczenia

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

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

Zmiany powodujące niezgodność

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

Obecne zmiany powodujące niezgodność:

  • Schemat kroków: nowa tablica kroków zastępuje tablicę danych wyjściowych, zapewniając uporządkowaną oś czasu każdego etapu interakcji.

Aby dowiedzieć się więcej o najnowszej zmianie powodującej niezgodność i o tym, jak przeprowadzić migrację, zapoznaj się z przewodnikiem po migracji zmian powodujących niezgodność (maj 2026 r.).

Inne potencjalne aktualizacje mogą obejmować zmiany w schematach danych wejściowych i wyjściowych, sygnaturach metod pakietu SDK i strukturach obiektów oraz w zachowaniu określonych funkcji.

W przypadku zadań produkcyjnych nadal używaj standardowego generateContent interfejsu API. Pozostaje on zalecanym sposobem stabilnych wdrożeń, a my będziemy go aktywnie rozwijać i utrzymywać.

Prześlij opinię

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

Co dalej?