Google's Interactions API reaches GA as the new primary Gemini interface

July 12, 2026·AI Newsroom·6 min read·16 sources

google google-deepmind gemini gemini-api interactions-api managed-agents+16

On 2026-06-22, Google published “Interactions API: our primary interface for Gemini models and agents” — the GA post for the Gemini Interactions API, with a stable schema, Managed Agents, background execution, and a “From Roles to Steps” schema migration (Google blog, 2026-06-22). The legacy generateContent API is not going away, but every Google AI Studio surface, the Gemini API docs, and the Google AI docs now default to the Interactions API, and frontier agent features “will increasingly land exclusively on the Interactions API.”

![Google blog post ‘Interactions API: our primary interface for Gemini models and agents’ on 2026-07-12, showing the bylines (Ali Çevik, Group PM, Google DeepMind; Philipp Schmid, Developer Relations Engineer, Google DeepMind) and the Interactions_API_GA_final hero illustration.]({{ ‘/images/articles/google-interactions-api-ga-primary-gemini-interface/hero-blog-desktop.png’ | url }})

What happened

The Interactions API was first launched in public beta in December 2025. On 2026-06-22 it reached general availability with a stable schema and four new capabilities: Managed Agents (with Antigravity as the default), background execution (background=True), Gemini Omni (soon), and a new tool-combination surface that mixes built-in tools (Google Search, Google Maps) with custom functions in one request (GA post, 2026-06-22).

The Google team’s wording on the legacy API: “the legacy generateContent API remains fully supported and will continue to receive new mainline Gemini models for the foreseeable future,” but “frontier capabilities for long-running models and agents will increasingly land exclusively on the Interactions API.” The docs still ship a toggle to switch snippets back to the legacy format. The July 7 Managed Agents expansion post adds background execution for async interactions, remote MCP server integration, custom function calling, and credential refresh.

Why it matters

It’s the default for every new project. The GA post recommends the Interactions API “for all new projects and applications.” The legacy generateContent path is preserved, but the development default has moved.
It’s the surface for frontier agent features. Long-running models, agents, and Gemini Omni all route through the Interactions API. Staying on generateContent means mainline model access without the agent surface.
It’s one endpoint for both models and agents. The same interactions.create call takes a model ID for inference or an agent ID for autonomous tasks. Set background=True for anything long-running.
It collapses tool orchestration into a typed step timeline. The new schema replaces the old role-based contents array with typed step entries (user_input, thought, function_call, model_output) and lets tool results return images alongside text.

What’s new in the API

Capability	What it does	Source
Managed Agents	One call provisions a remote Linux sandbox; agent can reason, execute code, browse the web, and manage files. Antigravity is the default agent.	GA post
Background execution	`background=True` runs the interaction asynchronously; server returns an ID, client can poll, stream, or reconnect later.	GA post; background-execution docs
Tool combination	Mix built-in tools (Google Search, Google Maps) with custom functions in one request; tool results can return images alongside text.	GA post; tool-combination docs
From Roles to Steps	Replaces the role-based `contents` array with typed step entries. The breaking change is documented per-feature.	breaking-changes doc
Flex / Priority tiers	Flex offers 50% cost reduction vs the default tier; Priority is the latency-optimized tier.	GA post; flex-inference docs
55-day retention	Past interactions retrievable for 55 days on the paid tier.	GA post
Field-level error messages	Errors now pinpoint the exact field.	GA post
Deep Research upgrades	Speed vs depth agent variants, collaborative planning, native charts and infographics, multimodal grounding with images / PDFs / audio.	GA post; deep-research docs
Media generation	Image generation with Nano Banana 2 and Google Image Search grounding; Lyria 3 music; multi-speaker TTS speech.	GA post; image-generation docs

Managed Agents in one breath

One call to interactions.create with an agent= ID provisions a remote Linux sandbox where the agent can reason, execute code, browse the web, and manage files. The default agent is Antigravity (antigravity-preview-05-2026). Custom agents can be defined via /v1beta/agents with a display_name, system_instruction, and a tools list. The Jul 7 Managed Agents expansion adds background execution, remote MCP server integration, custom function calling, and credential refresh.

A short code snippet

One Interactions API call, paraphrased from the official docs. Install the SDK first.

pip install google-genai

from google import genai

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

# Stateful conversation, server-side state via previous_interaction_id.
turn_1 = client.interactions.create(
    model="gemini-3.5-flash",
    input="Hi, my name is Amir.",
)
turn_2 = client.interactions.create(
    model="gemini-3.5-flash",
    input="What is my name?",
    previous_interaction_id=turn_1.id,
)
print(turn_2.outputs[-1].text)

# Long-running agent — run in the background, poll for status.
research = client.interactions.create(
    agent="deep-research-pro-preview-12-2025",
    input="Research the history of Google TPUs in 2025 and 2026.",
    background=True,
)

The same call shape is available in the JavaScript SDK via @google/genai 2.11.0 and in the REST API reference.

Migration entry points

Migration guide (migrate-to-interactions) — before/after Python + JavaScript + REST for every generateContent field.
Breaking changes doc (May 2026) — “Core change: outputs to steps”; the typed step values are user_input, thought, function_call, and model_output.
Legacy-format toggle in the Gemini API docs — switch any snippet back to the generateContent shape.
Coding-agents Skill (gemini-interactions-api) — install with npx skills add google-gemini/gemini-skills --skill gemini-interactions-api.
Python SDK — google-genai 2.11.0 on PyPI, Apache-2.0, Python ≥ 3.10.
JavaScript SDK — @google/genai 2.11.0 on npm, Apache-2.0, Node ≥ 20.
Partner integrations — LiteLLM, Eigent, Agno.

Practical implications for builders

Start new projects on the Interactions API. It is the documented default; mainline model coverage stays via generateContent for the foreseeable future.
Plan a migration window for legacy generateContent code. The migration guide maps every field. The breaking-change set is contained in May 2026.
Use background=True for any long-running agent. The server returns an ID and the client can poll, stream, or reconnect.
Evaluate the Flex tier for cost. Google publishes a 50% cost reduction for Flex on non-urgent workloads; benchmark against your prompt shape before committing production traffic.
Adopt the gemini-interactions-api Skill if you are building on Claude Code, Cursor, or any harness that consumes npx skills add packages.

Risks and caveats

Hosting model. The Interactions API is a hosted Google service, not open-source. The first-party SDKs (google-genai, @google/genai) are the canonical client surfaces; third-party SDK coverage is limited to the three partners named in the GA post.
Flex pricing is relative. The 50% cost reduction is a Google-published marketing claim; benchmark against your prompt shape before committing production traffic.
Retention window. Past interactions are retained 55 days on the paid tier only. Confirm against the pricing page before treating it as a durable audit log.
Gemini Omni is “coming soon.” The GA post does not claim it is available.
Partner coverage is curated. The GA post names three integration partners — do not generalize to “the major AI frameworks support it.”
Migration is recommended, not mandatory. The legacy generateContent API remains fully supported.

What to watch

Gemini Omni rollout. The GA post flags Gemini Omni as “soon” but does not commit to a date.
Partner coverage growth. Whether the partner integration list grows beyond LiteLLM, Eigent, and Agno.
The generateContent deprecation timeline. Whether Google publishes a deprecation date, or keeps generateContent as a parallel surface.
Skill adoption. Whether Claude Code, Cursor, Codex, and Aider adopt the gemini-interactions-api Skill — the most concrete “agentic ecosystem” signal in the GA post.
Concrete Flex / Priority pricing. Whether Google publishes per-million-token numbers for Flex and Priority, or only the relative 50% cost-reduction claim.