Google Gemini

SideSeat instruments the Google Gen AI SDK to capture model information, token usage, messages, and costs from the Gemini API.

Prerequisites

SideSeat running locally (sideseat)
Python SDK installed with the Google GenAI extra (pip install "sideseat[google-genai]")
Google API key or Google Cloud credentials configured

Gemini Developer API

SideSeat instruments the Google Gen AI SDK automatically. Initialize SideSeat with the GoogleGenAI framework, then use the SDK as usual:

from sideseat import SideSeat, Frameworks
from google import genai

SideSeat(framework=Frameworks.GoogleGenAI)

client = genai.Client(api_key="your-api-key")

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="What is the speed of light?",
)

print(response.text)

Traces

By default, each Gemini API call produces its own independent trace. Use client.trace() to group related calls under a single root span:

client = SideSeat(framework=Frameworks.GoogleGenAI)
gemini = genai.Client(api_key="your-api-key")

with client.trace("geography-chat"):
    # Turn 1
    response1 = gemini.models.generate_content(
        model="gemini-2.5-flash",
        contents="What is the capital of France?",
    )

    # Turn 2 — follows up on the previous answer
    response2 = gemini.models.generate_content(
        model="gemini-2.5-flash",
        contents=f"The capital is {response1.text}. What about Germany?",
    )

    # Turn 3
    response3 = gemini.models.generate_content(
        model="gemini-2.5-flash",
        contents="Which of Paris and Berlin has a larger population?",
    )

This produces the following span hierarchy:

geography-chat                        (root span)
  ├── generate_content gemini-2.5...  (turn 1)
  ├── generate_content gemini-2.5...  (turn 2)
  └── generate_content gemini-2.5...  (turn 3)

All three calls appear as child spans in the SideSeat UI, with the full conversation visible in the trace detail view.

For multi-turn conversations, use the chat API within a trace:

with client.trace("multi-turn-chat"):
    chat = gemini.chats.create(model="gemini-2.5-flash")

    response1 = chat.send_message("What is the capital of France?")
    response2 = chat.send_message("Tell me more about it.")

Sessions

Pass session_id and user_id to client.trace() to group independent traces into a session. The SideSeat sessions view groups all traces that share the same session_id.

Each client.trace() produces its own trace with its own trace ID, but they are linked by the shared session:

from sideseat import SideSeat, Frameworks
from google import genai

client = SideSeat(framework=Frameworks.GoogleGenAI)
gemini = genai.Client(api_key="your-api-key")

session_id = "sess-abc"
user_id = "user-123"

# Trace 1: Trip planning
with client.trace("trip-planning", session_id=session_id, user_id=user_id):
    chat = gemini.chats.create(model="gemini-2.5-flash")
    response = chat.send_message("Plan a 5-day trip to Japan.")
    response = chat.send_message("Tell me more about Kyoto.")

# Trace 2: Food recommendations (fresh conversation, same session)
with client.trace("food-recommendations", session_id=session_id, user_id=user_id):
    chat = gemini.chats.create(model="gemini-2.5-flash")
    response = chat.send_message("What are the must-try dishes in Tokyo?")
    response = chat.send_message("What about street food in Osaka?")

This produces two independent traces, each with their own span hierarchy:

Trace 1: trip-planning              (session_id=sess-abc, user_id=user-123)
  ├── send_message gemini-2.5...    (turn 1)
  └── send_message gemini-2.5...    (turn 2)

Trace 2: food-recommendations       (session_id=sess-abc, user_id=user-123)
  ├── send_message gemini-2.5...    (turn 1)
  └── send_message gemini-2.5...    (turn 2)

Each trace starts a fresh conversation with its own message history. The SideSeat sessions view groups them by session_id.

Vertex AI

To use the Vertex AI Gemini API, set vertexai=True on the client:

from sideseat import SideSeat, Frameworks
from google import genai

SideSeat(framework=Frameworks.GoogleGenAI)

client = genai.Client(
    vertexai=True,
    project="your-project",
    location="us-central1",
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="What is the speed of light?",
)

print(response.text)

Streaming

Streaming responses are fully captured, including token counts aggregated from stream chunks:

from sideseat import SideSeat, Frameworks
from google import genai

client = SideSeat(framework=Frameworks.GoogleGenAI)
gemini = genai.Client(api_key="your-api-key")

for chunk in gemini.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents="What is the boiling point of water?",
):
    print(chunk.text, end="", flush=True)

Tool Use

Tool definitions and function call results are captured:

from sideseat import SideSeat, Frameworks
from google import genai
from google.genai.types import FunctionDeclaration, Tool

client = SideSeat(framework=Frameworks.GoogleGenAI)
gemini = genai.Client(api_key="your-api-key")

get_weather = FunctionDeclaration(
    name="get_weather",
    description="Get the current weather for a location.",
    parameters={
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City name"}
        },
        "required": ["location"],
    },
)

tool = Tool(function_declarations=[get_weather])

response = gemini.models.generate_content(
    model="gemini-2.5-flash",
    contents="What's the weather in Paris?",
    config={"tools": [tool]},
)

SideSeat captures the tool definitions, function call requests, and function call results.

Authentication

# Gemini Developer API — use an API key
export GOOGLE_API_KEY=your-api-key

# Vertex AI — use Google Cloud credentials
gcloud auth application-default login
# Or service account
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

The Google Gen AI SDK reads GOOGLE_API_KEY from the environment automatically for the Developer API. For Vertex AI, it uses Application Default Credentials.

Next Steps

Google ADK — use SideSeat with the Google Agent Development Kit
Python SDK — SDK configuration and API reference
Overview — get started with SideSeat