# zidane/providers/google

> The Google Gemini providers, on the Gemini API with an API key or on Vertex AI with Google Cloud credentials.

Import: `import { … } from 'zidane/providers/google'`. Source: [src/providers/google.ts](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts).

Use `google()` for the Gemini API (Google AI Studio). With no key passed, it reads `GEMINI_API_KEY`, then `GOOGLE_API_KEY`. Use `googleVertex()` for Vertex AI. It uses a Vertex API key (`GOOGLE_CLOUD_API_KEY`) when one is set. Otherwise it uses Google Cloud credentials (`GOOGLE_APPLICATION_CREDENTIALS`, or the gcloud Application Default Credentials) for `GOOGLE_CLOUD_PROJECT` in `GOOGLE_CLOUD_LOCATION`, which defaults to `global`. Both providers keep the Gemini thought signatures in the session and send them back to the route that issued them. Gemini 3 needs them for multi-step tool use. Without an API key, Vertex AI also takes a service-account key or the metadata server on Google Cloud. Files such as PDFs go to the model as file parts. `googleCompatible()` runs the same plumbing over another Gemini-wire backend, such as an extension's transport: the route sends the request zidane builds and returns the SSE response.

```ts
import { createAgent } from 'zidane'
import { google, googleVertex } from 'zidane/providers/google'

const agent = createAgent({ provider: google({ defaultModel: 'gemini-3.8-flash' }) })
await agent.run({ prompt: 'Summarize README.md in three bullets.' })

const vertex = createAgent({ provider: googleVertex({ project: 'my-project', location: 'us-central1' }) })
await vertex.run({ prompt: 'List the files in this directory.' })
```

## Functions

### `classifyGoogleError`

Function.

Classify a Gemini API / Vertex AI error.

```ts
function classifyGoogleError(err: unknown, label?: string): ClassifiedError | null
```

**Parameters**

- `err` (`unknown`): Error a Google provider threw.
- `label?` (`string`, default `'Gemini'`): Product a limit's message names; routes over other services (Antigravity) pass their own.

**Returns** `ClassifiedError | null`

Source: [src/providers/google.ts:155](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L155)

### `google`

Function.

Creates the Google Gemini provider on the Gemini API (Google AI Studio).
Authenticates with `apiKey`, else `GEMINI_API_KEY`, else `GOOGLE_API_KEY`.

```ts
function google(params?: GoogleParams): Provider
```

**Parameters**

- `params?` (`GoogleParams`): API key, default model, capabilities and extra headers.

**Returns** `Provider`

**Example**

```ts
import { createAgent } from 'zidane'
import { google } from 'zidane/providers/google'

const agent = createAgent({
  provider: google({ apiKey: process.env.GEMINI_API_KEY }),
})
await agent.run({ prompt: 'Say hello.' })
```

Source: [src/providers/google.ts:481](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L481)

### `googleCompatible`

Function.

Creates a provider over another Gemini-wire backend: an extension supplies
the transport (`send`, `parseChunk`) and model records; message
conversion, thought signatures (tagged with the route's scope, never
replayed elsewhere), tool names, thinking levels, SSE parsing, usage and
cost come from the same plumbing as [`google`](https://zidane.si/docs/reference/providers-google.md#google) and
[`googleVertex`](https://zidane.si/docs/reference/providers-google.md#googleVertex).

```ts
function googleCompatible(
  route: GoogleCompatibleRoute,
  params?: GoogleSharedParams,
): Provider
```

**Parameters**

- `route` (`GoogleCompatibleRoute`): The backend: name, transport and models.
- `params?` (`GoogleSharedParams`): Default model, capabilities and extra headers.

**Returns** `Provider`

**Example**

```ts
import { googleCompatible } from 'zidane/providers'

const provider = googleCompatible({
  name: 'my-gateway',
  isOAuth: false,
  send: (turn, fetch) => fetch(`https://gateway.example/v1beta/models/${turn.model.id}:streamGenerateContent?alt=sse`, {
    method: 'POST',
    headers: { 'content-type': 'application/json', 'authorization': `Bearer ${process.env.MY_GATEWAY_KEY}` },
    body: JSON.stringify(turn.body),
    signal: turn.signal,
  }),
  resolveModel: id => myModels[id],
}, { defaultModel: 'gemini-3.8-flash' })
```

Source: [src/providers/google.ts:452](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L452)

### `googleVertex`

Function.

Creates the Google Vertex AI provider. Authenticates with a pinned
`account`'s Google sign-in, else a Vertex API key (`apiKey` or
`GOOGLE_CLOUD_API_KEY`), else the active "Sign in with Google" grant, else
Google Cloud credentials for `project` in `location`. See
[`resolveVertexAuth`](https://zidane.si/docs/reference/providers-google.md#resolveVertexAuth).

```ts
function googleVertex(params?: GoogleVertexParams): Provider
```

**Parameters**

- `params?` (`GoogleVertexParams`): Credentials, project, location, default model, capabilities and extra headers.

**Returns** `Provider`

**Example**

```ts
import { createAgent } from 'zidane'
import { googleVertex } from 'zidane/providers/google'

