/gemini-interactions-api

name: gemini-interactions-api
metadata:
  version: "2.0.2"
  category: AiAndMachineLearning
description: Guides the usage of Gemini Interactions API on Gemini Enterprise Agent Platform. Use when the user wants to use the stateful, server-managed Interactions API for multi-turn conversations, background execution, streaming, structured output, and function calling on the Agent Platform.

Gemini Interactions API Skill

This skill provides instructions for authenticating, connecting to, and utilizing the stateful, server-managed **Gemini Interactions API** on Gemini Enterprise Agent Platform.

The Interactions API is the modern, recommended way to execute Generative AI agent conversations, background research tasks, multi-turn chats, and structured, multi-step workflows.

> [!IMPORTANT] **CRITICAL: Unified SDK, Latest Models & Model/Agent Targeting** * > **Unified SDK**: Use the Google Gen AI SDK (**`google-genai >= 2.3.0`** for > Python, **`@google/genai >= 2.3.0`** for JS/TS). SDK versions `>= 2.0.0` are > the minimum floor at which the steps schema activates, but `>= 2.3.0` is the > supported/recommended floor. Legacy SDKs like `google-cloud-aiplatform`, > `@google-cloud/vertexai`, `google-generativeai`, and `@google/generative-ai` > are strictly unsupported for Interactions. * *Mandatory Instruction*: When > explaining client initialization or writing import code, you **must** > explicitly state/warn the user that legacy packages like > `google-cloud-aiplatform` or `google-generativeai` are strictly unsupported > for interactions. * **Latest Models Only**: Use `gemini-3.8-flash` (fast, > balanced, multimodal — the recommended default), `gemini-3.1-pro-preview` > (complex reasoning, coding, research), or `gemini-3.5-flash-lite` > (cost-efficient, high-frequency lightweight tasks). Refer to the > [latest model versions](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/migrate) > to check for new updates. Legacy models (`gemini-3-flash-preview`, > `gemini-2.5-*`, `gemini-2.0-*`, `gemini-1.5-*`) are deprecated and do not > support interactions. * *Mandatory Instruction*: In any interaction response, > you **must** warn the user that legacy models like `gemini-2.5-*`, > `gemini-2.0-*`, or `gemini-1.5-*` are deprecated and unsupported for the > Interactions API. If a user asks for a deprecated model, use > `gemini-3.8-flash` instead and note the substitution. * **Model & Agent > Targeting**: Target foundation models directly using > `model="gemini-3.8-flash"`, or target autonomous managed/custom agents > (`antigravity-preview-09-2026`, `deep-research-preview-04-2026`, or custom > agents provisioned via `client.agents.create()`) using `agent="<AGENT_ID>"`. > Managed agents (`antigravity-preview-09-2026` and custom agents) require > `environment="remote"` to provision a sandbox. * **Turn-Scoped Parameters**: > Parameters like `tools`, `system_instruction`, and `generation_config` are > turn-scoped. They **MUST** be passed with each interaction request.

Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST read [Usage Attribution](references/attribution.md). For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gemini-interactions-api)"` and append `agent-skills/1.0 (skill:gemini-interactions-api)` to `User-Agent` headers.

1. Authentication

Before running any code, ensure you are authenticated with Application Default Credentials (ADC) and have the necessary API enabled.

1. **Login**:

    gcloud auth application-default login

2. **Enable API** (if not already enabled):

    gcloud services enable aiplatform.googleapis.com

---

2. Client Initialization

You can initialize the client using environment variables (recommended) or by passing explicit configuration parameters.

Option A: Environment Variables (Recommended)

Configure environment variables to let the SDK automatically resolve settings:

export GOOGLE_GENAI_USE_ENTERPRISE=true
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="global"

Python

from google import genai

# The SDK automatically picks up the environment variables
client = genai.Client()

TypeScript/JavaScript

import { GoogleGenAI } from "@google/genai";

// The SDK automatically picks up the environment variables
const ai = new GoogleGenAI();

Option B: Explicit Inline Parameters

Alternatively, pass configuration values directly inside your code:

Python

from google import genai
import google.auth

_, project_id = google.auth.default()
client = genai.Client(enterprise=True, project=project_id, location="global")

TypeScript/JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "your-project-id",
    location: "global"
});

Option C: Express Mode (API Key)

Recommended for lightweight scripts or environments using an API key:

Python

from google import genai

client = genai.Client(enterprise=True, api_key="YOUR_API_KEY")

TypeScript/JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    apiKey: "YOUR_API_KEY"
});

---

3. Core Interactions API Usage

Quick Start (Single-Turn)

Submit a single prompt and read the final text response. Under the modern schema, output content is retrieved from the `steps` list.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence."
)
# Use the output_text convenience accessor (combined text from the trailing model_output steps)
print(interaction.output_text)

TypeScrip