Interakcje ze streamingiem

Podczas tworzenia interakcji możesz ustawić stream: true, aby stopniowo przesyłać strumieniowo odpowiedź za pomocą zdarzeń wysyłanych przez serwer (SSE).

Python

from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.5-flash",
    input="Count from 1 to 25.",
    stream=True,
)
for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="", flush=True)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "Count from 1 to 25.",
    stream: true,
});
for await (const event of stream) {
    if (event.event_type === "step.delta") {
        if (event.delta.type === "text") {
            process.stdout.write(event.delta.text);
        }
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Count from 1 to 25.",
    "stream": true
  }'

event: interaction.created
data: {"interaction":{"id":"v1_...","status":"in_progress","object":"interaction","model":"gemini-3.5-flash"},"event_type":"interaction.created"}

event: interaction.status_update
data: {"interaction_id":"v1_...","status":"in_progress","event_type":"interaction.status_update"}

event: step.start
data: {"index":0,"step":{"type":"thought"},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"signature":"...","type":"thought_signature"},"event_type":"step.delta"}

event: step.stop
data: {"index":0,"event_type":"step.stop"}

event: step.start
data: {"index":1,"step":{"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"text":"1, 2, 3, 4, 5, 6, ","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":1,"delta":{"text":"7, 8, 9, 10, 11, 12, 13,","type":"text"},"event_type":"step.delta"}

...

event: step.stop
data: {"index":1,"event_type":"step.stop"}

event: interaction.completed
data: {"interaction":{"id":"v1_...","status":"completed","usage":{"total_tokens":346,"total_input_tokens":11,"input_tokens_by_modality":[{"modality":"text","tokens":11}],"total_cached_tokens":0,"total_output_tokens":90,"total_tool_use_tokens":0,"total_thought_tokens":245},"created":"2026-05-12T18:44:51Z","updated":"2026-05-12T18:44:51Z","service_tier":"standard","object":"interaction","model":"gemini-3.5-flash"},"event_type":"interaction.completed"}

event: done
data: [DONE]

Typy zdarzeń

Każde zdarzenie wysłane przez serwer zawiera nazwane pole event_type i powiązane z nim dane JSON. Interfejs Interactions API korzysta z symetrycznego modelu przesyłania strumieniowego, w którym wszystkie treści – tekst, wywołania narzędzi i proces myślowy – przepływają przez spójne zdarzenie krokowe.

Każda transmisja ma następujący przepływ zdarzeń:

  1. interaction.created: interakcja jest tworzona i zawiera metadane (identyfikator, model, stan).
  2. Seria kroków, z których każdy składa się z:
    • step.start zdarzenie wskazujące typ kroku (np. model_output, thought, function_call).
    • Co najmniej 1 zdarzenie step.delta z danymi przyrostowymi dotyczącymi tego kroku.
    • step.stop zdarzenie oznaczające krok jako ukończony.
  3. Wydarzenie interaction.completed z ostatecznymi statystykami usage.

Gdy ustawisz parametr stream: false, interfejs API zwróci pojedynczy obiekt interaction z tablicą steps. Każdy element w steps to w pełni zmontowana wersja jednego cyklu step.start → step.delta → step.stop.

interaction.created

Wysyłane, gdy interakcja zostanie utworzona po raz pierwszy. Zawiera identyfikator interakcji, model i stan początkowy.

event: interaction.created
data: {"interaction": {"id": "...", "model": "gemini-3.5-flash", "status": "in_progress", "object": "interaction"}, "event_type": "interaction.created"}

interaction.status_update

Sygnalizuje przejście stanu na poziomie interakcji. Może się pojawiać między krokami.

event: interaction.status_update
data: {"interaction_id": "...", "status": "in_progress", "event_type": "interaction.status_update"}

step.start

Oznacza początek nowego kroku. Zawiera kroki type i index. Typ kroku określa, jakich typów delty należy oczekiwać i jak krok będzie wyglądać w odpowiedzi bez przesyłania strumieniowego:

Typ kroku Oczekiwane typy zmian Opis
model_output text, image, audio Treść ostatecznej odpowiedzi modelu.
thought thought_signature, thought_summary Rozumowanie w formie łańcucha myśli. Wartość summary występuje tylko wtedy, gdy włączona jest wartość thinking_summaries.
function_call arguments_delta Prośba o wykonanie funkcji przez klienta. Ustawia stan interakcji na requires_action.
Narzędzia po stronie serwera Zależy od narzędzia Narzędzia wykonywane przez interfejs API (np. google_search_call, google_search_result, code_execution_call, code_execution_result).

Pełną listę znajdziesz w dokumentacji interfejsu API interakcji.

event: step.start
data: {"index": 0, "step": {"type": "model_output"}, "event_type": "step.start"}

W przypadku wywołań funkcji krok zawiera nazwę funkcji, identyfikator i puste argumenty {}.

event: step.start
data: {"index": 0, "step": {"type": "function_call", "id":"un6k8t18", "name": "get_weather", "arguments":{}}, "event_type": "step.start"}

step.delta

Dane przyrostowe bieżącego kroku. Obiekt delta zawiera pole type, które określa jego kształt.

Przykłady:

text: przyrostowy token tekstowy z kroku model_output:

event: step.delta
data: {"index": 0, "delta": {"type": "text", "text": "Hello, my name is Phil"}, "event_type": "step.delta"}

event: step.delta
data: {"index": 0, "delta": {"type": "text", "text": ", and I live in Germany." }, "event_type": "step.delta"}

image: dane obrazu zakodowane w formacie Base64 z kroku model_output:

event: step.delta
data: {"index": 0, "delta"