Interações de streaming

Ao criar uma interação, você pode definir stream: true para transmitir a resposta de forma incremental usando eventos enviados pelo servidor (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]

Tipos de evento

Cada evento enviado pelo servidor inclui um event_type nomeado e dados JSON associados. A API Interactions usa um modelo de transmissão simétrico em que todo o conteúdo (texto, chamadas de ferramenta, raciocínio) flui por um evento baseado em etapas consistente.

Cada stream segue este fluxo de eventos:

  1. interaction.created: a interação é criada e inclui metadados (ID, modelo, status).
  2. Uma série de etapas, cada uma consistindo em:
    • Um evento step.start, que indica o tipo de etapa (por exemplo, model_output, thought, function_call).
    • Um ou mais eventos step.delta com dados incrementais para essa etapa.
    • Um evento step.stop que marca a etapa como concluída.
  3. Um evento interaction.completed com estatísticas usage finais.

Quando você define stream: false, a API retorna um único objeto interaction com uma matriz steps. Cada elemento em steps é a versão totalmente montada de um ciclo step.start → step.delta(s) → step.stop.

interaction.created

Enviado quando a interação é criada. Contém o ID da interação, o modelo e o status inicial.

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

interaction.status_update

Sinaliza uma transição de status no nível da interação. Pode aparecer entre as etapas.

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

step.start

Marca o início de uma nova etapa. Contém o type e o index da etapa. O tipo de etapa determina quais tipos de delta esperar e como a etapa aparece em uma resposta não transmitida:

Tipo de etapa Tipos de delta esperados Descrição
model_output text, image, audio O conteúdo da resposta final do modelo.
thought thought_signature, thought_summary Raciocínio da cadeia de pensamento. summary só está presente quando thinking_summaries está ativado.
function_call arguments_delta Uma solicitação para o cliente executar uma função. Define o status da interação como requires_action.
Ferramentas do lado do servidor Varia de acordo com a ferramenta Ferramentas executadas pela API (por exemplo, google_search_call, google_search_result, code_execution_call, code_execution_result).

Consulte a referência da API Interactions para conferir a lista completa.

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

Para chamadas de função, a etapa inclui o nome da função, o ID e os argumentos vazios {}.

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

step.delta

Dados incrementais para a etapa atual. O objeto delta contém um campo type que determina o formato dele.

Exemplos:

text:token de texto incremental de uma etapa 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:dados de imagem codificados em Base64 de uma etapa model_output:

event: step.delta
data: {"index": 0, "delta": {"type": "image", "mime_type": "image/jpeg", "data": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAoHBwgHBgoICAgLCg..."}, "event_type": "step.delta"}

thought_summary: conteúdo de resumo de raciocínio de uma etapa thought:

event: step.delta
data: {"index": 0, "delta": {"type": "thought_summary", "content": {"type": "text", "text": "I need to find the GCD..."}}, "event_type": "step.delta"}

arguments_delta:string JSON (parcial) para argumentos de chamada de função. Precisa ser acumulado em deltas:

event: step.delta
data: {"index": 0, "delta": {"type": "arguments_delta", "arguments": "{\"location\": \"San Francisco, CA\"}"}, "event_type": "step.delta"}

Estes são alguns dos tipos de delta mais comuns. Para conferir a lista completa de todos os tipos de delta, consulte a referência da API Interactions.

step.stop

Marca o fim de uma etapa. Contém o index da etapa.

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

interaction.completed

Enviado quando a interação é concluída. Contém o objeto de interação final com estatísticas usage. No modo não transmitido, esse é o próprio objeto de resposta de nível superior. Não inclui steps na resposta.

event: interaction.completed
data: {"interaction": {"id": "v1_abc123", "status": "completed", "usage": {"total_input_tokens": 7, "total_output_tokens": 12, "total_tokens": 19}}, "event_type": "interaction.completed"}

error

Enviado quando ocorre um erro durante a interação. Contém um objeto de erro com uma mensagem e um código.

event: error
data: {"error":{"message":"Deadline expired before operation could complete.","code":"gateway_timeout"},"event_type":"error"}

Transmissão com ferramentas

A API Interactions oferece suporte à transmissão com ferramentas do lado do cliente (chamada de função) e do lado do servidor (Pesquisa Google, execução de código etc.) em uma única solicitação. Durante a transmissão, as invocações de ferramentas aparecem como etapas digitadas no fluxo de eventos. Para chamadas de função, o evento step.start entrega o nome da função, e os eventos step.delta transmitem os argumentos como strings JSON (arguments_delta). É necessário acumular esses deltas para receber os argumentos completos. As ferramentas do lado do servidor, como a Pesquisa Google, são executadas automaticamente pela API, produzindo etapas google_search_call e google_search_result.

Transmissão com chamada de função

Para realizar a chamada de função com transmissão, o cliente precisa processar uma conversa multiturno:

  1. Turno 1 (solicitação de função) : chame interactions.create com stream: true e suas tools definidas. A API vai transmitir uma etapa function_call. É necessário acumular as strings JSON de argumento incremental (arguments_delta) de eventos step.delta até que a interação seja concluída com o status requires_action.
  2. Turno 2 (envio do resultado) : chame interactions.create novamente, transmitindo o previous_interaction_id (que corresponde ao ID da primeira interação) e enviando um bloco function_result na matriz input. Isso retoma o stream, permitindo que o modelo gere a resposta final.

Python

from google import genai

client = genai.Client()

weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
            }
        },
        "required": ["location"]
    }
}

# Turn 1: Request function call
stream = client.interactions.create(
    model="gemini-3.5-flash",
    tools=[weather_tool],
    input="What is the weather in Paris right now?",
    stream=True,
)

first_interaction_id = None
func_call_id = None
func_call_name = None
func_args_accumulated = ""

for event in stream:
    if event.event_type == "interaction.created":
        first_interaction_id = event.interaction.id
    elif event.event_type == "step.start":
        step = event.step
        if step.type == "function_call":
            func_call_id = step.id
            func_call_name = step.name
    elif event.event_type == "step.delta":
        if event.delta.type == "arguments_delta":
            func_args_accumulated += event.delta.arguments

# Turn 2: Execute tool and send the result back to resume stream
if func_call_id:
    # Execute weather_tool using accumulated arguments
    dummy_result = {
        "content": [{"type": "text", "text": '{"weather": "Sunny and 22°C"}'}]
    }

    stream2 = client.interactions.create(
        model="gemini-3.5-flash",
        previous_interaction_id=first_interaction_id,
        input=[{
            "type": "function_result",
            "name": func_call_name,
            "call_id": func_call_id,
            "result": dummy_result
        }],
        stream=True,
    )

    for event in stream2:
        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 weatherTool = {
    type: "function",
    name: "get_weather",
    description: "Get the current weather in a given location",
    parameters: {
        type: "object",
        properties: {
            location: {
                type: "string",
                description: "The city and state, e.g. San Francisco, CA"
            }
        },
        required: ["location"]
    }
};

// Turn 1: Request function call
const stream = await client.interactions.create({
    model: "gemini-3.5-flash",
    tools: [weatherTool],
    input: "What is the weather in Paris right now?",
    stream: true,
});

let firstInteractionId = null;
let funcCallId = null;
let funcCallName = null;
let funcArgsAccumulated = "";

for await (const event of stream) {
    if (event.event_type === "interaction.created") {
        firstInteractionId =