# Google GenAI (Gemini)

Install Brizz alongside Google's @google/genai SDK — Gemini on Vertex AI or the Gemini Developer API.

Quickstart for Gemini via [`@google/genai`](https://www.npmjs.com/package/@google/genai) — Google's unified SDK for both **Vertex AI** and the **Gemini Developer API**. For the full TypeScript SDK reference, see the [TypeScript SDK guide](/docs/sdks/typescript.md).

## Install

:::tabs
:::tab[npm]
```bash
npm install @brizz/sdk @google/genai @traceloop/instrumentation-google-generativeai
```
:::tab[yarn]
```bash
yarn add @brizz/sdk @google/genai @traceloop/instrumentation-google-generativeai
```
:::tab[pnpm]
```bash
pnpm add @brizz/sdk @google/genai @traceloop/instrumentation-google-generativeai
```
:::

`@traceloop/instrumentation-google-generativeai` is an optional peer dependency of `@brizz/sdk` — it's only needed when you use Gemini.

## Initialize

`@google/genai` is ESM-only, and a Node ES module namespace is read-only — the SDK can't patch the module in place (and `instrumentModules` doesn't apply). Instead, `instrumentGoogleGenAI` hands back an instrumented `GoogleGenAI` class; **build your client from that class** and every call is traced.

```typescript
import { Brizz } from '@brizz/sdk';
import { instrumentGoogleGenAI } from '@brizz/sdk/google-genai';
import * as genai from '@google/genai';

Brizz.initialize({
  apiKey: 'your-brizzai-api-key',
  appName: 'my-app',
});

// Call after Brizz.initialize() so the wrapper binds to the live tracer.
const GoogleGenAI = instrumentGoogleGenAI(genai);

// Vertex AI (uses Application Default Credentials):
const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: 'us-central1',
});

// …or the Gemini Developer API:
// const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
```

## Usage

`generateContent` and `generateContentStream` are captured automatically — messages, tool calls, token usage, and cost — with no per-call instrumentation. Wrap your conversation in `startSession` so calls group into one session:

```typescript
import { startSession, setUser } from '@brizz/sdk';

await startSession('conversation-123', async () => {
  setUser({ id: 'user-42', email: 'dana@example.com' });

  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'What can you help me with?',
  });
  console.log(response.text);
});
```

## Complete example

Copy, set `BRIZZ_API_KEY` + `GOOGLE_CLOUD_PROJECT`, and run with `tsx chat.ts`.

```typescript
// chat.ts
import { Brizz, startSession, setUser, emitEvent } from '@brizz/sdk';
import { instrumentGoogleGenAI } from '@brizz/sdk/google-genai';
import * as genai from '@google/genai';

Brizz.initialize({
  apiKey: process.env.BRIZZ_API_KEY!,
  appName: 'my-app',
});

const GoogleGenAI = instrumentGoogleGenAI(genai);
const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT!,
  location: 'us-central1',
});

await startSession('conversation-123', async () => {
  setUser({ id: 'user-42' });

  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'Best time of year to visit Tel Aviv?',
  });
  console.log(response.text);

  // Tool calling needs no extra wiring: declare your tools in config.tools, and when
  // you execute a functionCall and send the functionResponse turn back, Brizz renders
  // the tool call and its result in the conversation.

  // User feedback — map "feedback.positive" / "feedback.negative" to system
  // events in Org Settings -> Event so it powers filters and the Overview chart.
  emitEvent(
    'feedback.positive',
    { category: 'helpfulness' },
    { comment: 'Exactly what I needed!', context: 'travel-assistant' },
  );
});
```

The conversation renders in Brizz with the user and assistant messages, model badge, token counts, and cost. With a tool round-trip implemented, it renders as user → tool call → tool result → assistant.

**Gotchas**

- Construct your client from the class `instrumentGoogleGenAI` returns — clients built from the original `genai.GoogleGenAI` produce **no spans**.
- Call `instrumentGoogleGenAI` **after** `Brizz.initialize()`.
- On Vertex AI, an expired `gcloud auth application-default login` surfaces as a **503 "Reauthentication is needed"**, not an auth error.
- Both `@google/genai` v1 and v2 are supported.

## See also

- [Node.js / TypeScript SDK](/docs/sdks/typescript.md) — full SDK reference.
- [Sessions](/docs/instrument/sessions.md) — session capture patterns.
- [Record feedback](/docs/instrument/record-feedback.md) — capture end-user reactions on a conversation.