> ## Documentation Index
> Fetch the complete documentation index at: https://phidatainc.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).
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-flash-preview"),
markdown=True,
)
agent.print_response("Share a 2 sentence horror story.")
```
View more examples [here](/models/providers/native/google/usage/interactions-basic).
## 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
Server-side history management
Reasoning with thinking levels
Built-in web search
Function calling
Pydantic schema enforcement
Long-running tasks
Autonomous research with citations
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-flash-preview"),
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](/models/providers/native/google/usage/interactions-multi-turn).
## 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-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
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](/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_"` | 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) |
| `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_"`, 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](/reference/models/model) class and has access to the same params.