Gemini Interactions

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 for more details.

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.

Installation

uv pip install "google-genai>=2.0" agno

Authentication

Set the GOOGLE_API_KEY environment variable. You can get one from Google AI Studio.

export GOOGLE_API_KEY=***

Example

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.

How It Works

On the first turn, the agent sends the user message and receives a response along with an interaction_id.
On subsequent turns, only the new message is sent with previous_interaction_id referencing the prior turn.
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

Server-side history management

Thinking

Reasoning with thinking levels

Google Search

Built-in web search

Tool Use

Function calling

Structured Output

Pydantic schema enforcement

Background Execution

Long-running tasks

Deep Research

Autonomous research with citations

Antigravity

Autonomous sandboxed agent

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.

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.

Thinking

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

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

Google Search

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

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?")

Tool Use

Function calling works the same as with the Gemini class.

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?")

Structured Output

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

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)")

Background Execution

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

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.

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.

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.

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

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 class and has access to the same params.

Documentation Index

​Installation

​Authentication

​Example

​How It Works

​Capabilities

Multi-turn

Thinking

Google Search

Tool Use

Structured Output

Background Execution

Deep Research

Antigravity

​Multi-turn Conversations

​Thinking

​Google Search

​Tool Use

​Structured Output

​Background Execution

​Managed Agents

​Deep Research

​Antigravity

​Interactions API vs generateContent

​Params

Installation

Authentication

Example

How It Works

Capabilities

Multi-turn Conversations

Thinking

Google Search

Tool Use

Structured Output

Background Execution

Managed Agents

Deep Research

Antigravity

Interactions API vs generateContent

Params