Answer first: migrate new stateful, tool-using, or long-running Gemini work to the Interactions API, but do not treat generateContent as shut down. Google says the legacy API remains fully supported. The safe path is one representative workflow at a time, with explicit state, output parsing, tool, privacy, and rollback tests.
What changed at general availability
Google describes the Interactions API as its primary interface for Gemini models and agents. The GA surface adds a stable schema and represents work as an interaction with typed execution steps.
| Existing assumption | Interactions API decision |
|---|---|
| A request returns candidates and content parts | An interaction returns status and a typed steps timeline |
| Conversation history is rebuilt client-side | Continue from a previous interaction ID or explicitly remain stateless |
| Final text is the only useful output | Inspect steps when tools, thoughts, images, audio, or other content interrupt text |
| The HTTP request stays open | Use background execution for suitable long-running work |
| Tools are attached to a model call | Treat built-in tools, custom functions, and managed agents as separate execution boundaries |
The migration is therefore more than renaming one SDK method.
Decide whether to migrate now
Prioritize a workflow when at least one is true:
- The application manually resends long conversation history.
- Users need progress, tool-call, or intermediate-step visibility.
- A request can outlive a normal synchronous connection.
- The product needs built-in and custom tools in one observable flow.
- The next feature depends on a managed agent.
Keep a stable generateContent path in place when it is simple, well tested, and gains no clear value from server-side state or typed steps. Google recommends the new API for new development; it does not require a rushed rewrite of every working call.
Migrate one vertical slice
Choose one bounded use case and capture its current contract:
- Input types and validation.
- Model selection and generation settings.
- Tool definitions and permission boundaries.
- Output schema and error behavior.
- Latency, retries, and cancellation.
- Logging, storage, privacy, and deletion requirements.
Then replace the call and adapt the consumer. Simple text can use the SDK’s output convenience field. A workflow with tools or mixed media should read the relevant typed steps rather than assuming every useful result is one final text block.
Make state an explicit product decision
The Interactions API stores state by default and can continue a flow from previous_interaction_id. That reduces client-side history handling, but it also changes the data lifecycle.
Before enabling it in production, decide:
- Which interaction IDs belong to which user and tenant.
- Whether the workflow needs state at all.
- Who may retrieve a stored interaction.
- Which prompts, files, and tool results are permitted.
- How current retention and deletion behavior fit the system’s policy.
Use stateless behavior when the application must own the complete history or when server-side storage is not appropriate. Confirm the current official retention terms instead of copying a dated number into architecture.
Preserve observable behavior
Run the old and new path against a fixed acceptance set:
| Check | Evidence to record |
|---|---|
| Content | Required facts and fields are present |
| Structure | JSON, multimodal, and tool outputs parse correctly |
| State | Follow-up turns use only the intended context |
| Tools | Calls stay within the approved tool and argument policy |
| Failure | Timeouts, refusals, retries, and partial steps are handled |
| Operations | Logs expose status without leaking sensitive content |
| Cost | Token, tool, storage, and retry behavior is understood |
Do not compare only one successful text response. A migration passes when downstream behavior remains correct under success, failure, and cancellation.
Roll out with a reversible boundary
Keep the API choice behind one adapter or feature flag. Start with internal traffic, then a small production cohort. Preserve the prior implementation until the new path meets the agreed error, latency, correctness, and privacy gates.
For current Gemini model and data-control questions, use the Gemini FAQ. For long-running managed execution, continue with the Gemini Managed Agents guide. If the decision is model fit rather than API shape, review the Gemini 3.1 model route.
FAQ
Is generateContent deprecated?
No. Google says generateContent remains fully supported. The Interactions API is the recommended interface for new development, especially stateful, tool-using, or long-running work.
What is the biggest migration change?
Treat the response as an interaction with typed steps and optional server-side state, not only as a candidate containing parts. Update parsing, persistence, observability, and tests together.
Does the Interactions API store state by default?
Google’s migration guide says server-side state is enabled by default. Review the current storage and retention terms, use store=false when stateless behavior is required, and avoid sending data the application is not authorized to process.
Should every Gemini request migrate at once?
No. Start with one representative path, keep the old implementation behind a rollback boundary, compare outputs and operational behavior, then expand only after the acceptance checks pass.
Official sources
Sources last checked July 29, 2026: