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=***

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

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

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

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

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

Gemini Interactions

Installation

Authentication

Example

How It Works

Capabilities

Multi-turn

Thinking

Google Search

Tool Use

Structured Output

Background Execution

Multi-turn Conversations

Thinking

Google Search

Tool Use

Structured Output

Background Execution

Interactions API vs generateContent

Params

​Installation

​Authentication

​Example

​How It Works

​Capabilities

Multi-turn

Thinking

Google Search

Tool Use

Structured Output

Background Execution

​Multi-turn Conversations

​Thinking

​Google Search

​Tool Use

​Structured Output

​Background Execution

​Interactions API vs generateContent

​Params

Installation

Authentication

Example

How It Works

Capabilities

Multi-turn Conversations

Thinking

Google Search

Tool Use

Structured Output

Background Execution

Interactions API vs generateContent

Params