gemini-interactions-api

Files (4)

• SKILL.md
• attribution.md · references/
• data_model.md · references/
• rest_api.md · references/

SKILL.md (first lines)

# 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-05-2026`, `deep-research-preview-04-2026`, or custom
> agents provisioned via `client.agents.create()`) using `agent="<AGENT_ID>"`.
> Managed agents (`antigravity-preview-05-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**:
    
    ```bash
    gcloud auth application-default login
    ```
2.  **Enable API** (if not already enabled):
    
    ```bash
    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:

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

#### Python

```python
from google import genai

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

#### TypeScript/JavaScript

```typescript
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

```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

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

const ai = new GoogleGenAI({
    enterprise: true,

From google/skills, Apache-2.0.

More from google/skills