Gemini Interactions Api

# Migration Reference

How to migrate existing Gemini API code to the Interactions API and/or upgrade between model generations. Covers the agent workflow for performing migrations safely.

For detailed before/after code examples across all feature areas (text generation, multi-turn, streaming, function calling, structured output, grounding, multimodal), fetch the full migration guide: https://ai.google.dev/gemini-api/docs/migrate-to-interactions.md.txt

## Confirm the Migration Scope

**Before any edits, confirm the scope.** If the user's request does not explicitly name a single file, a specific directory, or an explicit file list, ask first and do not start editing.

Even imperative requests like "migrate my code", "upgrade to gemini 3", or "switch to the Interactions API" leave the scope ambiguous. Ask:

> Before I start editing, can you confirm the scope?
> 1. Entire project
> 2. Specific subdirectory (e.g. `src/`, `api/`)
> 3. Specific file or list of files

**Sizing the scope (large repos).** Before asking, get a per-directory count:

```sh
rg -l "generate_content\|generateContent\|gemini-2\.0\|gemini-1\.5\|gemini-2\.5\|gemini-3-flash-preview\|thinking_budget\|temperature" --type-not md | cut -d/ -f1 | sort | uniq -c | sort -rn
```

Present the breakdown in your question (e.g. *"Found 42 references across 3 directories: src/ (28), tests/ (10), scripts/ (4). Which to migrate?"*).

**Proceed without asking** only when the scope is already unambiguous, the user named an exact file ("migrate `app.py`"), pointed at a directory ("migrate everything under `src/`"), or already confirmed scope in an earlier turn.

## API Migration: `generateContent` → `Interactions`

The core changes when migrating from `generateContent` to the Interactions API:

| What | `generateContent` | Interactions API |
|------|----------------|-----------------|
| **SDK method** | `client.models.generate_content()` | `client.interactions.create()` |
| **Response text** | `response.text` | `interaction.steps[-1].content[0].text` |
| **Multi-turn** | Manual history array or `client.chats.create()` | `previous_interaction_id=interaction.id` |
| **Streaming** | `generate_content_stream()` / `:streamGenerateContent` | `stream=True` + `step.delta` events |
| **Structured output** | `config.response_format` inside `GenerateContentConfig` | Top-level `response_format` array |
| **Function calling** | `candidates[0].content.parts[0].function_call` | `function_call` step in `interaction.steps` |
| **Search grounding** | `groundingMetadata` on candidates | `google_search_call`/`google_search_result` steps + inline `annotations` |
| **Config/types** | `types.GenerateContentConfig(...)`, `types.Tool(...)`, `types.Content(...)`, `types.Part.*` | Not used. Interactions API uses plain Python dicts and direct params. Check the feature docs for exact format. |
| **REST endpoint** | `POST /v1beta/models/{model}:generateContent` | `POST /v1beta/interactions` |
| **SDK package** | `google-genai` ≥ 1.x or legacy `google-generativeai` | `google-genai` ≥ 2.0.0 |

For full before/after code examples, fetch the [Migration Guide](https://ai.google.dev/gemini-api/docs/migrate-to-interactions.md.txt) or read the Interactions API documentation pages for each feature.

## Model Migration

### Deprecated Models

| Model | Status | Drop-in Replacement |
|-------|--------|-------------------|
| `gemini-2.0-flash` | Deprecated | `gemini-3.5-flash` |
| `gemini-2.0-flash-lite` | Deprecated | `gemini-3.1-flash-lite-preview` |
| `gemini-1.5-pro` | Deprecated | `gemini-3.5-flash` |
| `gemini-1.5-flash` | Deprecated | `gemini-3.5-flash` |

### Active Legacy Models (migration recommended)

| Current Model | Recommended Target | Why |
|--------------|-------------------|-----|
| `gemini-3-flash-preview` | `gemini-3.5-flash` | Latest Flash with Interactions API support |
| `gemini-2.5-flash` | `gemini-3.5-flash` | Latest Flash with Interactions API support |
| `gemini-2.5-pro` | `gemini-3.1-pro-pr