Gemini

Trace Gemini calls from your TypeScript application, then run experiments against Gemini models.

Tracing

Trace Gemini calls to Braintrust with the native Google GenAI SDK, or route them through the Braintrust gateway.

Setup

Install the Braintrust and Google GenAI SDKs, then set your API keys.

Install packages

pnpm add braintrust @google/genai

npm install braintrust @google/genai

Set environment variables

.env

GEMINI_API_KEY=<your-gemini-api-key>
BRAINTRUST_API_KEY=<your-braintrust-api-key>

# For organizations on the EU data plane, use https://api-eu.braintrust.dev
# For self-hosted deployments, use your data plane URL
# BRAINTRUST_API_URL=<your-braintrust-api-url-here>

Auto-instrumentation

To trace Gemini calls without modifying your application code, run your app with Braintrust’s import hook. The hook patches the Google GenAI SDK at startup, so calls from an unwrapped client are traced automatically.

trace-gemini-auto.js

import { GoogleGenAI } from "@google/genai";
import { initLogger } from "braintrust";

initLogger({
  projectName: "My Project", // Replace with your project name
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await client.models.generateContent({
  model: "gemini-3.6-flash",
  contents: "What is the capital of France?",
});
console.log(response.text);

Run your app with the import hook:

node --import braintrust/hook.mjs trace-gemini-auto.js

The auto-instrumentation example uses plain JavaScript so node --import can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook.

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

Manual instrumentation

To trace Gemini calls manually, wrap the Google GenAI module yourself with wrapGoogleGenAI. Every call from the wrapped client is then logged to Braintrust.

import * as googleGenAI from "@google/genai";
import { wrapGoogleGenAI, initLogger } from "braintrust";

// Initialize Braintrust tracing
initLogger({ projectName: "My Project" });

// Use wrapGoogleGenAI to wrap the Google GenAI module for automatic tracing
const { GoogleGenAI } = wrapGoogleGenAI(googleGenAI);

// Create a native Google GenAI client
const client = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY || "",
});

// All API calls are automatically logged
const response = await client.models.generateContent({
  model: "gemini-3.6-flash",
  contents: "What is machine learning?",
  config: {
    maxOutputTokens: 100,
  },
});
console.log(response.text);

Gateway

To route Gemini calls through the Braintrust gateway, point the OpenAI SDK at the gateway base URL with your Braintrust API key. Routing and logging happen server-side, so you can reach Gemini through any supported provider’s SDK.Install the braintrust and openai packages.

pnpm add braintrust openai

npm install braintrust openai

Initialize the client and make a request to a Gemini model through the gateway.

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.braintrust.dev/v1",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gemini-3.6-flash",
  messages: [{ role: "user", content: "Hello, world!" }],
});

Log to a project

To log gateway calls to a specific project, initialize a logger with initLogger.

import { OpenAI } from "openai";
import { initLogger } from "braintrust";

