> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini Interactions

> Use Google's Interactions API for server-side conversation history, implicit caching, and background execution.

The Interactions API is an alternative to Gemini's `generateContent` endpoint. Instead of sending the full conversation history on every turn, it stores prior turns server-side and references them via `previous_interaction_id`. This reduces token costs and latency through implicit caching.

See the [Interactions API documentation](https://ai.google.dev/gemini-api/docs/interactions).

> [!WARNING]
>
> The Interactions API is experimental and may change in future versions. Requires `google-genai>=2.0`.

## Installation

```bash theme={null}
uv pip install "google-genai>=2.0" agno ddgs sqlalchemy
```

## Authentication

Set the `GOOGLE_API_KEY` environment variable. You can get one [from Google AI Studio](https://ai.google.dev/gemini-api/docs/api-key). The Interactions API requires a Gemini API key and is not available on Vertex AI.

```bash Mac theme={null}
export GOOGLE_API_KEY=***
```

```bash Windows theme={null}
setx GOOGLE_API_KEY ***
```

## Example

```python theme={null}
from agno.agent import Agent
from agno.models.google import GeminiInteractions

agent = Agent(
    model=GeminiInteractions(id="gemini-3.7-flash"),
    markdown=True,
)

agent.print_response("Share a 2 sentence horror story.")
```

> [!NOTE]
>
> View more examples [here](https://agno-v2.mintlify.site/models/providers/native/google/usage/interactions-basic.md).

## How It Works

1. On the first turn, the agent sends the user message and receives a response along with an `interaction_id`.
2. On subsequent turns, only the new message is sent with `previous_interaction_id` referencing the prior turn.
3. The server reconstructs the full context from stored history, applying implicit caching to reduce cost.

This is transparent to the user. The `Agent` class handles `interaction_id` tracking automatically.

## Capabilities

> **[Multi-turn](#multi-turn-conversations)**
>
> Server-side history management

> **[Thinking](#thinking)**
>
> Reasoning with thinking levels

> **[Google Search](#google-search)**
>
> Built-in web search

> **[Tool Use](#tool-use)**
>
> Function calling

> **[Structured Output](#structured-output)**
>
> Pydantic schema enforcement

> **[Background Execution](#background-execution)**
>
> Long-running tasks

> **[Deep Research](#deep-research)**
>
> Autonomous research with citations

> **[Antigravity](#antigravity)**
>
> Autonomous sandboxed agent

## Multi-turn Conversations

Prior turns are stored server-side and referenced by ID, so only the new message is sent each turn. This is the key advantage of the Interactions API. Multi-turn requires a database so the `interaction_id` from each turn is persisted on the assistant message and read back on the next turn.

```python theme={null}
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.google import GeminiInteractions

agent = Agent(
    model=GeminiInteractions(id="gemini-3.7-flash"),
    add_history_to_context=True,
    db=SqliteDb(db_file="tmp/data.db"),
    markdown=True,
)

agent.print_response("My name is Alice and I love hiking in the mountains.")
agent.print_response("What did I just tell you about myself?")
agent.print_response("Suggest a hiking destination based on what you know about me.")
```

Read more about multi-turn conversations [here](https://agno-v2.mintlify.site/models/providers/native/google/usage/interactions-multi-turn.md).

## Thinking

Enable extended reasoning with the `thinking_level` parameter. Accepts `"minimal"`, `"low"`, `"medium"`, or `"high"`.

```python theme={null}
from agno.agent import Agent
from agno.models.google import GeminiInteractions

agent = Agent(
    model=GeminiInteractions(
        id="gemini-3.7-flash",
        thinking_level="high",
    ),
    markdown=True,
)

agent.print_response("Explain why the sum of angles in a triangle is always 180 degrees.")
```

Read more about thinking [here](https://agno-v2.mintlify.site/models/providers/native/google/usage/interactions-thinking.md).

## Google Search

Enable built-in Google Search by setting `search=True`. No external tool needed.

```python theme={null}
from agno.agent import Agent
from agno.models.google import GeminiInteractions

agent = Agent(
    model=GeminiInteractions(
        id="gemini-3.7-flash",
        search=True,
    ),
    markdown=True,
)

agent.print_response("What are the latest developments in quantum computing?")
```

Read more about Google Search [here](https://agno-v2.mintlify.site/models/providers/native/google/usage/interactions-search.md).

## Tool Use

Function calling works the same as with the `Gemini` class.

```python theme={null}
from agno.agent import Agent
from agno.models.google import GeminiInteractions
from agno.tools.websearch import WebSearchTools

agent = Agent(
    model=GeminiInteractions(id="gemini-3.7-flash"),
    tools=[WebSearchTools()],
    markdown=True,
)

agent.print_response("Whats happening in France?")
```

Read more about tool use [here](https://agno-v2.mintlify.site/models/providers/native/google/usage/interactions-tool-use.md).

## Structured Output

Use Pydantic models to enforce a JSON schema on the response.

```python theme={null}
from agno.agent import Agent
from agno.models.google import GeminiInteractions
from pydantic import BaseModel, Field

class MovieReview(BaseModel):
    title: str = Field(description="The movie title")
    year: int = Field(description="Release year")
    genre: str = Field(description="Primary genre")
    rating: float = Field(description="Rating out of 10")
    summary: str = Field(description="Brief review summary")

agent = Agent(
    model=GeminiInteractions(id="gemini-3.7-flash"),
    output_schema=MovieReview,
)

response = agent.run("Write a review of The Matrix (1999)")
```

Read more about structured output [here](https://agno-v2.mintlify.site/models/providers/native/google/usage/interactions-structured-output.md).

## Background Execution

Deep Research runs long-running tasks in the background. It forces `background=True` and `store=True` on the request; the non-streaming path polls until the result is ready, waiting `agent_poll_interval` seconds between polls up to `agent_max_wait` seconds. Background execution is handled automatically and has no user-facing flag on `GeminiInteractions`.

See [Deep Research](#deep-research).

## Managed Agents

Setting `agent` instead of `id` switches `GeminiInteractions` to Google's managed agent path (`agent` + `agent_config` instead of `model` + `generation_config`). Two agents are supported:

| Agent | Model ID | Description |
| - | - | - |
| Deep Research | `deep-research-preview-04-2026`, `deep-research-pro-preview-12-2025` | Autonomous research agent that plans, browses, and returns a report with citations. Runs in background. |
| Antigravity | `antigravity-preview-05-2026` | General-purpose autonomous agent that plans, runs code, browses, and produces artifacts inside a managed Linux sandbox. Runs in foreground. |

`agent` is mutually exclusive with `id`. Per-agent semantics (background execution, sandbox provisioning) are applied automatically based on the agent ID.

### Deep Research

Deep Research plans the task, searches the web, and returns a researched report with citations. The model forces `background=True` and `store=True`, and the non-streaming path polls until the result is ready.

```python theme={null}
from agno.agent import Agent
from agno.models.google import GeminiInteractions

agent = Agent(
    model=GeminiInteractions(
        agent="deep-research-preview-04-2026",
        thinking_summaries="auto",
        visualization="auto",
    ),
    markdown=True,
)

agent.print_response(
    "Research the current state of solid-state battery commercialization."
)
```

Deep Research config knobs:

| Parameter | Type | Description |
| - | - | - |
| `collaborative_planning` | `bool` | Turn 1 returns a plan instead of executing. Flip to `False` to execute the approved plan. |
| `thinking_summaries` | `"auto"` / `"none"` | Stream intermediate reasoning during execution. Required for streaming progress. |
| `visualization` | `"auto"` / `"off"` | Allow the agent to generate charts and graphs. |
| `agent_poll_interval` | `float` | Seconds between status polls. Default `10.0`. |
| `mcp_servers` | `list[dict]` | Remote MCP servers the agent can call. |
| `file_search_store_names` | `list[str]` | File Search store names to ground research on your own documents. |

Read more about Deep Research [here](https://agno-v2.mintlify.site/models/providers/native/google/usage/interactions-deep-research.md).

### Antigravity

Antigravity is a general-purpose autonomous agent that plans, runs code, browses the web, and produces artifacts inside a managed Linux sandbox. Unlike Deep Research, it runs in the foreground.

```python theme={null}
from agno.agent import Agent
from agno.models.google import GeminiInteractions

agent = Agent(
    model=GeminiInteractions(
        agent="antigravity-preview-05-2026",
        environment="remote",
    ),
    markdown=True,
)

agent.print_response(
    "Read Hacker News, summarize the top 5 stories, and save the summary "
    "as a Markdown report."
)
```

The `environment` parameter selects the sandbox:

| Value | Behavior |
| - | - |
| `"remote"` | Fresh remote Linux sandbox. Default for new sessions. |
| `"env_<id>"` | Reuse a previously provisioned sandbox. Faster startup, state persists. |
| `dict` | Full `EnvironmentConfig` (sources, network rules, etc.). |

Read more about Antigravity [here](https://agno-v2.mintlify.site/models/providers/native/google/usage/interactions-antigravity.md).

## Interactions API vs generateContent

| Feature | GeminiInteractions | Gemini |
| - | - | - |
| Conversation history | Server-side, referenced by ID | Client-side, resent each turn |
| Caching | Implicit on prior turns | Manual via context caching API |
| Token cost on multi-turn | Lower (only new message sent) | Higher (full history resent) |
| Background execution | Supported | Not supported |
| Response format | Typed execution steps | Generic content parts |

## Params

| Parameter | Type | Default | Description |
| - | - | - | - |
| `id` | `str` | `"gemini-3.7-flash"` | The model identifier. Mutually exclusive with `agent`. |
| `agent` | `Optional[str]` | `None` | Managed agent ID (e.g. `"deep-research-preview-04-2026"`, `"antigravity-preview-05-2026"`). Mutually exclusive with `id`. |
| `name` | `str` | `"GeminiInteractions"` | The name of the model |
| `provider` | `str` | `"Google"` | The provider of the model |
| `api_key` | `Optional[str]` | `None` | Google API key (defaults to `GOOGLE_API_KEY` env var) |
| `temperature` | `Optional[float]` | `None` | Controls randomness (0.0-2.0) |
| `top_p` | `Optional[float]` | `None` | Nucleus sampling threshold |
| `max_output_tokens` | `Optional[int]` | `None` | Maximum tokens in response |
| `stop_sequences` | `Optional[list[str]]` | `None` | Sequences that stop generation |
| `seed` | `Optional[int]` | `None` | Random seed for reproducibility |
| `response_modalities` | `Optional[list[str]]` | `None` | Output types (e.g., `["text", "image"]`) |
| `store` | `Optional[bool]` | `None` | Persist interactions server-side (default: True) |
| `thinking_level` | `Optional[str]` | `None` | Reasoning intensity: `"minimal"`, `"low"`, `"medium"`, or `"high"` |
| `search` | `bool` | `False` | Enable built-in Google Search |
| `url_context` | `bool` | `False` | Enable URL context extraction |
| `code_execution` | `bool` | `False` | Enable code execution |
| `service_tier` | `Optional[str]` | `None` | Inference tier: `"flex"`, `"standard"`, or `"priority"` |
| `mcp_servers` | `Optional[list[dict]]` | `None` | Remote MCP server configs. Supported on the model path and Deep Research, not on Antigravity. |
| `file_search_store_names` | `Optional[list[str]]` | `None` | File Search store names to ground responses on your own corpora. Supported on the model path and Deep Research, not on Antigravity. |
| `collaborative_planning` | `Optional[bool]` | `None` | Deep Research: return a plan on turn 1 instead of executing. |
| `thinking_summaries` | `Optional[str]` | `None` | Deep Research: `"auto"` or `"none"`. Stream intermediate reasoning. |
| `visualization` | `Optional[str]` | `None` | Deep Research: `"auto"` or `"off"`. Allow chart/graph generation. |
| `environment` | `Optional[Union[str, Dict]]` | `None` | Antigravity sandbox: `"remote"`, `"env_<id>"`, or full `EnvironmentConfig` dict. |
| `agent_poll_interval` | `float` | `10.0` | Seconds between status polls for background agents. |
| `agent_max_wait` | `float` | `1800.0` | Max seconds to wait for a background agent to finish. |
| `generation_config` | `Optional[Union[Dict, BaseModel]]` | `None` | Raw generation config passthrough. Keys override the fields above. |
| `timeout` | `Optional[float]` | `None` | Request timeout in seconds |
| `client_params` | `Optional[Dict[str, Any]]` | `None` | Additional client parameters |

`GeminiInteractions` is a subclass of the [Model](https://agno-v2.mintlify.site/reference/models/model.md) class and has access to the same params.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.