Building with the Gemini Interactions API: A Developer's Guide to the New Standard

Introduction

If you’ve been building with the Gemini API for a while, you’re probably familiar with the generateContent endpoint. It’s been the workhorse of text generation, multimodal understanding, and tool calling for years. But the way we build with AI is changing, and the API needs to change with it.

As of June 2026, the Interactions API is Generally Available and is now the recommended way to build with Gemini models and agents. It is a single, unified interface designed for every use case — from a simple one-turn text request to complex agentic workflows that chain multiple tools and models together. And critically, it’s where all new models, multimodal capabilities, and agentic features will launch from now on.

In this article, we’ll dive into why the Interactions API matters, how it works under the hood, how to use its state management and background execution features, and how to migrate your existing generateContent integrations.

Why use the Interactions API?

The old API had a fundamental problem: as AI applications grew more sophisticated, developers needed more than a “give the model a prompt, get a response” loop. They needed conversation state, tool orchestration, agent delegation, and observability — and they needed it all through one consistent interface.

The Interactions API solves this with a few key design decisions:

• Universal interface for all applications: Whether you’re doing single-turn text generation, multimodal understanding, structured outputs, tool orchestration, or full agentic workflows, you use the same endpoint and the same mental model.
• Single API for models and agents: One unified pattern for calling standard Gemini models and specialized agents — like Deep Research and custom managed agents — directly. No more bolting agents onto a text-generation API that wasn’t designed for them.
• New capabilities out of the box: Optional server-side conversation state via previous_interaction_id, observable execution steps for debugging and UI rendering, and background execution for long-running tasks using background=true.
• Lower cost with higher cache hit rates: In multi-turn conversations, server-side state management enables more efficient context caching across turns, which reduces token costs significantly.
• The future of the platform: Going forward, every new model, multimodal capability, tool, and agentic feature will launch on the Interactions API.

The most important shift here is architectural. Instead of forcing you to manage conversation history client-side and resend it on every turn, the Interactions API lets the server hold the state. For long-running agentic applications, that’s a game changer.

How the Interactions API works

At the center of the API is a core resource called an Interaction. Think of it as a complete turn in a conversation or task — a session record that contains the entire history of that turn as a chronological sequence of execution steps.

These steps are the building blocks of everything the model does:

• Model thoughts (reasoning)
• Server-side or client-side tool calls and results (like function_call and function_result)
• The final model_output

When you call interactions.create, you create a new Interaction resource. If you retrieve a stored interaction via interactions.get, you’ll also see the user_input steps for full context, though the create response only returns the model-generated steps.

Let’s look at a basic example in Python using the google-genai SDK (v2.3.0+):

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

response = client.interactions.create(
    model="gemini-3.6-flash",
    contents="Explain the Interactions API in one paragraph.",
)

print(response)

And the equivalent in JavaScript with @google/genai:

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

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

const response = await ai.interactions.create({
  model: "gemini-3.6-flash",
  contents: "Explain the Interactions API in one paragraph.",
});

console.log(response);

Simple enough. But the real power comes from what happens next.

Server-side state management

In a traditional chat application, every request resends the entire conversation history to the model. This is wasteful — the same tokens get re-processed turn after turn, driving up both latency and cost.

The Interactions API flips this model. You can use the id of a completed interaction in a subsequent call via the previous_interaction_id parameter. The server retrieves the conversation history for you, so you never have to resend it.

# First turn
first = client.interactions.create(
    model="gemini-3.6-flash",
    contents="My name is Ada and I'm researching the Interactions API.",
)
interaction_id = first.id

# Second turn - the server remembers the conversation
second = client.interactions.create(
    model="gemini-3.6-flash",
    previous_interaction_id=interaction_id,
    contents="What is my name?",
)

print(second.interaction.model_output)

There’s an important nuance here: previous_interaction_id preserves only the conversation history (inputs and outputs). Everything else is interaction-scoped, meaning it applies only to the specific interaction you’re generating:

• tools
• system_instruction
• generation_config (including thinking_level, temperature, etc.)

In practice, this means you must re-specify these parameters on each new interaction if you want them applied. It’s a small mental shift from the old API, but it keeps the contract explicit — every interaction is self-contained, with only the conversation state flowing through the ID.

Data storage and retention

To make server-side state work, the API stores Interaction objects by default (store=true). This powers previous_interaction_id, background execution, and observability. But storage isn’t forever:

• Paid tier: Interactions are retained for 55 days.
• Free tier: Interactions are retained for 1 day.

You can opt out per-request by setting store=false. This is useful when you’re doing one-off, stateless requests and don’t want data persisted. Note, however, that store=false is incompatible with background execution and prevents using previous_interaction_id for subsequent turns.

For Paid Tier projects, you can configure the retention window in AI Studio to auto-mark logs for deletion after 7, 14, 28, or 55 days. And you can always delete stored interactions programmatically using the delete method, which takes the interaction ID.

Background execution for long-running tasks