initLogger({
  projectName: "My Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const client = new OpenAI({
  baseURL: "https://gateway.braintrust.dev/v1",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

// All API calls are automatically logged
const result = await client.chat.completions.create({
  model: "gemini-3.6-flash",
  messages: [{ role: "user", content: "What is machine learning?" }],
});

Streaming

Stream Gemini responses through the gateway.

const stream = await client.chat.completions.create({
  model: "gemini-3.6-flash",
  messages: [{ role: "user", content: "Count to 10" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Embeddings

The gateway also supports Gemini’s native embedContent and batchEmbedContents endpoints, including multimodal text and image content. See Generate embeddings for an example.

Streaming

Stream responses from the native Google GenAI client with automatic tracing.

const stream = await client.models.generateContentStream({
  model: "gemini-3.6-flash",
  contents: "Count from 1 to 10 slowly.",
  config: {
    maxOutputTokens: 200,
  },
});

// All streaming chunks are automatically logged
for await (const chunk of stream) {
  if (chunk.text) {
    process.stdout.write(chunk.text);
  }
}

The wrapper aggregates streamed chunks and records streaming token metrics.

import * as googleGenAI from "@google/genai";
import { wrapGoogleGenAI, initLogger } from "braintrust";

// Setup automatic tracing
initLogger({ projectName: "My Project" });
const { GoogleGenAI } = wrapGoogleGenAI(googleGenAI);

const client = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY || "",
});

// Stream responses - automatically tracked
const stream = await client.models.generateContentStream({
  model: "gemini-3.6-flash",
  contents: "Write a story about a robot learning to paint.",
  config: {
    maxOutputTokens: 500,
  },
});

// Streaming automatically tracks:
// - time_to_first_token
// - prompt_tokens, completion_tokens, total_tokens
// - prompt_cached_tokens (if using caching)
for await (const chunk of stream) {
  if (chunk.text) {
    process.stdout.write(chunk.text);
  }
}

Structured outputs

Gemini supports structured JSON outputs using response schemas.

import * as googleGenAI from "@google/genai";
import { wrapGoogleGenAI, initLogger } from "braintrust";

// Setup automatic tracing
initLogger({ projectName: "My Project" });
const { GoogleGenAI } = wrapGoogleGenAI(googleGenAI);

const client = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY || "",
});

// Define a schema for the response
interface Person {
  name: string;
  age: number;
  occupation: string;
}

const response = await client.models.generateContent({
  model: "gemini-3.6-flash",
  contents:
    "Extract information about: John Smith is a 30-year-old software engineer.",
  config: {
    responseMimeType: "application/json",
    responseSchema: {
      type: "object",
      properties: {
        name: { type: "string" },
        age: { type: "number" },
        occupation: { type: "string" },
      },
      required: ["name", "age", "occupation"],
    },
    maxOutputTokens: 200,
  },
});

// Parse the JSON response
const personData: Person = JSON.parse(response.text);
console.log(`Name: ${personData.name}, Age: ${personData.age}`);

Function calling

Gemini supports function calling for building AI agents with tools.

import * as googleGenAI from "@google/genai";
import { wrapGoogleGenAI, initLogger } from "braintrust";

// Setup automatic tracing
initLogger({ projectName: "My Project" });
const { GoogleGenAI } = wrapGoogleGenAI(googleGenAI);

const client = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY || "",
});

// Define functions for the model to call
function getWeather(location: string, unit: string = "celsius"): string {
  // In a real app, this would call a weather API
  return `22 degrees ${unit} and sunny in ${location}`;
}

function searchWeb(query: string): string {
  return `Search results for: ${query}`;
}

// Define function declarations
const tools = [
  {
    functionDeclarations: [
      {
        name: "get_weather",
        description: "Get the current weather for a location",
        parameters: {
          type: "object",
          properties: {
            location: {
              type: "string",
              description: "The city and state, e.g. San Francisco, CA",
            },
            unit: {
              type: "string",
              enum: ["celsius", "fahrenheit"],
              description: "The unit of temperature",
            },
          },
          required: ["location"],
        },
      },
      {
        name: "search_web",
        description: "Search the web for information",
        parameters: {
          type: "object",
          properties: {
            query: {
              type: "string",
              description: "The search query",
            },
          },
          required: ["query"],
        },
      },
    ],
  },
];

// Generate with tools
const response = await client.models.generateContent({
  model: "gemini-3.6-flash",
  contents:
    "What's the weather in Paris and what tourist sites should I visit?",
  config: {
    tools: tools,
    maxOutputTokens: 500,
  },
});

// Handle function calls
if (response.candidates[0].content.parts) {
  for (const part of response.candidates[0].content.parts) {
    if (part.functionCall) {
      const fc = part.functionCall;
      console.log(`Function: ${fc.name}`);
      console.log(`Arguments: ${JSON.stringify(fc.args)}`);

      // Execute the function
      if (fc.name === "get_weather") {
        const result = getWeather(fc.args.location, fc.args.unit);
        // Send result back to model for final response
      }
    }
  }
}

Multimodal content

Gemini models support multimodal inputs including images, audio, and video.

import * as googleGenAI from "@google/genai";
import { wrapGoogleGenAI, initLogger } from "braintrust";
import * as fs from "fs";

// Setup automatic tracing
initLogger({ projectName: "My Project" });
const { GoogleGenAI } = wrapGoogleGenAI(googleGenAI);

const client = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY || "",
});

// Image analysis
const imageData = fs.readFileSync("image.jpg");

const response = await client.models.generateContent({
  model: "gemini-3.6-flash",
  contents: [
    { text: "What's in this image?" },
    {
      inlineData: {
        mimeType: "image/jpeg",
        data: imageData.toString("base64"),
      },
    },
  ],
});

// Audio transcription
const audioData = fs.readFileSync("audio.mp3");

