Como migrar para a API Interactions

Este guia ajuda você a migrar da API generateContent para a API Interactions.

A API Interactions é a maneira mais simples e eficiente de criar com modelos e agentes do Gemini. Embora generateContent ainda tenha suporte total, recomendamos a API Interactions para todos os novos desenvolvimentos.

Por que migrar?

A API Interactions é a maneira mais simples e eficiente de criar com modelos e agentes do Gemini:

  • Gerenciamento do histórico do lado do servidor: fluxos de várias interações simplificados via previous_interaction_id. O servidor ativa o estado por padrão (store=true), mas você pode ativar o comportamento sem estado definindo store=false.
  • Etapas de execução observáveis: as etapas tipadas facilitam a depuração de fluxos complexos e a renderização da interface para eventos intermediários (como ideias ou widgets de pesquisa).
  • Uso de ferramentas e fluxos de trabalho de agentes: suporte nativo para uso de ferramentas em várias etapas, orquestração e fluxos de raciocínio complexos por etapas de execução tipadas.
  • Tarefas longas e em segundo plano: oferece suporte ao descarregamento de operações que exigem muito tempo, como o Deep Think e o Deep Research, para processos em segundo plano usando background=true.

Entrada/saída básica

Esta seção mostra como migrar uma solicitação simples de geração de texto.

Antes (generateContent)

A API generateContent não tem estado e retorna a resposta diretamente. A estrutura da resposta envolve a saída em uma lista de candidates, cada uma contendo content com uma lista de parts para analisar.

Python

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash-lite", contents="Tell me a joke."
)
print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash-lite",
  contents: "Tell me a joke.",
});
console.log(response.text);

REST

# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "contents": [{
        "parts": [{
            "text": "Tell me a joke."
        }]
    }]
}'

# Response
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Why did the chicken cross the road? To get to the other side!"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 12,
    "totalTokenCount": 16
  }
}

A API Interactions retorna um recurso de interação armazenado com uma linha do tempo steps. Embora seja possível inspecionar manualmente a matriz steps para encontrar eventos intermediários, os SDKs de IA generativa do Google oferecem propriedades convenientes diretamente no objeto Interaction retornado para acessar a saída final.

A propriedade de conveniência mais comum é .output_text (String), que extrai e une automaticamente blocos TextContent consecutivos no final da resposta do modelo. Embora isso funcione perfeitamente para respostas simples, não inclui blocos de texto anteriores separados por conteúdo que não é texto, como pensamentos, imagens, áudio ou chamadas de ferramentas. Para respostas multimodais complexas ou intercaladas, itere manualmente sobre steps.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.6-flash", input="Tell me a joke."
)

print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
    model: 'gemini-3.6-flash',
    input: 'Tell me a joke.'
});

console.log(interaction.output_text);

REST

# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta2/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.6-flash",
    "input": "Tell me a joke."
}'

# Response
{
  "id": "int_123",
  "status": "completed",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Tell me a joke."
        }
      ]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}

Conversas com vários turnos

A API Interactions armazena interações por padrão, permitindo o gerenciamento de estado do lado do servidor para conversas multiturno.

Antes (generateContent)

No generateContent, é necessário gerenciar manualmente o histórico de conversas usando a matriz contents ou um auxiliar de chat do lado do cliente.

Python

Usar o auxiliar de chat (recomendado)

from google import genai

client = genai.Client()

chat = client.chats.create(model="gemini-2.5-flash-lite")
response1 = chat.send_message("Hi, my name is Phil.")
print(response1.text)

response2 = chat.send_message("What is my name?")
print(response2.text)

Gerenciar o histórico manualmente

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash-lite",
    contents=[
        types.Content(
            role="user", parts=[types.Part.from_text(text="Hi, my name is Phil.")]
        ),
        types.Content(
            role="model",
            parts=[types.Part.from_text(text="Hi Phil, how can I help you?")],
        ),
        types.Content(
            role="user", parts=[types.Part.from_text(text="What is my name?")]
        ),
    ],
)
print(response.text)

JavaScript

Usar o auxiliar de chat (recomendado)

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

const client = new GoogleGenAI({});

const chat = client.chats.create({ model: 'gemini-2.5-flash-lite' });
let response = await chat.sendMessage({ message: 'Hi, my name is Phil.' });
console.log(response.text);

response = await chat.sendMessage({ message: 'What is my name?' });
console.log(response.text);

Gerenciar o histórico manualmente

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

const client = new GoogleGenAI({});

const response = await client.models.generateContent({
    model: 'gemini-2.5-flash-lite',
    contents: [
        { role: 'user', parts: [{ text: 'Hi, my name is Phil.' }] },
        { role: 'model',