Some tasks — deep research, large document analysis, multi-step agent workflows — take a while. Blocking on them synchronously ties up your request pipeline. The Interactions API supports running these in the background using background=true:

task = client.interactions.create(
    model="deep-research-preview-04-2026",
    contents="Research the competitive landscape of open-source vector databases.",
    background=True,
)

# Poll or retrieve the result later

Long-running and agentic tasks become first-class citizens rather than awkward workarounds. This is a big deal for building production systems where you need to offload heavy work and pick up results when ready.

Best practices

Over time, a few patterns stand out when working with the Interactions API:

• Maximize cache hit rates: Implicit caching is supported in both stateful and stateless modes, but using previous_interaction_id to continue conversations lets the system more easily reuse the implicit cache for conversation history. That translates directly into better performance and lower costs.
• Mix agents and models freely: You can mix Agent and Model interactions within a single conversation. For example, use the Deep Research agent for initial data collection, then hand the results to a standard Gemini model for summarization or reformatting — all linked by previous_interaction_id. Each step plays to the strength of the model or agent that’s best at it.

This mixing pattern is arguably the most exciting part of the API. It removes the friction of coordinating multiple providers or bespoke agent frameworks; it’s all just interactions chained together.

Supported models and agents

The Interactions API supports the full breadth of the Gemini ecosystem — text, multimodal, image, audio, video, TTS, and Gemma open models — plus specialized agents like Deep Research:

Model Name	Type	Model ID
Gemini 3.6 Flash	Model	gemini-3.6-flash
Gemini 3.5 Flash	Model	gemini-3.5-flash
Gemini 3.1 Pro Preview	Model	gemini-3.1-pro-preview
Gemini 3.5 Flash-Lite	Model	gemini-3.5-flash-lite
Gemini 3.1 Flash-Lite	Model	gemini-3.1-flash-lite
Gemini 3 Flash Preview	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
Gemini 3 Pro Image	Model	gemini-3-pro-image
Gemini 3.1 Flash Image	Model	gemini-3.1-flash-image
Gemini 3.1 Flash TTS Preview	Model	gemini-3.1-flash-tts-preview
Gemma 4 31B IT	Model	gemma-4-31b-it
Gemma 4 26B MoE IT	Model	gemma-4-26b-a4b-it
Lyria 3 Clip Preview	Model	lyria-3-clip-preview
Lyria 3 Pro Preview	Model	lyria-3-pro-preview
Deep Research Preview	Agent	deep-research-preview-04-2026
Deep Research Preview	Agent	deep-research-max-preview-04-2026
Antigravity Preview	Agent	antigravity-preview-05-2026

SDKs

You can access the Interactions API with the latest Google GenAI SDKs:

• Python: the google-genai package, from version 2.3.0 onwards.
• JavaScript: the @google/genai package, from version 2.3.0 onwards.

Check the Libraries page for installation instructions.

Migrating from generateContent

If you have an existing integration built on generateContent, you don’t need to panic — the legacy API remains fully supported. But if you want to move to the new standard, Google provides a dedicated Migration guide. For most apps the migration is mechanical: swap the endpoint, adapt the response shape, and adjust the conversation handling to leverage previous_interaction_id where it makes sense.

Current limitations

The Interactions API is powerful, but it’s not yet a drop-in replacement for every feature of generateContent. Two notable restrictions apply to the API generally:

• Remote MCP: Gemini 3 does not support remote MCP yet — this is coming soon.
• Multi-turn model compatibility: When mixing different models in a conversation (stateful or stateless), subsequent models must support the output modalities of previous models as input. For example, if you generate an image with gemini-3.1-flash-image, you can’t continue that conversation with a text-only model or a music-generation model like Lyria.

Additionally, these generateContent features are not yet available in the Interactions API:

• Video metadata: The video_metadata field (clipping intervals, custom frame rates) for video understanding.
• Batch API
• Automatic function calling (Python)
• Explicit caching: Server-side implicit caching is available via previous_interaction_id, but explicit, manual caching is not.
• Custom safety settings

Keep these in mind when evaluating whether to migrate. For most new projects, the trade-off is clearly worth it.

Conclusion

The Interactions API represents a fundamental shift in how developers are meant to build with Gemini. It’s not just a renamed generateContent — it’s a unified interface designed around conversations, state, and agents rather than one-shot prompt/response calls.

The headline benefits are clear:

1. One API for everything — models, agents, multimodal, tools, structured output.
2. Server-side state — cheaper multi-turn conversations via previous_interaction_id and implicit caching.
3. Background execution — long-running agentic tasks without blocking.
4. Observable execution steps — better debugging and UI rendering.
5. It’s the future — all new capabilities launch here.

If you’re starting a new project, build directly on the Interactions API. If you’re on generateContent, the migration guide is well-trodden. Either way, this is the interface you’ll be building with for years to come.

What’s next

• Try the Interactions API quickstart notebook.
• Learn more about the Gemini Deep Research Agent.
• Read the Migration guide to move existing integrations.