const audioResponse = await client.models.generateContent({
  model: "gemini-3.6-flash",
  contents: [
    { text: "Transcribe this audio:" },
    {
      inlineData: {
        mimeType: "audio/mp3",
        data: audioData.toString("base64"),
      },
    },
  ],
});

// The wrapper automatically handles binary data serialization
// Binary attachments are converted to Braintrust Attachment objects

Reasoning models

Gemini 3 models like gemini-3.6-flash and gemini-3.1-pro have built-in reasoning capabilities enabled by default. Configure reasoning behavior with thinkingConfig.

import * as googleGenAI from "@google/genai";
import { wrapGoogleGenAI, initLogger } from "braintrust";

// Setup automatic tracing
initLogger({ projectName: "My Project" });
const { GoogleGenAI } = wrapGoogleGenAI(googleGenAI);

const client = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY || "",
});

// Use reasoning model - reasoning tokens are automatically tracked
const response = await client.models.generateContent({
  model: "gemini-3.6-flash",
  contents: "What is the derivative of x^2 + 3x + 5? Think step by step.",
  config: {
    maxOutputTokens: 1000,
  },
});

// The response includes both the reasoning and final answer
console.log(response.text);

// Metrics automatically include reasoning tokens
// The wrapper captures completion_reasoning_tokens in the metrics

Context caching

Gemini supports context caching for efficient reuse of large contexts.

import * as googleGenAI from "@google/genai";
import { wrapGoogleGenAI, initLogger } from "braintrust";

// Setup automatic tracing
initLogger({ projectName: "My Project" });
const { GoogleGenAI } = wrapGoogleGenAI(googleGenAI);

const client = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY || "",
});

// Create a cache for a large document
const documentContent = "... very long document content ...";

// Note: Caching API requires the full Vertex AI SDK
// This example shows the structure - refer to Google's documentation
// for complete caching implementation

const response = await client.models.generateContent({
  model: "gemini-3.6-flash",
  contents: "Summarize the key points from the document",
  config: {
    // cachedContent would be configured here
    maxOutputTokens: 500,
  },
});

// The wrapper tracks cached tokens in metrics
// Look for prompt_cached_tokens in the logged metrics

Error handling, attachments, and masking sensitive data

To learn more about these topics, check out the customize traces guide.

import { OpenAI } from "openai";
import "@braintrust/proxy/types"; // for type safety

const client = new OpenAI({
  baseURL: "https://gateway.braintrust.dev/v1",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gemini-3.6-flash",
  reasoning_enabled: true,
  reasoning_budget: 1024,
  messages: [{ role: "user", content: "How many rs in 'ferrocarril'?" }],
});

console.log(response.choices[0].reasoning); // Access reasoning steps

To learn more about multimodal support, attachments, error handling, and masking sensitive data with Gemini, visit the customize traces guide.

What Braintrust traces

Braintrust captures:

Content generation spans (generate_content and generate_content_stream), with the request as input and the full response as output. Streaming adds time to first token.
Embedding spans (embed_content), with embedding count and length and token usage.
Interaction spans (create_interaction) for foreground interactions.create calls, including streaming, with the interaction input, output, and usage.
Token metrics: prompt, completion, total (tokens), cached (prompt_cached_tokens), reasoning (completion_reasoning_tokens), and audio and image modality tokens.
Google Search grounding metadata on grounded responses.
Binary inputs (images, audio, and documents) uploaded as Braintrust attachments.

Tracing resources

Google GenAI SDK reference for the API surface being traced.
braintrust on npm for the tracing package.
Trace LLM calls for tracing patterns across providers.

Evals

Evaluate the output of Gemini models by running experiments with Braintrust Eval. Each eval combines a dataset, a task, and one or more scorers. To learn more, see the Experiments guide.

Native SDK

Run experiments that call Gemini through the native Google GenAI SDK.

import * as googleGenAI from "@google/genai";
import { Eval, wrapGoogleGenAI, initLogger } from "braintrust";

// Setup tracing
initLogger({ projectName: "Gemini Evaluation" });
const { GoogleGenAI } = wrapGoogleGenAI(googleGenAI);

const client = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY || "",
});

Eval("Gemini Native Evaluation", {
  data: () => [
    { input: "What is 2+2?", expected: "4" },
    { input: "What is the capital of France?", expected: "Paris" },
  ],
  task: async (input) => {
    const response = await client.models.generateContent({
      model: "gemini-3.6-flash",
      contents: input,
      config: {
        maxOutputTokens: 100,
      },
    });
    return response.text;
  },
  scores: [
    {
      name: "accuracy",
      scorer: (args) => (args.output === args.expected ? 1 : 0),
    },
  ],
});