// After `gcloud auth application-default login`:
const agent = createAgent({
  provider: googleVertex({ project: 'my-project' }),
})
await agent.run({ prompt: 'Say hello.' })
```

Source: [src/providers/google.ts:646](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L646)

### `resolveGoogleModel`

Function.

Model record for `modelId` on `route`: the registry's entry, else a
[`GOOGLE_EXTRA_MODELS`](https://zidane.si/docs/reference/providers-google.md#GOOGLE_EXTRA_MODELS) overlay, else the default model's shape under
the requested id. A catalog entry overlays whichever applies.

```ts
function resolveGoogleModel(
  route: GoogleRouteName,
  modelId: string,
  catalog?: ModelCatalog,
): GoogleWireModel
```

**Parameters**

- `route` (`GoogleRouteName`): Backend the request goes to.
- `modelId` (`string`): Requested model id.
- `catalog?` (`ModelCatalog`): Per-run catalog override.

**Returns** `GoogleWireModel`

Source: [src/providers/google.ts:106](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L106)

### `resolveVertexAuth`

Function.

Where a Vertex AI request goes and its credentials, read per turn so a
credential configured after the provider was built still applies. In
order: a pinned account's sign-in, a Vertex API key, the active "Sign in
with Google" grant, then Google Cloud credentials for the project (a
credentials file, gcloud's Application Default Credentials, the metadata
server), a fresh token minted per request.

```ts
function resolveVertexAuth(
  params?: GoogleVertexParams,
  callbacks?: StreamCallbacks,
  signal?: AbortSignal,
): Promise<VertexRequestAuth>
```

**Parameters**

- `params?` (`GoogleVertexParams`): Explicit settings; environment variables fill the rest.
- `callbacks?` (`StreamCallbacks`): Stream callbacks, for the OAuth refresh hook.
- `signal?` (`AbortSignal`): Aborts a token request.

**Returns** `Promise<VertexRequestAuth>`

Source: [src/providers/google.ts:601](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L601)

### `toGeminiContents`

Function.

Converts session messages to Gemini `contents`.

An assistant turn stays whole: Gemini signs only the FIRST function call
of a parallel step, so splitting the calls into separate model turns would
leave the others unsigned. Its results follow in call order, in one user
turn, with the synthetic placeholder for any the history lost.

```ts
function toGeminiContents(
  messages: SessionMessage[],
  model: GoogleWireModel,
  scope: GeminiSignatureScope,
  provider?: string,
): GeminiContent[]
```

**Parameters**

- `messages` (`SessionMessage[]`): Session messages, tool names already on the wire.
- `model` (`GoogleWireModel`): Target model.
- `scope` (`GeminiSignatureScope`): Signature scope of the target.
- `provider?` (`string`, default `scope`): Provider named in unsupported-media errors. Defaults to `scope`.

**Returns** `GeminiContent[]`

Source: [src/providers/gemini/request.ts:202](https://github.com/Tahul/zidane/blob/main/src/providers/gemini/request.ts#L202)

## Constants

### `GOOGLE_DEFAULT_MODEL`

Constant.

Model used when a request names none. Served on free-tier Gemini API keys.

```ts
const GOOGLE_DEFAULT_MODEL = 'gemini-3.8-flash'
```

Source: [src/providers/google.ts:58](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L58)

### `GOOGLE_EXTRA_MODELS`

Constant.

Models pi-ai's registry hasn't bundled yet, served on both routes. A
pi-ai release that bundles one supersedes its entry (bundled metadata
always wins), so delete the entry then.

```ts
const GOOGLE_EXTRA_MODELS: readonly GoogleExtraModel[]
```

Source: [src/providers/google.ts:81](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L81)

## Interfaces

### `GeminiContent`

Interface.

One turn of the conversation.

```ts
interface GeminiContent
```

**Properties**

- `parts` (`GeminiPart[]`): What was said.
- `role` (`'user' | 'model'`): Who spoke.

Source: [src/providers/gemini/types.ts:54](https://github.com/Tahul/zidane/blob/main/src/providers/gemini/types.ts#L54)

### `GeminiFunctionDeclaration`

Interface.

A tool the model may call.

```ts
interface GeminiFunctionDeclaration
```

**Properties**

- `description` (`string`): What it does.
- `name` (`string`): Function name.
- `parameters?` (`unknown`): OpenAPI-subset schema of the arguments (the legacy field some backends translate).
- `parametersJsonSchema?` (`unknown`): Full JSON Schema of the arguments.

Source: [src/providers/gemini/types.ts:62](https://github.com/Tahul/zidane/blob/main/src/providers/gemini/types.ts#L62)

### `GeminiGenerationConfig`

Interface.

Generation settings.

```ts
interface GeminiGenerationConfig
```

**Properties**

- `maxOutputTokens?` (`number`): Output ceiling in tokens.
- `temperature?` (`number`): Sampling temperature.
- `thinkingConfig?` (`GeminiThinkingConfig`): Thinking settings.

Source: [src/providers/gemini/types.ts:84](https://github.com/Tahul/zidane/blob/main/src/providers/gemini/types.ts#L84)

### `GeminiPart`

Interface.

One part of a turn.

```ts
interface GeminiPart
```

**Properties**

- `functionCall?` (`GeminiFunctionCall`): A function call.
- `functionResponse?` (`GeminiFunctionResponse`): A function result.
- `inlineData?` (`GeminiBlob`): Inline media or file.
- `text?` (`string`): Text, or a thought summary when `thought` is set.
- `thought?` (`boolean`): Marks `text` as thought content.
- `thoughtSignature?` (`string`): Opaque signature of the model's reasoning, replayed as received.

Source: [src/providers/gemini/types.ts:38](https://github.com/Tahul/zidane/blob/main/src/providers/gemini/types.ts#L38)

### `GeminiRequest`

Interface.

A `GenerateContentRequest` body.

```ts
interface GeminiRequest
```

**Properties**

- `contents` (`GeminiContent[]`): The conversation.
- `generationConfig?` (`GeminiGenerationConfig`): Generation settings.
- `systemInstruction?` (`{ parts: { text: string }[]; role: 'user' }`): The system prompt.
- `toolConfig?` (`GeminiToolConfig`): Function-calling mode.
- `tools?` (`{ functionDeclarations: GeminiFunctionDeclaration[] }[]`): Function declarations.

Source: [src/providers/gemini/types.ts:100](https://github.com/Tahul/zidane/blob/main/src/providers/gemini/types.ts#L100)

### `GeminiResponseChunk`

Interface.

One streamed `GenerateContentResponse`.

```ts
interface GeminiResponseChunk
```

**Properties**

- `candidates?` (`{ content?: { parts?: GeminiPart[]; role?: string }; finishReason?: string }[]`): Candidates; zidane reads the first.
- `responseId?` (`string`): Response id.
- `usageMetadata?` (`GeminiUsageMetadata`): Token counts so far.

Source: [src/providers/gemini/types.ts:128](https://github.com/Tahul/zidane/blob/main/src/providers/gemini/types.ts#L128)

### `GeminiThinkingConfig`

Interface.

Thinking settings.

```ts
interface GeminiThinkingConfig
```

**Properties**

- `includeThoughts?` (`boolean`): Stream thought summaries.
- `thinkingBudget?` (`number`): Token budget (Gemini 2.5); `0` turns thinking off, `-1` lets the model pick.
- `thinkingLevel?` (`'MINIMAL' | 'LOW' | 'MEDIUM' | 'HIGH'`): Discrete level (Gemini 3+).

Source: [src/providers/gemini/types.ts:74](https://github.com/Tahul/zidane/blob/main/src/providers/gemini/types.ts#L74)

### `GeminiTool`

Interface.

A tool as `formatTools` hands it to the request: name, description, JSON Schema.

```ts
interface GeminiTool
```

**Properties**

- `description` (`string`): What it does.
- `name` (`string`): Function name on the wire.
- `parameters` (`Record<string, unknown>`): JSON Schema of its arguments.

Source: [src/providers/gemini/request.ts:20](https://github.com/Tahul/zidane/blob/main/src/providers/gemini/request.ts#L20)

### `GeminiToolConfig`

Interface.

Function-calling mode.

```ts
interface GeminiToolConfig
```

**Properties**

- `functionCallingConfig` (`{ allowedFunctionNames?: string[]; mode: 'AUTO' | 'ANY' | 'NONE' | 'VALIDATED' }`): `AUTO`, `ANY` (must call one) or `NONE`, optionally limited to some functions.

Source: [src/providers/gemini/types.ts:94](https://github.com/Tahul/zidane/blob/main/src/providers/gemini/types.ts#L94)

### `GoogleCompatibleRoute`

Interface.

A Gemini-wire backend for [`googleCompatible`](https://zidane.si/docs/reference/providers-google.md#googleCompatible): where requests go and
how they authenticate (`send`), how its stream events read
(`parseChunk`) and which models it serves (`resolveModel`). Message
conversion, thought-signature bookkeeping, tool names, thinking levels,
SSE parsing, usage and cost stay in the shared plumbing.

```ts
interface GoogleCompatibleRoute
```

**Properties**

- `classifyError?` (`(err: unknown) => ClassifiedError | null`): Error classification. Defaults to [`classifyGoogleError`](https://zidane.si/docs/reference/providers-google.md#classifyGoogleError).
- `isOAuth` (`boolean`): Whether the provider runs on an OAuth credential.
- `name` (`string`): Provider name (`Provider.name`, error copy) and the default signature
  scope. Must not be a built-in provider name (`google`,
  `google-vertex`, `anthropic`, `openai`).
- `parseChunk?` (`(payload: unknown) => GeminiResponseChunk`): One SSE event's JSON to a `GenerateContentResponse`, for a backend that
  wraps it (Cloud Code Assist's `{ response }`). Throw for an in-stream
  error. Defaults to the event as is, an `{ error }` event thrown as a
  Google error.
- `resolveModel` (`(modelId: string, catalog?: ModelCatalog) => GoogleWireModel`): Model record for a requested model id. Its `cost` rates price each
  turn: zero rates report no cost (quota-backed access).
- `send` (`(request: GoogleTurnRequest, fetch: typeof fetch) => Promise<Response>`): Sends one turn and returns the streaming response
  (`streamGenerateContent?alt=sse` or the backend's equivalent). Send it
  with `fetch`: it is the provider's, carrying the `http.request` /
  `http.response` interceptors. A non-2xx response is read as a Google
  error; throw instead to report the backend's own (with a numeric
  `status` so it classifies by HTTP status).
- `signatureScope?` (`(modelId: string) => string`): Signature scope of a model: the tag its thought signatures carry, and
  the only scope they replay to. Defaults to `name`, right when every model
  behind the backend accepts the others' signatures (Gemini does). A
  backend fronting several model families returns one scope per family,
  so switching families mid-session sends earlier reasoning unsigned.

Source: [src/providers/google.ts:217](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L217)

### `GoogleExtraModel`

Interface.

A Google model pi-ai's registry hasn't bundled yet: a bundled `template` with the same thinking shape, under its own id.

```ts
interface GoogleExtraModel
```

**Properties**

- `contextWindow` (`number`): Context window in tokens.
- `id` (`string`): Model id sent to the API.
- `maxTokens` (`number`): Largest output in tokens.
- `name` (`string`): Display name.
- `rates` (`() => Required<ModelCostRates>`): A function, so a dated price change applies to long-running hosts.
- `template` (`string`): A bundled model with the same thinking levels and budgets.

Source: [src/providers/google.ts:61](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L61)

### `GoogleParams`

Interface.

Options for [`google`](https://zidane.si/docs/reference/providers-google.md#google).

```ts
interface GoogleParams extends GoogleSharedParams
```

**Properties**

- `apiKey?` (`string`): Gemini API key. Defaults to `GEMINI_API_KEY`, then `GOOGLE_API_KEY`.
- `capabilities?` (`ProviderCapabilities`, from `GoogleSharedParams`): Provider capability flags. Gemini takes images and files (PDFs and
  others) in prompts and in tool results; audio and video are refused.
- `defaultModel?` (`string`, from `GoogleSharedParams`, default `'gemini-3.8-flash'`): Model used when a request does not set one.
- `extraHeaders?` (`Record<string, string>`, from `GoogleSharedParams`): Extra HTTP headers sent on every request.

Source: [src/providers/google.ts:459](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L459)

### `GoogleSharedParams`

Interface.

Settings shared by the Google providers.

```ts
interface GoogleSharedParams
```

**Properties**

- `capabilities?` (`ProviderCapabilities`): Provider capability flags. Gemini takes images and files (PDFs and
  others) in prompts and in tool results; audio and video are refused.
- `defaultModel?` (`string`, default `'gemini-3.8-flash'`): Model used when a request does not set one.
- `extraHeaders?` (`Record<string, string>`): Extra HTTP headers sent on every request.

Source: [src/providers/google.ts:276](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L276)

### `GoogleTurnRequest`

Interface.

One turn's request, handed to a [`GoogleCompatibleRoute`](https://zidane.si/docs/reference/providers-google.md#GoogleCompatibleRoute)'s `send`.

```ts
interface GoogleTurnRequest
```

**Properties**

- `body` (`GeminiRequest`): The standard `GenerateContentRequest`: contents with this route's
  signatures, tools, forced tool choice, and `generationConfig` with the
  output ceiling and the thinking config Gemini models take. A route may
  edit it, or wrap it in its backend's envelope.
- `callbacks` (`StreamCallbacks`): Stream callbacks, for OAuth refresh hooks.
- `headers` (`Record<string, string>`): The provider's extra headers (`extraHeaders`), to send on top of the route's.
- `maxTokens?` (`number`): Output ceiling as requested (the body's is already resolved).
- `model` (`GoogleWireModel`): The model record the route resolved.
- `signal?` (`AbortSignal`): Aborts the request.
- `thinking?` (`'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'adaptive'`): Thinking level as requested, for a backend that maps it its own way.

