AI Services (advanced): Sessions and large files Follow

This documents assumes you're familiar with a basic AI Services usage.

AI Sessions

Note: As of June 2026, Gemini's /Interactions API is in Beta phase and Google's recommendation is to continue using the stateless generateContent API. Therefore as of now, AI sessions are managed on the ServiceManager side.

AI sessions can be used similary to Forms/HTML services: pass keepAlive=true to a service, then use the returned sessionId when running another service that continues it.

The active sessions will be listed under AI Sessions in Admin -> Sessions:

The ServiceManager remembers and can continue these conversations (for at least AI_SESSION_TIMEOUT_MINUTES), but there's no active session in Gemini nor between ServiceManager and Gemini.

To kill a session, use the Kill button or use a HTTP DELETE request to the /Macro/Sessions API (as in Forms/HTML).

Files API

When an AI service runs with keepAlive=true and one of its inputs is a file, the file will be automatically uploaded to the Gemini's Files API, and sent in the conversation as a URL (totally transparent to the user).

Why is it needed? 
A file of 1 million chars (~1MB) uploaded as string consumes ~250,000 tokens.
The Gemini-2.5-flash context window is 1 million tokens.
Therefore a file of 4MB already fills most of the conversation's context, and becomes a costly prompt. 
 

The Gemini's Files API is the dedicated solution for using files in a convesation, it has a limit of 2GB per file, and files are stored for 48 hours - more than enough for most use cases.