Google realtime session

[BETA] Defines a realtime session module to interact with Gemini Live models.

Authors

Henry Wicaksono (henry.wicaksono@gdplabs.id)

References

[1] https://ai.google.dev/gemini-api/docs/live

GoogleRealtimeOrchestrator(session, task_group, input_queue, output_queue, input_streamers, output_streamers, tool_dict, logger)

[BETA] Defines the GoogleRealtimeOrchestrator.

This class manages the realtime conversation lifecycle. It handles the IO operations between the model and the input/output streamers.

Attributes:

Name	Type	Description
session	AsyncSession	The session of the GoogleRealtimeOrchestrator.
task_group	TaskGroup	The task group of the GoogleRealtimeOrchestrator.
input_queue	Queue	The input queue of the GoogleRealtimeOrchestrator.
output_queue	Queue	The output queue of the GoogleRealtimeOrchestrator.
input_streamers	list[BaseInputStreamer]	The input streamers of the GoogleRealtimeOrchestrator.
output_streamers	list[BaseOutputStreamer]	The output streamers of the GoogleRealtimeOrchestrator.
tool_dict	dict[str, Tool]	The dictionary of tools of the GoogleRealtimeOrchestrator.
tool_call_queue	Queue	The tool call queue of the GoogleRealtimeOrchestrator.
state	RealtimeState	The state of the GoogleRealtimeOrchestrator.

Initializes a new instance of the GoogleRealtimeOrchestrator class.

Parameters:

Name	Type	Description	Default
session	AsyncSession	The session of the GoogleRealtimeOrchestrator.	required
task_group	TaskGroup	The task group of the GoogleRealtimeOrchestrator.	required
input_queue	Queue[RealtimeEvent]	The input queue of the GoogleRealtimeOrchestrator.	required
output_queue	Queue[RealtimeEvent]	The output queue of the GoogleRealtimeOrchestrator.	required
input_streamers	list[BaseInputStreamer]	The input streamers of the GoogleRealtimeOrchestrator.	required
output_streamers	list[BaseOutputStreamer]	The output streamers of the GoogleRealtimeOrchestrator.	required
tool_dict	dict[str, Tool]	A dictionary of tools provided to the model.	required
logger	Logger	The logger of the GoogleRealtimeOrchestrator.	required

start() async

Processes the realtime conversation.

This method is used to start the realtime conversation. It initializes the input and output streamers, creates the necessary tasks, and starts the conversation. When the conversation is terminated, it cleans up the input and output streamers.

GoogleRealtimeSession(model_name, api_key=None, credentials_path=None, project_id=None, location='us-central1', tools=None, config=None)

Bases: BaseRealtimeSession

[BETA] A realtime session module to interact with Gemini Live models.

Warning

The 'GoogleRealtimeSession' class is currently in beta and may be subject to changes in the future. It is intended only for quick prototyping in local environments. Please avoid using it in production environments.

Attributes:

Name	Type	Description
model_name	str	The name of the language model.
client_params	dict[str, Any]	The Google client instance init parameters.
config	LiveConnectConfig	The configuration for the realtime session.
tool_dict	dict[str, Tool]	A dictionary of tools provided to the model.

Basic usage

The GoogleRealtimeSession can be used as started as follows:

realtime_session = GoogleRealtimeSession(model_name="gemini-live-2.5-flash-preview")
await realtime_session.invoke()

Tool calling

The GoogleRealtimeSession can call provided tools to perform certain tasks. This feature can be enabled by providing a list of Tool objects to the tools parameter.

Usage example:

tools = [get_weather, get_temperature]
realtime_session = GoogleRealtimeSession(model_name="gemini-live-2.5-flash-preview", tools=tools)
await realtime_session.start()

Custom IO streamers

The GoogleRealtimeSession can be used with custom IO streamers.

input_streamers = [KeyboardInputStreamer(), LinuxMicInputStreamer()]
output_streamers = [ConsoleOutputStreamer(), LinuxSpeakerOutputStreamer()]
realtime_session = GoogleRealtimeSession(model_name="gemini-live-2.5-flash-preview")
await realtime_session.start(input_streamers=input_streamers, output_streamers=output_streamers)

In the above example, we added a capability to use a Linux system microphone and speaker, allowing realtime audio input and output to the model.

Authentication

The GoogleRealtimeSession can use either Google Gen AI or Google Vertex AI.

Google Gen AI is recommended for quick prototyping and development. It requires a Gemini API key for authentication.

Usage example:

realtime_session = GoogleRealtimeSession(
    model_name="gemini-2.5-flash-native-audio-preview-12-2025",
    api_key="your_api_key"
)

Google Vertex AI is recommended to build production-ready applications. It requires a service account JSON file for authentication.

Usage example:

realtime_session = GoogleRealtimeSession(
    model_name="gemini-2.5-flash-native-audio-preview-12-2025",
    credentials_path="path/to/service_account.json"
)

If neither api_key nor credentials_path is provided, Google Gen AI will be used by default. The GOOGLE_API_KEY environment variable will be used for authentication.

Initializes a new instance of the GoogleRealtimeChat class.

Parameters:

Name	Type	Description	Default
model_name	str	The name of the model to use.	required
api_key	str | None	Required for Google Gen AI authentication. Cannot be used together with credentials_path. Defaults to None.	None
credentials_path	str | None	Required for Google Vertex AI authentication. Path to the service account credentials JSON file. Cannot be used together with api_key. Defaults to None.	None
project_id	str | None	The Google Cloud project ID for Vertex AI. Only used when authenticating with credentials_path. Defaults to None, in which case it will be loaded from the credentials file.	None
location	str	The location of the Google Cloud project for Vertex AI. Only used when authenticating with credentials_path. Defaults to "us-central1".	'us-central1'
tools	list[Tool] | None	Tools provided to the model to enable tool calling. Defaults to None.	None
config	dict[str, Any] | None	Additional configuration for the realtime session. Defaults to None.	None

Note

If neither api_key nor credentials_path is provided, Google Gen AI will be used by default. The GOOGLE_API_KEY environment variable will be used for authentication.

Key

Defines valid keys in Google Realtime Session.