/gemini-interactions-api

name: gemini-interactions-api
metadata:
  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 & GEAP 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`, and `google-generativeai` 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.5-flash` (fast, balanced, multimodal — the > recommended default), `gemini-3.1-pro-preview` (complex reasoning, coding, > research), or `gemini-3.1-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. * **GEAP requires a provisioned agent (no direct base-model > calls yet)**: On Gemini Enterprise Agent Platform (GEAP), direct/base-model > calls (`model="..."`) via the Interactions API are **not supported yet**. You > **must** target a provisioned agent or endpoint with the `agent="<AGENT_ID>"` > parameter instead of `model="..."`. The code examples in this skill use > `agent=...` for this reason. (This is the primary difference from the > [ai.google.dev](https://ai.google.dev/gemini-api/docs/interactions) > documentation for Interactions, which uses `model=...` — while `model=...` is > valid for other Gemini API contexts, it is **not supported on the Agent > Platform**.) Provision an agent per the > [Agent Platform docs](https://docs.cloud.google.com/gemini-enterprise-agent-platform) > and pass its ID as `agent`. * **Turn-Scoped Parameters**: Parameters like > `tools`, `system_instruction`, and `generation_config` are turn-scoped. They > **MUST** be passed with each interaction request.

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: {
        project: "your-project-id",
        location: "global"
    }
});

---

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(
    agent="your-agent-id",  # GEAP: target a provisioned agent, not a base model
    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)

TypeScript/JavaScript

const interaction = await ai.interactions.create({
    agent: "your-agent-id", // GEAP: target a provisioned agent, not a base model
    input: "Explain serverless computing in one sentence."
});
console.log(interaction.output_text);

---

Stateful Conversation (Multi-Turn)

Interactions are stateful by default. Store the conversation state in the cloud and reference it in the subsequent turn using `previous_interaction_id`.

Python

# Turn 1: Introduce ourselves
# Interactions are s