Migrating to the Interactions API

This guide helps you migrate from the generateContent API to the Interactions API.

The Interactions API is our simplest and best way to build with Gemini models and agents. While generateContent remains fully supported, we recommend the Interactions API for all new development.

Why migrate?

The Interactions API is our simplest and best way to build with Gemini models and agents:

• Server-side history management: Simplified multi-turn flows via previous_interaction_id. The server enables state by default (store=true), but you can opt into stateless behavior by setting store=false.
• Observable execution steps: Typed steps make it easy to debug complex flows and render UI for intermediate events (like thoughts or search widgets).
• Tool use and agentic workflows: Native support for multi-step tool use, orchestration, and complex reasoning flows through typed execution steps.
• Long-running and background tasks: Supports offloading time-intensive operations like Deep Think and Deep Research to background processes using background=true.

Basic input/output

This section shows how to migrate a simple text generation request.

Before (generateContent)

The generateContent API is stateless and returns the response directly. The response structure wraps the output in a list of candidates, each containing content with a list of parts to parse.

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)

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);

# 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":