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 the history sent by the client. Billing and latency still depend on context size and cache use.

See the Interactions API documentation.

Installation

uv pip install "google-genai>=2.3" 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.

export GOOGLE_API_KEY=***

Example

from agno.agent import Agent
from agno.models.google import GeminiInteractions

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

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

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 eligible implicit caching. Prior context is still part of the model input; it is not free merely because the client sends only new messages.

The Agent class handles interaction_id tracking automatically. With store=False, ordinary model requests omit previous_interaction_id. The current Agno adapter serializes user messages, assistant tool calls, and tool results, but omits plain assistant replies. Use stored interactions when a conversation needs those prior replies; stateless multi-turn history is incomplete in this adapter. Managed agents force storage. Both Interactions and generateContent support caching, so smaller HTTP payloads alone do not establish lower token charges.

Capabilities

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.7-flash"),
    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.7-flash",
        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.7-flash",
        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.7-flash"),
    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.7-flash"),
    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 takes precedence over id when building the request; the constructor does not reject both together. 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:

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:

Read more about Antigravity here.

Interactions API vs generateContent

Params

GeminiInteractions is a subclass of the Model class and has access to the same params.