> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/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) for more details.

<Warning>
  The Interactions API is experimental and may change in future versions. You will see the following warning when using it:

  ```
  UserWarning: Interactions usage is experimental and may change in future versions.
  ```

  Requires `google-genai>=2.0`.
</Warning>

## Installation

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

## 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).

<CodeGroup>
  ```bash Mac theme={null}
  export GOOGLE_API_KEY=***
  ```

  ```bash Windows theme={null}
  setx GOOGLE_API_KEY ***
  ```
</CodeGroup>

## Example

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

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

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

<Note>View more examples [here](/models/providers/native/google/usage/interactions-basic).</Note>

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

<CardGroup cols={3}>
  <Card title="Multi-turn" icon="messages" href="#multi-turn-conversations">
    Server-side history management
  </Card>

  <Card title="Thinking" icon="brain" href="#thinking">
    Reasoning with thinking levels
  </Card>

  <Card title="Google Search" icon="magnifying-glass" href="#google-search">
    Built-in web search
  </Card>

  <Card title="Tool Use" icon="wrench" href="#tool-use">
    Function calling
  </Card>

  <Card title="Structured Output" icon="brackets-curly" href="#structured-output">
    Pydantic schema enforcement
  </Card>

  <Card title="Background Execution" icon="clock" href="#background-execution">
    Long-running tasks
  </Card>

  <Card title="Deep Research" icon="magnifying-glass-chart" href="#deep-research">
    Autonomous research with citations
  </Card>

  <Card title="Antigravity" icon="robot" href="#antigravity">
    Autonomous sandboxed agent
  </Card>
</CardGroup>

## Multi-turn Conversations

The key advantage of the Interactions API. Prior turns are stored server-side and referenced by ID, so only the new message is sent each turn.

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

agent = Agent(
    model=GeminiInteractions(id="gemini-3-flash-preview"),
    add_history_to_context=True,
    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](/models/providers/native/google/usage/interactions-multi-turn).

## Thinking

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

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

agent = Agent(
    model=GeminiInteractions(
        id="gemini-3-flash-preview",
        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](/models/providers/native/google/usage/interactions-thinking).

## 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-flash-preview",
        search=True,
    ),
    markdown=True,
)

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

Read more about Google Search [here](/models/providers/native/google/usage/interactions-search).

## 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-flash-preview"),
    tools=[WebSearchTools()],
    markdown=True,
)

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

Read more about tool use [here](/models/providers/native/google/usage/interactions-tool-use).

## 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-flash-preview"),
    output_schema=MovieReview,
)

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

Read more about structured output [here](/models/providers/native/google/usage/interactions-structured-output).

## Background Execution

For long-running tasks like Deep Research, enable background execution. The API offloads the task and returns results when complete.

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

agent = Agent(
    model=GeminiInteractions(
        id="gemini-3-flash-preview",
        background=True,
    ),
    markdown=True,
)

agent.print_response("Research the history of quantum computing.")
```

## 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 forced by the SDK 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](/models/providers/native/google/usage/interactions-deep-research).

### 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](/models/providers/native/google/usage/interactions-antigravity).

## 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-flash-preview"` | 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)                                                                          |
| `background`              | `Optional[bool]`             | `None`                     | Offload to background execution                                                                                           |
| `thinking_level`          | `Optional[str]`              | `None`                     | Reasoning intensity: `"low"` 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 available to managed agents.                                                                    |
| `file_search_store_names` | `Optional[list[str]]`        | `None`                     | File Search store names available to managed agents.                                                                      |
| `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.                                                                       |
| `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](/reference/models/model) class and has access to the same params.