Can one API really both replace simple stateless model calls and host autonomous agents that run code, browse the web, manage files, and retain 55 days of mid-term history? Google says yes, and on 22 June 2026 it moved that claim into production by promoting the Interactions API to general availability and the default surface across Google AI Studio and the Gemini API documentation. The GA release stabilised the schema that began public beta in December 2025 while adding Managed Agents that run in Google-hosted Linux sandboxes, background execution for long-running work, typed execution steps, richer tool outputs including images, and media-generation upgrades. For developers the choice is pragmatic: keep using the legacy GenerateContent API for quick stateless inference, or adopt Interactions when state, tools, files or autonomous workflows matter.

Can a single API really be both the low-friction path for quick inference and the control plane for autonomous, long-running agents?

1. What the Interactions API is and why it matters

The core concept is simple. An Interaction is a chronological, retrievable record of a task or turn composed of typed steps such as User_input, Thought, Function_call, Function_result and Model_output. That stored resource is available via Interactions.get, and a developer continues a task by passing Previous_interaction_id instead of resending full chat transcripts each turn. By default the API stores requests to enable server-side state management; teams may opt out by setting Store=false.

GA arrived on 22 June 2026, after a public beta that started in December 2025. The general availability move did more than mark stability. Google set Interactions as the default surface across Google AI Studio, the Gemini API documentation, and the example SDKs, signalling that future agentic capabilities will appear there. At the same time, the company left the legacy GenerateContent pathway fully supported for simple, low-latency inference.

2. The seven-step path to migration and new builds

First, choose the surface. The Interactions API accepts either a model ID for direct inference or an agent ID for autonomous multi-step work at the same endpoint. If you only need quick stateless calls without tools, memory or long-running execution, the legacy GenerateContent API remains supported and may be the lower-friction path. If your work requires state, tool orchestration, multimodal inputs, file handling or autonomous workflows, Interactions is purpose-built. Worked example: a chat widget that only returns a single text reply can stay on GenerateContent; a research assistant that calls search, opens PDFs and runs code should start on Interactions.

Second, provision and call. Set up the official client and call Interactions.create with either Model="model-id" or Agent="agent-id". To run a hosted agent that executes code in a Google-hosted sandbox, include Environment="remote" or the SDK equivalent. GA supplies a default Antigravity managed agent that provisions a remote Linux sandbox in a single API call. Developers can also define custom managed agents with instructions, skills and data sources. The mental shift for teams used to prompt-in, completion-out is to think for stateful session records and typed steps instead of roles.

Third, handle long-running and asynchronous work. For interactions that may take minutes or involve chained tool calls, set Background=true. The server runs the interaction asynchronously, and clients either poll or stream status and retrieve the finished interaction when complete. Google provides a cancel endpoint to stop in-flight background jobs. The GA documentation and SDK examples show both polling and streaming patterns, and they recommend designing for retries and idempotency around background jobs. Worked example: a data-processing agent that fetches data, runs ETL and produces charts should be created with Background=true so the client can poll a job status and fetch the interaction timeline on completion.

Fourth, use tools, multimodality and functions. The Interactions API supports mixing built-in Google tools such as Google Search and Google Maps alongside developer-provided functions in the same request. Tool results can return images alongside text, simplifying UI rendering for multimodal workflows. Deep Research agent variants in the Interactions family add collaborative planning, native charts and infographics, and multimodal grounding across images, PDFs and audio. Media generation also arrived in GA: new image-generation models and refreshed audio models let agents produce images, music and expressive multi-speaker speech as part of interactions. Worked example: an agent that answers product questions can call a product-catalog function, return a structured function_result and include an image-bearing tool_result for the product photo in the same interaction timeline.

Fifth, manage costs and pick a tier. Google introduced Flex and Priority inference tiers. Flex is a cost-optimised tier that Google advertises as reducing costs in some workloads compared with higher-latency, higher-cost options. The Interactions API’s server-side state management can reduce token consumption for multi-turn conversations by enabling caching across turns. For production deployments, pick the inference tier that matches latency and budget objectives and design fallbacks for throttling and quota errors. Worked example: use Flex for batch research jobs where latency is secondary, and reserve Priority for latency-sensitive user-facing flows.

Mastheads

