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.

The Interactions API is experimental and may change in future versions. Requires google-genai>=2.0.

Installation

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. The Interactions API requires a Gemini API key and is not available on Vertex AI.

Mac

export GOOGLE_API_KEY=***

setx 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

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

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

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.

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.

Thinking

Enable extended reasoning with the thinking_level parameter. Accepts "minimal", "low", "medium", 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.")

Read more about thinking here.

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

Read more about Google Search here.

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

Read more about tool use here.

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

Read more about structured output here.

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.

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.

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.

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

Read more about Antigravity here.

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