Background
The Gemini Interactions API supports stateful sessions via previous_interaction_id. Instead of resending the full Message[] history on every turn, the server retains it and the client only sends the new message.
Measured savings (10-turn conversation):
- ~79% reduction in input tokens
- ~85% reduction in payload size
generateContent payload grows to 13× larger by turn 10
See docs/api-and-efficiency.md for the full analysis.
Why deferred
The Interactions API had structural breaking changes as recently as March 2026 (@google/genai v1.46.0). Migrating now risks instability. We revisit once it stabilises.
Scope
Migration is contained to two files:
src/model/gemini.ts — switch from generateContentStream to client.interactions.create()src/model/schema.ts — verify if lowercase JSONSchema types are required (Interactions API uses lowercase vs our current uppercase)
The rest of the system communicates via StreamEvent and Message[] and requires no changes.
Requirements
@google/genai >= 1.33.0 (already satisfied)- Tools and system instruction must still be resent every turn (not retained server-side)
- Maintain
thoughtSignature handling for thinking models
- Keep stateless fallback for compatibility
Background
The Gemini Interactions API supports stateful sessions via
previous_interaction_id. Instead of resending the fullMessage[]history on every turn, the server retains it and the client only sends the new message.Measured savings (10-turn conversation):
generateContentpayload grows to 13× larger by turn 10See
docs/api-and-efficiency.mdfor the full analysis.Why deferred
The Interactions API had structural breaking changes as recently as March 2026 (
@google/genaiv1.46.0). Migrating now risks instability. We revisit once it stabilises.Scope
Migration is contained to two files:
src/model/gemini.ts— switch fromgenerateContentStreamtoclient.interactions.create()src/model/schema.ts— verify if lowercase JSONSchema types are required (Interactions API uses lowercase vs our current uppercase)The rest of the system communicates via
StreamEventandMessage[]and requires no changes.Requirements
@google/genai >= 1.33.0(already satisfied)thoughtSignaturehandling for thinking models