Sixth, plan operations, security and observability. Production readiness for hosted agents depends on controls beyond model selection. Teams must plan permissions, secret management, logs, human approvals and cost limits for agents that run code and browse external web pages. Google’s guidance emphasises auditability and observability because managed agents can run autonomous tasks that touch external services and internal data. Design patterns include placing strict IAM boundaries around agent capabilities, routing sensitive tool calls to gated functions, and instrumenting interaction steps for replay and forensic inspection. The Interactions API surfaces execution steps that developers can use for debugging UIs and for operational alerts. Worked example: gate any function that writes to production databases behind an IAM-controlled wrapper and record each function_call and function_result entry in the interaction timeline for audit.

Seventh, choose a migration path and coexistence strategy. Google recommends the Interactions API for new projects and for agentic or stateful workflows, while keeping GenerateContent fully supported and receiving mainline Gemini models for the foreseeable future. For existing generateContent integrations Google published a Migration Guide to help with the shift to typed steps and the Interaction resource model. In practice, decide by use case: remain on generateContent for simple low-latency inference; migrate to Interactions when state, tool orchestration or background execution is central; choose Managed Agents when hosted execution and remote sandboxes are required. Worked example: a team running a single-turn summarisation microservice can delay migration; a team building a multi-step document research assistant should plan to move to Interactions and Managed Agents.

3. Model selection, agent variants and developer ergonomics

Model selection now includes a range of flash and pro models across the Gemini 2.5 and Gemini 3 families, with preview-stage model IDs and intended use cases listed in public documentation to guide choice. Google added agent versions optimised for speed or depth and dedicated Deep Research variants for compute-heavy or collaborative tasks. The Interactions API returns observable execution steps that simplify UI rendering and debugging, exposes clearer error fields that point to the exact step that failed, and makes past interactions retrievable for timeline views or partial replay.

For developers familiar with older role-based chats, the new typed execution steps are the ergonomics win. They let UIs render intermediate states such as a model's internal Thought or a function's structured Result, and they help operations teams correlate errors to the offending step rather than guessing from a long free-text transcript. The API also enables structured tool outputs, which reduces client-side parsing and improves reliability.

4. Compliance, retention and practical controls

Because the Interactions API defaults to storing interaction state, teams that handle regulated or sensitive personal data should treat the Store flag as a control and review Google’s paid-tier retention limit. If you need stateless behaviour or shorter retention for compliance reasons, set Store=false and design client-side state management and encryption accordingly. Where logs or stored interactions must be retained for audit, build retention policies that align with organisational requirements and local regulation.

Operational mechanics matter. The API surfaces execution steps for forensic inspection. Instrument those steps and retain only the subset you need for audit. Route sensitive calls to gated functions, centralise secret handling, and place strict IAM boundaries around any agent that can access internal services. For hosted Managed Agents, set explicit cost limits and human-approval gates before allowing autonomous actions that could trigger external spending or data exfiltration.

How to think about costs in practice: use server-side caching to reduce token consumption across multi-turn conversations, select Flex when throughput and cost matter more than raw latency, and design fallbacks for quota errors. Production design still needs retries, idempotency and graceful degradation strategies.

5. Roadmap decisions and coexistence strategy

GA is directional rather than coercive. There's no formal deadline to migrate. Google has stabilised the Interactions API as the place where new agentic capabilities will appear, while continuing to support GenerateContent. That situation creates a migration moment: teams building stateful, multimodal or autonomous products have a clear path forward, while teams running simple inference flows can choose to stay put.

For a migration plan, inventory your use cases by whether they require state, tools, file handling, background execution or hosted code execution. Map the high-impact cases to Interactions first. Keep low-latency single-turn paths on generateContent until you need the extra capabilities. Where you move to Interactions, deploy in stages: prototype with a Managed Agent in a sandbox, add observability, then roll to production with cost limits and IAM controls.

Finally, the developer ergonomics payoff is tangible: cleaner error fields, typed steps for UI rendering, a retrievable interaction timeline for debugging, and the ability to mix built-in Google tools with developer functions in a single request. Those changes aren't cosmetic. They change how teams design for observability, security and user experience.

In short, Interactions GA is both a technical consolidation and an invitation: build more agentic, multimodal and stateful products, but plan for the ops, security and cost work that comes with autonomy.

Related Articles

Remember 22 June 2026: Interactions reached general availability and is now Google’s default home for agentic, stateful capabilities. For builders the deciding question is simple: migrate workflows that need state, tools or background execution to Interactions, and leave single-turn, low-latency inference on GenerateContent.

This article was created with AI assistance.