Interactions API overview

The Interactions API provides a unified, stateful interface for building generative AI applications and agentic workflows using Gemini models and agents hosted on Gemini Enterprise Agent Platform. While there is feature overlap with the existing generateContent API, the generateContent API remains fully supported.

Why use the Interactions API?

The Interactions API provides several key advantages for building generative AI applications and agentic workflows:

  • Single API for models and agents: One unified endpoint and pattern for calling standard Gemini models as well as specialized agents directly (such as Gemini Deep Research Agent and custom managed agents).
  • New capabilities out of the box: Features like optional server-side conversation state using previous_interaction_id, observable execution steps for debugging and UI rendering, and background execution for long-running tasks using background=true.
  • Where new features launch: Going forward, all new models, multimodal capabilities, tools, and agentic features will be supported on the Interactions API.

How the Interactions API works

The Interactions API centers around the Interaction resource. An Interaction represents a complete turn in a conversation or task and acts as a session record containing a chronological sequence of execution steps:

  • user_input: The input messages, multimodal files, or tool results provided for the turn. Stored interactions retrieved with interactions.get include user_input steps for full context, whereas interactions.create responses return only the steps generated during that turn.
  • thought: Intermediate reasoning summaries generated by the model or agent as it plans its response.
  • Tool call and result steps: Client-side or server-side tool invocations and outputs (such as function_call and function_result).
  • model_output: The final text, structured JSON, or multimodal content produced by the model or agent.

When you call interactions.create, Agent Platform processes your input, executes any configured server-side tools or agent loops, and returns the resulting Interaction resource.

Supported models

The following Gemini models support the Interactions API:

Click to expand supported models

In addition to the models listed above, the Interactions API supports the following specialized multimodal and audio generation models:

  • gemini-omni-flash-preview: High-performance multimodal model for conversational video generation, editing, and cinematic control.
  • lyria-3-clip-preview and lyria-3-pro-preview: Generative music models for high-fidelity audio clips and full-song composition (supported in stateless interactions only with store=false).

Supported agents

You can invoke the following agents through the Interactions API by specifying the agent parameter instead of model:

  • antigravity-preview-05-2026: General-purpose autonomous agent designed for multi-step reasoning, coding, file operations, and tool use.
  • deep-research-preview-04-2026: Gemini Deep Research Agent designed for autonomous, multi-step web research and synthesis.
  • Custom managed agents deployed on Agent Platform.

Features and specifications

The following sections describe the core capabilities, technical specifications, and operational considerations for the Interactions API.

State management

By default, the Interactions API stores requests so you can leverage the server-side state management features by using previous_interaction_id. You can opt into stateless behavior by setting store=false.

Supported tools and grounding

The following built-in tools, grounding providers, and search capabilities are supported for Gemini 3 models in the Interactions API:

  • Grounding with Google Search and Web Grounding for Enterprise: Grounds model responses with real-time web information from Google Search or Web Grounding for Enterprise.
  • Agent Search and RAG Engine on Gemini Enterprise Agent Platform: Grounds model responses against private enterprise datastores and document repositories using Agent Search and RAG Engine.
  • xAI Search: Connects models to real-time social search and knowledge grounding.
  • Parallel Search: Grounds model responses with real-time public web data provided by Parallel Web Systems' search API.
  • Code execution: Lets the model generate and execute Python code in a secure, sandboxed environment.
  • Function calling: Enables models to connect to external tools, APIs, and databases by returning structured function arguments.

The Interactions API supports Web Grounding for Enterprise and Grounding with Google Search. Your use of these features is additionally subject to their Service Specific Terms.

Billing

Interactions API usage is billed based on token consumption.

Billing for interrupted or unfulfilled requests is handled as follows:

  • Manual cancellations: If an interaction is cancelled before completion (for example, by sending a cancellation request), you are charged for the tokens consumed up to the point of cancellation.
  • Failed requests: If an interaction request fails due to an internal system error or backend failure, you are not charged for the failed request.

Security and compliance

During Preview, the Interactions API has the following security, compliance, and data residency considerations:

  • Security & compliance certifications: The Interactions API preview doesn't support FedRAMP or customer-managed encryption keys (CMEK), and isn't compliant with Department of Defense (DoD) Impact Level 5 (IL5) or International Traffic in Arms Regulations (ITAR) requirements.
  • VPC Service Controls: The Interactions API preview supports VPC Service Controls (VPC-SC) to secure your API perimeter.
  • Data residency: The Interactions API preview doesn't support Data residency and doesn't make any commitments for session storage.
  • Endpoints: The Interactions API preview only supports global endpoints (locations/global).

Supported SDKs

You can access the Interactions API using the unified Google Gen AI SDK or direct REST calls:

  • Python: google-genai version 2.3.0 or later
  • TypeScript / JavaScript: @google/genai version 2.3.0 or later
  • Go: google.golang.org/genai
  • Java: com.google.genai:google-genai

Legacy SDKs (google-cloud-aiplatform, @google-cloud/vertexai, and google-generativeai) don't support the Interactions API.

What's next