gemini-interactions-api

What this skill does

# 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**
> *   **Unified SDK**: Use the Google Gen AI SDK (**`google-genai >= 2.0.0`** for Python, **`@google/genai >= 2.0.0`** for JS/TS). Legacy SDKs like `google-cloud-aiplatform`, `@google-cloud/vertexai`, and `google-generativeai` are strictly unsupported for Interactions.
> *   **Latest Models Only**: Use `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite`, `gemini-3-flash-preview`, `gemini-2.5-pro`, or `gemini-2.5-flash`. 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-2.0-*`, `gemini-1.5-*`) are deprecated and do not support interactions.
> *   **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**:
    ```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: {
        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
```python
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain serverless computing in one sentence."
)
# Output text is located under steps
print(interaction.steps[-1].content[0].text)
```

#### TypeScript/JavaScript
```typescript
const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain serverless computing in one sentence."
});
console.log(interaction.steps[interaction.steps.length - 1].content[0].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
```python
# Turn 1: Introduce ourselves
turn1 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Hi! My name is John. I am working on AI agents.",
    store=True
)
print(f"Turn 1: {turn1.steps[-1].content[0].text}")

# Turn 2: Refer back to the stored turn state
turn2 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is my name?",
    previous_interaction_id=turn1.id
)
print(f"Turn 2: {turn2.steps[-1].content[0].text}")
```

#### TypeScript/JavaScript
```typescript
// Turn 1
const turn1 = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Hi! My name is John. I am working on AI agents.",
    store: true
});

// Turn 2
const turn2 = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is my name?",
    previousInteractionId: turn1.id
});
console.log(turn2.steps[turn2.steps.length - 1].content[0].text);
```

---

### Real-Time Streaming

Stream responses in real-time. Passing `stream=True` returns an iterable chunk generator.

#### Python
```python
response = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Write a short poem about debugging.",
    stream=True
)

for chunk in response:
    if chunk.steps:
        step = chunk.steps[-1]
        if step.content and step.content[0].text:
            print(step.content[0].text, end="", flush=True)
print()
```

#### TypeScript/JavaScript
```typescript
const responseStream = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Write a short poem about debugging.",
    stream: true
});

for await (const chunk of responseStream) {
    if (chunk.steps) {
        const step = chunk.steps[chunk.steps.length - 1];
        if (step.content && step.content[0].text) {
            process.stdout.write(step.content[0].text);
        }
    }
}
console.log();
```

---

### Structured Output (Pydantic / Polymorphic `response_format`)

Retrieve structured, type-safe JSON matching a schema. Under the modern Interactions API, a polymorphic `response_format` argument directly takes the target schema structure.

#### Python
```python
from pydantic import BaseModel, Field

class Book(BaseModel):
    title: str = Field(description="The title of the book")
    author: str = Field(description="The book's author")
    year_published: int

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Recommend one famous sci-fi book.",
    response_format=Book
)

# The text will be a valid JSON matching the Book schema
print(interaction.steps[-1].content[0].text)
```

#### TypeScript/JavaScript
```typescript
import { Type } from "@google/genai";

const BookSchema = {
    type: Type.OBJECT,
    properties: {
        title: { type: Type.STRING, description: "The title of the book" },
        author: { type: Type.STRING, description: "The book's author" },
        yearPublished: { type: Type.INTEGER }
    },
    required: ["title", "author", "yearPublished"]
};

const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Recommend one famous sci-fi book.",
    responseFormat: BookSchema
});

console.log(interaction.steps[interaction.steps.length - 1].content[0].text);
```

---

### Function Calling (Agent Tool Use)

Define local tools (functions) and submit execution results to the stateful interaction history.

#### Python
```python
def get_stock_price(ticker: str) -> float:
    """Gets the stock price for a given ticker symbol."""
    if ticker.upper() == "GOOG":
        return 175.50
    return 100.0

# Turn 1: Pass tools to the model
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the stock price of GOOG?",
    tools=[get_stock_price]
)

last_step = interaction.steps[-1]
# Check if the model requested a function call
if last_step.tool_calls:
    for call in last_step.tool_calls:
        if call.name == "get_stock_price":
            ticker_arg = call.args.get("ticker")
            price = get_stock_price(ticker_arg)

            # Turn 2: Submit function execution result statefully