Source: [src/providers/google.ts:188](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L188)

### `GoogleVertexParams`

Interface.

Options for [`googleVertex`](https://zidane.si/docs/reference/providers-google.md#googleVertex).

```ts
interface GoogleVertexParams extends GoogleSharedParams
```

**Properties**

- `account?` (`string`): Run on one stored "Sign in with Google" account (its stable id) rather
  than the active one. See `OAuthParams.account`.
- `apiKey?` (`string`): Vertex AI API key (express mode). Defaults to `GOOGLE_CLOUD_API_KEY`.
  Without one, requests authenticate with Google Cloud credentials.
- `capabilities?` (`ProviderCapabilities`, from `GoogleSharedParams`): Provider capability flags. Gemini takes images and files (PDFs and
  others) in prompts and in tool results; audio and video are refused.
- `credentialsFile?` (`string`): Service-account or authorized-user credentials file. Defaults to
  `GOOGLE_APPLICATION_CREDENTIALS`, then gcloud's Application Default
  Credentials (`gcloud auth application-default login`), then the
  metadata server on Google Cloud.
- `defaultModel?` (`string`, from `GoogleSharedParams`, default `'gemini-3.8-flash'`): Model used when a request does not set one.
- `extraHeaders?` (`Record<string, string>`, from `GoogleSharedParams`): Extra HTTP headers sent on every request.
- `location?` (`string`): Vertex AI location. Defaults to `GOOGLE_CLOUD_LOCATION`, then `global`.
- `project?` (`string`): Google Cloud project. Defaults to `GOOGLE_CLOUD_PROJECT`, then `GCLOUD_PROJECT`.

Source: [src/providers/google.ts:500](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L500)

### `GoogleWireModel`

Interface.

A model on a Gemini wire: what the request builder and the cost need. The
Google routes read it from pi-ai's model registry; a
`googleCompatible` backend builds its own.

```ts
interface GoogleWireModel
```

**Properties**

- `baseUrl?` (`string`): API base URL (the Gemini API's, or Vertex's `{location}` template).
- `contextWindow` (`number`): Context window in tokens.
- `cost` (`GeminiModelCost`): Prices per million tokens; zero rates report no cost.
- `id` (`string`): Model id sent on the wire.
- `input` (`readonly string[]`): Input kinds; a model without `image` gets a text marker for each image.
- `maxTokens` (`number`): Output ceiling in tokens.
- `name` (`string`): Display name.
- `provider` (`string`): Provider that serves it.
- `reasoning` (`boolean`): Whether it thinks.
- `thinkingLevelMap?` (`Partial<Record<string, string | null>>`): zidane level → Gemini level, `null` where the model lacks one. Levels
  absent from the map pass through (`xhigh` and `max` only when mapped).

Source: [src/providers/gemini/types.ts:160](https://github.com/Tahul/zidane/blob/main/src/providers/gemini/types.ts#L160)

### `VertexRequestAuth`

Interface.

Where a Vertex AI request goes and how it authenticates.

```ts
interface VertexRequestAuth
```

**Properties**

- `headers` (`Record<string, string>`): Auth headers: `x-goog-api-key`, or a bearer token and the billed project.
- `url` (`(modelId: string) => string`): The `streamGenerateContent` URL of a model.

Source: [src/providers/google.ts:525](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L525)

## Types

### `GoogleRouteName`

Type.

Zidane provider (and signature route) names of the two Google backends.

```ts
type GoogleRouteName = 'google' | 'google-vertex'
```

Source: [src/providers/google.ts:55](https://github.com/Tahul/zidane/blob/main/src/providers/google.ts#L55)