Gemini Interactions API Migration Guide: What to Change

Decide whether migration solves a real constraint

The Interactions API became generally available in June 2026 and is Google's recommended interface for new Gemini projects. It unifies calls to models and specialized agents, represents work as an Interaction resource, exposes a chronological timeline of typed steps, and supports optional server-side state and background execution. Those capabilities are especially useful for multi-turn products, tool-using systems, agents, and tasks whose progress must be rendered or debugged.

That recommendation is not the same as a forced migration deadline. Google says the original generateContent API remains fully supported. A stable, single-turn integration may gain little from an immediate rewrite. Migrate when the new state, observability, agent, or background-task model simplifies a real requirement—or when standardizing new development reduces long-term maintenance. Do not turn an API migration into an unbounded platform redesign.

This guide is based on Google's documentation and release materials, not hands-on testing of a particular application. Exact compatibility depends on the SDK version, API version, model, modalities, tools, and error handling in your system.

• Good trigger: multi-turn history is expensive or awkward to resend
• Good trigger: users need visible progress for long-running work
• Good trigger: one application must switch between models and specialized agents
• Weak trigger: a new endpoint exists but the current workflow has no measured problem

Map request and response contracts before changing code

A generateContent response is organized around candidates, content, and parts. An Interactions response is an Interaction resource whose steps can include user input, model output, tool calls, tool results, and other events. Google's SDKs expose output_text as a convenience for simple responses, but the migration guide warns that it only joins consecutive final text blocks. Earlier text separated by thoughts, images, audio, or tool calls may not appear there.

Treat this as a contract migration, not a method rename. Build an inventory of every input type, structured-output schema, function declaration, safety setting, stream event, finish condition, usage field, exception, and parser assumption. For each call site, write the expected application behavior in a fixture that can run against both implementations. A customer-facing answer, an internal audit event, and a tool approval card may all depend on different steps from the same interaction.

Keep the first comparison controlled. Use the same model version, system instruction, prompt, tool definitions, and evaluation inputs on both paths. If the API and model change together, a quality regression cannot be separated from a parsing or orchestration error.

• Translate contents into the Interactions input shape
• Translate structured output controls into response_format
• Replace first-candidate parsing with explicit step handling
• Map usage, status, refusal, incomplete, and error states
• Preserve product-specific moderation and approval behavior outside the model

Choose state, storage, and retention deliberately

Interactions are stored by default. A completed interaction ID can be passed as previous_interaction_id so the service retrieves conversation history instead of requiring the client to resend it. Google's current overview lists default retention of 55 days for paid-tier projects and one day for free-tier projects, with configurable paid-tier windows and programmatic deletion. These are current documentation details that should be rechecked before implementation or procurement.

Convenience changes the data architecture. Decide which data classes may enter stored interactions, who can view logs, how interaction IDs are associated with users, when deletion occurs, and what happens when an ID expires. If storage is inappropriate, set store=false and send the required history with each request. Google documents an important tradeoff: stateless operation cannot later use previous_interaction_id and is incompatible with background execution.

Conversation state also does less than some teams expect. Google says previous_interaction_id preserves inputs and outputs, while tools, system_instruction, and generation_config remain interaction-scoped. Re-send them on every turn that needs them. Otherwise a continuation can look coherent while silently losing a guardrail, tool definition, temperature, or thinking setting.

• Classify prompts, files, tool results, and generated output
• Select store=true or store=false per workflow rather than globally by accident
• Persist interaction IDs only with appropriate access and deletion controls
• Handle expiration and retrieval failure without exposing another user's history
• Reapply current-turn controls even when conversation history is server-managed

Design background and tool workflows as state machines

Background execution lets an application submit long-running work and retrieve it later. That is useful for research and agent tasks, but it moves complexity into product operations. The application needs durable job identity, status transitions, polling or event handling, user-visible progress, timeouts, cancellation rules, retry semantics, and a safe response when a task remains incomplete. A network retry must not accidentally create duplicate consequential work.

Typed steps improve observability but do not automatically make tool use safe. Validate tool arguments outside the model, scope credentials, require approval at consequential boundaries, and record both the proposed and executed action. For managed agents, Google's July update documents token-budget controls and environment hooks that can block, lint, or audit sandbox tool calls. Those features can support defense in depth, but they do not replace the surrounding application's authorization and business rules.

Separate stable core behavior from preview agent behavior in your risk register. Pin versions where possible, monitor release notes, and design a fallback for changed defaults. A managed agent changing its default model may alter cost, latency, or output even when application code does not change.

Prove parity with shadow traffic and a reversible canary

Start with deterministic contract tests: request construction, response parsing, structured schemas, tool events, storage choices, and known failure states. Then run representative task evaluations that score whether the final result is accepted after review. Compare quality, latency, token use, cache behavior, tool accuracy, error rate, and total accepted-task cost. Exact byte-for-byte output equality is usually the wrong goal for a generative system; preserved product behavior and bounded risk are the useful targets.

Shadow production requests only when data handling permits it, and prevent the shadow path from executing real tools or customer-visible actions. Review disagreements, improve parsers and gates, then canary a small cohort with an immediate rollback switch. Increase traffic only after the cohort meets predefined thresholds across normal, adversarial, and failure cases.

Finally, update runbooks and dashboards. Operators should be able to locate an interaction, understand its status and steps, identify the model and configuration used, delete stored data when required, and determine whether a retry is safe. Retire the generateContent path only after the rollback window closes and the new path has demonstrated stable operations—not merely because the code compiled.

• Contract tests for every supported modality and output shape
• Task-level evaluations for quality and accepted outcomes
• Failure injection for timeouts, partial streams, expired state, and tool denial
• A shadow phase with all external writes disabled
• A canary with explicit success thresholds and rollback ownership