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. The generateContent API remains fully supported alongside the Interactions API.

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.

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. For code samples across Python, TypeScript/JavaScript, and REST, see the Interactions API developer guide.

Supported models

The following Gemini models support the Interactions API:

Click to expand supported models

In addition to the Gemini models in the preceding list, the Interactions API supports the following generative music models: * 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 interactions on the server (store=true) for 7 days so you can chain multi-turn conversations with previous_interaction_id and run asynchronous background tasks (background=true). To opt into stateless execution and support Zero Data Retention (ZDR) workflows, set store=false. For details, see Manage session storage and conversation state.

Request and multimodal limits

The Interactions API enforces the following request payload and multimodal input limits:

  • Request payload limits: The compressed HTTP request payload can't exceed 256 MiB for synchronous and streaming interactions.create requests. When service_tier is set to deferred (which requires both background and store to be true), the uncompressed request can't exceed 9.75 MiB.
  • URI limit for Cloud Storage files: Standard Gemini model interaction requests support up to 100 distinct Cloud Storage (gs://) URIs per request, including URIs carried forward from earlier conversation turns through previous_interaction_id. Managed agent interactions, Gemini Omni models, and Lyria 3 models are excluded from this 100-URI limit. For permissions and multi-turn URI handling, see Access uploaded Cloud Storage files.
  • Multimodal item and token limits: Standard Gemini models accept the same per-modality item counts as generateContent (up to 3,000 images and PDFs combined, 1,000 audio files, 10 videos, and up to 6,500 combined multimodal files when including plain-text files), bounded by the model's 1,048,576-token context window. Individual Cloud Storage files can't exceed 2 GiB minus 500 KiB, and public HTTP or HTTPS URLs can't exceed 15 MiB. To send more than 100 files in a single request, pass additional attachments inline within the request payload limit or call generateContent.

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.
  • Exa Web Search: Grounds model responses with web search results from Exa's search API.
  • Parallel Web Search: Grounds model responses with real-time public web data provided by Parallel Web Systems' search API.
  • URL context: Retrieves and analyzes content from public web URLs included in your prompt.
  • Code execution: Lets the model generate and execute Python code in a secure, sandboxed environment.
  • Computer use: Enables browser and user-interface automation workflows.
  • 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

The Interactions API supports the following security controls, compliance certifications, and endpoint configurations:

  • Endpoints: The Interactions API supports the global endpoint (locations/global on aiplatform.googleapis.com) and the us and eu multi-region endpoints (locations/us on aiplatform.us.rep.googleapis.com and locations/eu on aiplatform.eu.rep.googleapis.com). Single-region endpoints (such as us-central1 or europe-west1) aren't supported.
  • Data residency: The Interactions API supports data residency for both ML processing (in-use) and stored interaction data at rest (store=true) when you use the us and eu multi-region endpoints (locations/us and locations/eu). Requests sent to the global endpoint don't provide data residency guarantees.
  • Customer-managed encryption keys (CMEK): The Interactions API supports CMEK for stored interaction data through serving profiles (with scope set to INTERACTIONS_API) in the us and eu multi-regions. The global endpoint isn't supported for CMEK.
  • VPC Service Controls (VPC-SC): The Interactions API supports VPC-SC to help secure your API perimeter and mitigate data exfiltration risks.
  • Access Transparency (AXT): The Interactions API supports AXT logs for near-real-time visibility when Google personnel access stored interaction content.
  • Security and compliance certifications: The Interactions API meets FedRAMP High requirements within the Google Cloud FedRAMP High authorization boundary. The Interactions API isn't compliant with Department of Defense (DoD) Impact Level 5 (IL5) or International Traffic in Arms Regulations (ITAR) requirements.

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