Gateway

Run experiments that call Gemini through the Braintrust gateway.

import { Eval } from "braintrust";
import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.braintrust.dev/v1",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

Eval("Gemini Evaluation", {
  data: () => [
    { input: "What is 2+2?", expected: "4" },
    { input: "What is the capital of France?", expected: "Paris" },
  ],
  task: async (input) => {
    const response = await client.chat.completions.create({
      model: "gemini-3.6-flash",
      messages: [{ role: "user", content: input }],
    });
    return response.choices[0].message.content;
  },
  scores: [
    {
      name: "accuracy",
      scorer: (args) => (args.output === args.expected ? 1 : 0),
    },
  ],
});

Legacy SDK (`@google/generative-ai`)

The @google/generative-ai package (v0.24.x) is the older Google Generative AI SDK for TypeScript, separate from the newer @google/genai SDK documented above. Braintrust supports auto-instrumentation and manual instrumentation for this legacy SDK.

Auto-instrumentation

Install the Braintrust and @google/generative-ai packages, then run your app with the import hook. Requires @google/generative-ai v0.24.0 or later.

Install packages

pnpm add braintrust @google/generative-ai

npm install braintrust @google/generative-ai

Initialize Braintrust and call the legacy SDK

trace-legacy-gemini-auto.js

import { GoogleGenerativeAI } from "@google/generative-ai";
import { initLogger } from "braintrust";

initLogger({
  projectName: "gemini-example",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

const result = await model.generateContent("What is the capital of France?");
console.log(result.response.text());

Run with the import hook

node --import braintrust/hook.mjs trace-legacy-gemini-auto.js

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

Manual instrumentation

To trace legacy SDK clients manually, wrap the client with wrapGoogleGenerativeAI().

import { GoogleGenerativeAI } from "@google/generative-ai";
import { initLogger, wrapGoogleGenerativeAI } from "braintrust";

initLogger({
  projectName: "gemini-example",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const client = wrapGoogleGenerativeAI(
  new GoogleGenerativeAI(process.env.GEMINI_API_KEY),
);

const model = client.getGenerativeModel({ model: "gemini-1.5-flash" });
const result = await model.generateContent("What is the capital of France?");
console.log(result.response.text());

What Braintrust traces

Braintrust patches the @google/generative-ai SDK and creates a span per call:

Content generation spans (generate_content, generate_content_stream): input contents, model, generation config, safety settings, and tools as metadata. Output includes response text, token usage (prompt_tokens, completion_tokens, tokens), and time_to_first_token on streaming calls.
Embedding spans (embed_content, batch_embed_contents): input text and model as metadata.
Chat spans (send_message, send_message_stream): message input and model as metadata. Streaming calls also capture time_to_first_token.
Images handled as Braintrust attachments.
Errors captured on every call.

AI providers

SDKs

Developer tools

Runtime environments

Tracing

Setup

Auto-instrumentation

Manual instrumentation

Gateway

Log to a project

Streaming

Embeddings

Streaming

Structured outputs

Function calling

Multimodal content

Reasoning models

Context caching

Error handling, attachments, and masking sensitive data

What Braintrust traces

Tracing resources

Evals

Native SDK

Gateway

Legacy SDK (`@google/generative-ai`)

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Add Gemini as an AI provider

Gemini provider resources

​Tracing

​Setup

​Auto-instrumentation

​Manual instrumentation

​Gateway

​Log to a project

​Streaming

​Embeddings

​Streaming

​Structured outputs

​Function calling

​Multimodal content

​Reasoning models

​Context caching

​Error handling, attachments, and masking sensitive data

​What Braintrust traces

​Tracing resources

​Evals

​Native SDK

​Gateway

​Legacy SDK (@google/generative-ai)

​Auto-instrumentation

​Manual instrumentation

​What Braintrust traces

​Add Gemini as an AI provider

​Gemini provider resources

Tracing

Setup

Auto-instrumentation

Manual instrumentation

Gateway

Log to a project

Streaming

Embeddings

Streaming

Structured outputs

Function calling

Multimodal content

Reasoning models

Context caching

Error handling, attachments, and masking sensitive data

What Braintrust traces

Tracing resources

Evals

Native SDK

Gateway

Legacy SDK (`@google/generative-ai`)

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Add Gemini as an AI provider

Gemini provider resources