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

Warning

The Interactions API is experimental and may change in future versions. You will see the following warning when using it:

1UserWarning: Interactions usage is experimental and may change in future versions.

Requires google-genai>=2.0.

Installation

1uv pip install "google-genai>=2.0" kern-ai

Authentication

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

1export GOOGLE_API_KEY=***

1setx GOOGLE_API_KEY ***

Example

1from kern.agent import Agent
2from kern.models.google import GeminiInteractions
3
4agent = Agent(
5    model=GeminiInteractions(id="gemini-3-flash-preview"),
6    markdown=True,
7)
8
9agent.print_response("Share a 2 sentence horror story.")

NoteView 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

messages

Multi-turn

Server-side history management

brain

Thinking

Reasoning with thinking levels

magnifying-glass

Google Search

Built-in web search

wrench

Tool Use

Function calling

brackets-curly

Structured Output

Pydantic schema enforcement

clock

Background Execution

Long-running tasks

magnifying-glass-chart

Deep Research

Autonomous research with citations

robot

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.

1from kern.agent import Agent
2from kern.models.google import GeminiInteractions
3
4agent = Agent(
5    model=GeminiInteractions(id="gemini-3-flash-preview"),
6    add_history_to_context=True,
7    markdown=True,
8)
9
10agent.print_response("My name is Alice and I love hiking in the mountains.")
11agent.print_response("What did I just tell you about myself?")
12agent.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".

1from kern.agent import Agent
2from kern.models.google import GeminiInteractions
3
4agent = Agent(
5    model=GeminiInteractions(
6        id="gemini-3-flash-preview",
7        thinking_level="high",
8    ),
9    markdown=True,
10)
11
12agent.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.

1from kern.agent import Agent
2from kern.models.google import GeminiInteractions
3
4agent = Agent(
5    model=GeminiInteractions(
6        id="gemini-3-flash-preview",
7        search=True,
8    ),
9    markdown=True,
10)
11
12agent.print_response("What are the latest developments in quantum computing?")

Tool Use

Function calling works the same as with the Gemini class.

1from kern.agent import Agent
2from kern.models.google import GeminiInteractions
3from kern.tools.websearch import WebSearchTools
4
5agent = Agent(
6    model=GeminiInteractions(id="gemini-3-flash-preview"),
7    tools=[WebSearchTools()],
8    markdown=True,
9)
10
11agent.print_response("Whats happening in France?")

Structured Output

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

1from kern.agent import Agent
2from kern.models.google import GeminiInteractions
3from pydantic import BaseModel, Field
4
5class MovieReview(BaseModel):
6    title: str = Field(description="The movie title")
7    year: int = Field(description="Release year")
8    genre: str = Field(description="Primary genre")
9    rating: float = Field(description="Rating out of 10")
10    summary: str = Field(description="Brief review summary")
11
12agent = Agent(
13    model=GeminiInteractions(id="gemini-3-flash-preview"),
14    output_schema=MovieReview,
15)
16
17response = 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.

1from kern.agent import Agent
2from kern.models.google import GeminiInteractions
3
4agent = Agent(
5    model=GeminiInteractions(
6        id="gemini-3-flash-preview",
7        background=True,
8    ),
9    markdown=True,
10)
11
12agent.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.

1from kern.agent import Agent
2from kern.models.google import GeminiInteractions
3
4agent = Agent(
5    model=GeminiInteractions(
6        agent="deep-research-preview-04-2026",
7        thinking_summaries="auto",
8        visualization="auto",
9    ),
10    markdown=True,
11)
12
13agent.print_response(
14    "Research the current state of solid-state battery commercialization."
15)

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.

1from kern.agent import Agent
2from kern.models.google import GeminiInteractions
3
4agent = Agent(
5    model=GeminiInteractions(
6        agent="antigravity-preview-05-2026",
7        environment="remote",
8    ),
9    markdown=True,
10)
11
12agent.print_response(
13    "Read Hacker News, summarize the top 5 stories, and save the summary "
14    "as a Markdown report."
15)

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.