Google

You can use Google models through AI Gateway (recommended) or connect directly to the Google APIs with @ai-sdk/google.

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-5.5',
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

console.log(text);

Using AI Gateway

The AI SDK uses AI Gateway by default for model strings. AI Gateway provides access to Google and other providers through a single API key, with usage and cost tracking. Install the ai package:

pnpm add ai

npm install ai

yarn add ai

bun add ai

Set an AI Gateway API key in your environment:

export AI_GATEWAY_API_KEY=your_api_key_here

Vercel deployments can also use OIDC authentication. See the AI Gateway provider documentation for configuration and the model catalog for available Google models.

Google model options can be passed through providerOptions.google when using AI Gateway. Support depends on the model and the provider serving the request; see Gateway provider options.

Using @ai-sdk/google

For direct access to the Google APIs, install ai and @ai-sdk/google:

pnpm add ai @ai-sdk/google

npm install ai @ai-sdk/google

yarn add ai @ai-sdk/google

bun add ai @ai-sdk/google

Set your Google API key in the GOOGLE_GENERATIVE_AI_API_KEY environment variable:

export GOOGLE_GENERATIVE_AI_API_KEY=your_api_key_here

AI Gateway does not expose every API in @ai-sdk/google. Use the direct provider for Google-specific APIs such as google.interactions(...), or when you need to customize the Google connection with createGoogle.

Provider Instance

You can import the default provider instance google from @ai-sdk/google:

import { google } from '@ai-sdk/google';

If you need a customized setup, you can import createGoogle from @ai-sdk/google and create a provider instance with your settings:

import { createGoogle } from '@ai-sdk/google';

const google = createGoogle({
  // custom settings
});

You can use the following optional settings to customize the Google provider instance:

• batchResultDownloads object

  Settings for downloading file-based JSON Lines batch results.

  • maxLineBytes number

    Maximum UTF-8 bytes per row, excluding the LF delimiter. Defaults to 64 MiB (67,108,864 bytes). Must be a positive safe integer. Oversized rows throw a DownloadError and cancel the download.

• baseURL string

  Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is https://generativelanguage.googleapis.com/v1beta.

• apiKey string

  API key that is being sent using the x-goog-api-key header. It defaults to the GOOGLE_GENERATIVE_AI_API_KEY environment variable.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation. Defaults to the global fetch function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

• generateId () => string

  Optional function to generate unique IDs for each request. Defaults to the SDK's built-in ID generator.

• name string

  Custom provider name. Defaults to 'google.generative-ai'.

Language Models

You can create models that call the Google Generative AI API using the provider instance. The first argument is the model id, e.g. gemini-4-argon. The models support tool calls and some have multi-modal capabilities.

const model = google('gemini-4-argon');

You can use Google language models to generate text with the generateText function:

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const { text } = await generateText({
  model: google('gemini-4-argon'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

Google language models can also be used in the streamText function and support structured data generation with Output (see AI SDK Core).

Google also supports some model specific settings that are not part of the standard call settings. You can pass them as an options argument:

import { google, type GoogleLanguageModelOptions } from '@ai-sdk/google';

const model = google('gemini-4-argon');

await generateText({
  model,
  providerOptions: {
    google: {
      safetySettings: [
        {
          category: 'HARM_CATEGORY_UNSPECIFIED',
          threshold: 'BLOCK_LOW_AND_ABOVE',
        },
      ],
    } satisfies GoogleLanguageModelOptions,
  },
});

The following optional provider options are available for Google models:

• cachedContent string

  Optional. The name of the cached content used as context to serve the prediction. Format: cachedContents/{cachedContent}

• structuredOutputs boolean

  Optional. Enable structured output. Default is true.

  You can disable structured outputs when a schema is not supported or exceeds Google's schema complexity limits. The model will still be instructed to return JSON, but the schema will not be sent to Google.

  See Troubleshooting: Schema Limitations for more details.

• safetySettings Array<{ category: string; threshold: string }>

  Optional. Safety settings for the model.

  • category string

    The category of the safety setting. Can be one of the following:

    • HARM_CATEGORY_UNSPECIFIED
    • HARM_CATEGORY_HATE_SPEECH
    • HARM_CATEGORY_DANGEROUS_CONTENT
    • HARM_CATEGORY_HARASSMENT
    • HARM_CATEGORY_SEXUALLY_EXPLICIT
    • HARM_CATEGORY_CIVIC_INTEGRITY

  • threshold string

    The threshold of the safety setting. Can be one of the following:

    • HARM_BLOCK_THRESHOLD_UNSPECIFIED
    • BLOCK_LOW_AND_ABOVE
    • BLOCK_MEDIUM_AND_ABOVE
    • BLOCK_ONLY_HIGH
    • BLOCK_NONE
    • OFF

• responseModalities string[] The modalities to use for the response. Valid values are TEXT, IMAGE, and AUDIO, but support is model-dependent. When not defined or empty, the model defaults to returning only text.

• thinkingConfig { thinkingLevel?: 'minimal' | 'low' | 'medium' | 'high'; thinkingBudget?: number; includeThoughts?: boolean }

  Optional. Configuration for the model's thinking process. Only supported by specific Google models.

  • thinkingLevel 'minimal' | 'low' | 'medium' | 'high'

    Optional. Controls the thinking depth for Gemini 3 and later models. Gemini 3.1 Pro supports 'low', 'medium', and 'high', Gemini 3 Pro supports 'low' and 'high', while Gemini 3 Flash supports all four levels: 'minimal', 'low', 'medium', and 'high'.

  • thinkingBudget number

    Optional. Gives the model guidance on the number of thinking tokens it can use when generating a response. Setting it to 0 disables thinking, if the model supports it. For more information about the possible value ranges for each model see Google thinking documentation.

    Note

    This option is for Gemini 2.5 models. Gemini 3 and later models should use thinkingLevel instead.

  • includeThoughts boolean

    Optional. If set to true, thought summaries are returned, which are synthesized versions of the model's raw thoughts and offer insights into the model's internal reasoning process.

• imageConfig { aspectRatio?: string, imageSize?: string }

  Optional. Configuration for the models image generation. Only supported by specific Google models.

  • aspectRatio string

    Model defaults to generate 1:1 squares, or to matching the output image size to that of your input image. Can be one of the following:

    • 1:1
    • 2:3
    • 3:2
    • 3:4
    • 4:3
    • 4:5
    • 5:4
    • 9:16
    • 16:9
    • 21:9

  • imageSize string

    Controls the output image resolution. Defaults to 1K. Can be one of the following:

    • 1K
    • 2K
    • 4K

• audioTimestamp boolean

  Optional. Enables timestamp understanding for audio-only files. See Google Cloud audio understanding documentation.

• mediaResolution string

  Optional. If specified, the media resolution specified will be used. Can be one of the following:

  • MEDIA_RESOLUTION_UNSPECIFIED
  • MEDIA_RESOLUTION_LOW
  • MEDIA_RESOLUTION_MEDIUM
  • MEDIA_RESOLUTION_HIGH

  See Google API MediaResolution documentation.

• labels Record<string, string>

  Optional. Defines labels used in billing reports. Available on Vertex AI only. See Google Cloud labels documentation.

• serviceTier 'standard' | 'flex' | 'priority'

  Optional. The service tier to use for the request. Set to 'flex' for 50% cheaper processing at the cost of increased latency. Set to 'priority' for ultra-low latency at a 75-100% price premium over 'standard'.

  Because Priority can be gracefully downgraded to Standard under load, the tier the request actually ran on is surfaced on result.providerMetadata.google.serviceTier. See Priority inference and Flex inference.

• continuationToken string

  Optional. Resumes a response that stopped because it used up its maxOutputTokens budget (Gemini 4 long decode). Send it with the original request and a higher maxOutputTokens. See Long decode.

• threshold string

  Optional. Standalone threshold setting that can be used independently of safetySettings. Uses the same values as the safetySettings threshold.

Thinking

The Gemini 2.5 and Gemini 3-and-later series models use an internal "thinking process" that significantly improves their reasoning and multi-step planning abilities, making them highly effective for complex tasks such as coding, advanced mathematics, and data analysis. For more information see Google thinking documentation.

Gemini 3 and Later Models

For Gemini 3 and later models, use the thinkingLevel parameter to control the depth of reasoning:

import { google, GoogleLanguageModelOptions } from '@ai-sdk/google';
import { generateText } from 'ai';

const model = google('gemini-4-argon');

const { text, reasoning } = await generateText({
  model: model,
  prompt: 'What is the sum of the first 10 prime numbers?',
  providerOptions: {
    google: {
      thinkingConfig: {
        thinkingLevel: 'high',
        includeThoughts: true,
      },
    } satisfies GoogleLanguageModelOptions,
  },
});

console.log(text);

console.log(reasoning); // Reasoning summary

Gemini 2.5 Models

For Gemini 2.5 models, use the thinkingBudget parameter to control the number of thinking tokens:

import { google, GoogleLanguageModelOptions } from '@ai-sdk/google';
import { generateText } from 'ai';

const model = google('gemini-2.5-flash');

const { text, reasoning } = await generateText({
  model: model,
  prompt: 'What is the sum of the first 10 prime numbers?',
  providerOptions: {
    google: {
      thinkingConfig: {
        thinkingBudget: 8192,
        includeThoughts: true,
      },
    } satisfies GoogleLanguageModelOptions,
  },
});

console.log(text);

console.log(reasoning); // Reasoning summary

Long decode

Gemini 4 models such as gemini-4-argon can keep thinking and writing past a single request's limits, up to the shared 1M token context window (input, thinking, and output tokens together). Use it for hard math, science, proofs, and long coding or agentic tasks.

• A single request generates at most 32,768 tokens without streaming and 65,536 tokens with streaming (streamText). Thinking tokens count towards this cap.
• maxOutputTokens is a cumulative budget across requests, not a target length. When a request reaches the per-request cap while budget remains, the provider automatically sends the same request again with a continuation token and combines the results into one response. Set maxOutputTokens above the per-request cap (up to 1M minus the input tokens) to enable this. If you do not set it, the call ends after one request.
• A lower maxOutputTokens does not make the model think less, it ends the response early (possibly before any answer) and you are still charged for the tokens. Use thinkingConfig.thinkingLevel to control how much the model thinks. thinkingBudget is not supported by these models.
• Complex requests can run for several minutes. Make sure your HTTP client allows read timeouts of at least 15 to 20 minutes.

Grounding across requests. When a response is continued automatically, providerMetadata.google.groundingMetadataPerRequest contains the grounding metadata from each request, in order. An entry is null if that request did not return grounding metadata. This preserves earlier Search results even if the final request returns none, and keeps citation indices scoped to their original request. The existing groundingMetadata field keeps its current behavior; use the per-request array when inspecting a continued response.

Usage across requests. Each continued request re-sends the prompt plus all output so far as input, so its prompt token count includes everything generated before it. usage is the sum of all requests, which matches what Google bills (re-sent tokens are billed at a discount through implicit caching). Do not use the summed input tokens for context window checks or compaction: they can be several times larger than the real context. When a response spanned more than one request, providerMetadata.google.initialPromptTokenCount holds the prompt token count of the first request (the google-genai SDKs expose the same value as initial_prompt_token_count):

const result = await generateText({
  model: google('gemini-4-argon'),
  prompt,
  maxOutputTokens: 500_000,
});

// Billing: summed across all requests
console.log(result.usage.inputTokens.total);

// Context window: the first request's prompt plus the generated output
const promptTokens =
  result.finalStep.providerMetadata?.google?.initialPromptTokenCount ??
  result.usage.inputTokens.total;
const contextTokens = promptTokens + (result.usage.outputTokens.total ?? 0);

Resuming after the budget is used up. When the cumulative generated tokens reach maxOutputTokens, the finish reason is length and the provider returns a continuation token on result.providerMetadata.google.continuationToken. To continue, send the original request unchanged (same prompt, tools, and settings; do not append the partial output as a message) together with the token as providerOptions.google.continuationToken and a higher maxOutputTokens. Resending with the same maxOutputTokens fails because the budget is used up. Each response contains only the newly generated content.

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const prompt = 'Prove that sqrt(2) is irrational, in detail.';

const result = await generateText({
  model: google('gemini-4-argon'),
  prompt,
  maxOutputTokens: 128_000,
});

const continuationToken =
  result.finalStep.providerMetadata?.google?.continuationToken;

if (result.finishReason === 'length' && typeof continuationToken === 'string') {
  // The budget was used up. Raise it to keep going.
  const continued = await generateText({
    model: google('gemini-4-argon'),
    prompt,
    maxOutputTokens: 256_000,
    providerOptions: { google: { continuationToken } },
  });

  console.log(result.text + continued.text);
}

Things to keep in mind:

• Dropped streams. Streamed parts are forwarded as they arrive and are not buffered between the server's checkpoints, so a stream that drops mid-request is not resumed automatically. Retry the request from the start.
• Provider metadata is per call. If you store the conversation history, combine the content of all calls into one model message only after the final call finishes. Keep thought signatures unchanged, including the ones on empty trailing text parts.
• Zero Data Retention. Continuation works with store: false because the state travels encrypted inside the token.

Long decode with the Interactions API

With the Interactions API, long decode requires background: true. The server runs every request itself, so no client-side continuation is needed, and usage covers all requests. Set an explicit maxOutputTokens above 65,536 (without it, you get a single 64K request) and keep store enabled (the default). The provider polls the interaction (or streams it, reconnecting when the connection drops) until it finishes.

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google.interactions('gemini-4-argon'),
  prompt: 'Prove that sqrt(2) is irrational, in detail.',
  maxOutputTokens: 500_000,
  providerOptions: {
    google: {
      background: true,
      pollingTimeoutMs: 60 * 60 * 1000, // default: 30 minutes
    },
  },
});

Without background: true, an interaction generates at most 65,536 tokens. Requests with a higher maxOutputTokens are rejected by the API, and an interaction that reaches the cap finishes with length. Long decode is not available with the Vertex AI Interactions API.

File Inputs

The Google provider supports file inputs, e.g. PDF files.

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google('gemini-4-argon'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'What is an embedding model according to this document?',
        },
        {
          type: 'file',
          data: fs.readFileSync('./data/ai.pdf'),
          mediaType: 'application/pdf',
        },
      ],
    },
  ],
});

You can also use YouTube URLs directly:

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google('gemini-4-argon'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Summarize this video',
        },
        {
          type: 'file',
          data: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
          mediaType: 'video/mp4',
        },
      ],
    },
  ],
});

See File Parts for details on how to use files in prompts.

Cached Content

Google supports both explicit and implicit caching to help reduce costs on repetitive content.

Implicit Caching

Gemini models automatically provide cache cost savings without needing to create an explicit cache. When you send requests that share common prefixes with previous requests, you can receive discounted pricing on cached input tokens.

To maximize cache hits with implicit caching:

• Keep content at the beginning of requests consistent
• Add variable content (like user questions) at the end of prompts
• Ensure requests meet minimum token requirements:
  • Gemini 3 series: 4096 tokens minimum
  • Gemini 2.5 series: 2048 tokens minimum

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

// Structure prompts with consistent content at the beginning
const baseContext =
  'You are a cooking assistant with expertise in Italian cuisine. Here are 1000 lasagna recipes for reference...';

const { text: veggieLasagna } = await generateText({
  model: google('gemini-4-argon'),
  prompt: `${baseContext}\n\nWrite a vegetarian lasagna recipe for 4 people.`,
});

// Second request with same prefix - eligible for cache hit
const { text: meatLasagna, providerMetadata } = await generateText({
  model: google('gemini-4-argon'),
  prompt: `${baseContext}\n\nWrite a meat lasagna recipe for 12 people.`,
});

// Check cached token count in usage metadata
console.log('Cached tokens:', providerMetadata.google);
// e.g.
// {
//   groundingMetadata: null,
//   safetyRatings: null,
//   usageMetadata: {
//     cachedContentTokenCount: 5027,
//     thoughtsTokenCount: 702,
//     promptTokenCount: 5152,
//     candidatesTokenCount: 710,
//     totalTokenCount: 6564
//   }
// }

Explicit Caching

For guaranteed cost savings, you can still use explicit caching with Gemini 2.5 and 3 series models. Gemini 4 Argon supports implicit caching only, so this example uses gemini-3.8-flash. See the models page to check if caching is supported for the used model:

import { google, type GoogleLanguageModelOptions } from '@ai-sdk/google';
import { GoogleGenAI } from '@google/genai';
import { generateText } from 'ai';

const ai = new GoogleGenAI({
  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY,
});

const model = 'gemini-3.8-flash';

// Create a cache with the content you want to reuse
const cache = await ai.caches.create({
  model,
  config: {
    contents: [
      {
        role: 'user',
        parts: [{ text: '1000 Lasagna Recipes...' }],
      },
    ],
    ttl: '300s', // Cache expires after 5 minutes
  },
});

const { text: veggieLasagnaRecipe } = await generateText({
  model: google(model),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
  providerOptions: {
    google: {
      cachedContent: cache.name,
    } satisfies GoogleLanguageModelOptions,
  },
});

const { text: meatLasagnaRecipe } = await generateText({
  model: google(model),
  prompt: 'Write a meat lasagna recipe for 12 people.',
  providerOptions: {
    google: {
      cachedContent: cache.name,
    } satisfies GoogleLanguageModelOptions,
  },
});

Code Execution

With Code Execution, certain models can generate and execute Python code to perform calculations, solve problems, or provide more accurate information.

You can enable code execution by adding the code_execution tool to your request.

import { google } from '@ai-sdk/google';
import { googleTools } from '@ai-sdk/google/internal';
import { generateText } from 'ai';

const { text, toolCalls, toolResults } = await generateText({
  model: google('gemini-4-argon'),
  tools: { code_execution: google.tools.codeExecution({}) },
  prompt: 'Use python to calculate the 20th fibonacci number.',
});

The response will contain the tool calls and results from the code execution.

Google Search

With Google Search grounding, the model has access to the latest information using Google Search.

import { google } from '@ai-sdk/google';
import { GoogleProviderMetadata } from '@ai-sdk/google';
import { generateText } from 'ai';

const { text, sources, providerMetadata } = await generateText({
  model: google('gemini-4-argon'),
  tools: {
    google_search: google.tools.googleSearch({}),
  },
  prompt:
    'List the top 5 San Francisco news from the past week.' +
    'You must include the date of each article.',
});

// access the grounding metadata. Casting to the provider metadata type
// is optional but provides autocomplete and type safety.
const metadata = providerMetadata?.google as GoogleProviderMetadata | undefined;
const groundingMetadata = metadata?.groundingMetadata;
const safetyRatings = metadata?.safetyRatings;

The googleSearch tool accepts the following optional configuration options:

• searchTypes object

  Enables specific search types. Both can be combined.

  • webSearch: Enable web search grounding (pass {} to enable). This is the default.
  • imageSearch: Enable image search grounding (pass {} to enable).

• timeRangeFilter object

  Restricts search results to a specific time range. Both startTime and endTime are required.

  • startTime: Start time in ISO 8601 format (e.g. '2025-01-01T00:00:00Z').
  • endTime: End time in ISO 8601 format (e.g. '2025-12-31T23:59:59Z').

google.tools.googleSearch({
  searchTypes: { webSearch: {} },
  timeRangeFilter: {
    startTime: '2025-01-01T00:00:00Z',
    endTime: '2025-12-31T23:59:59Z',
  },
});

When Google Search grounding is enabled, the model will include sources in the response.

Additionally, the grounding metadata includes detailed information about how search results were used to ground the model's response. Here are the available fields:

• webSearchQueries (string[] | null)

  • Array of search queries used to retrieve information
  • Example: ["What's the weather in Chicago this weekend?"]

• searchEntryPoint ({ renderedContent: string } | null)

  • Contains the main search result content used as an entry point
  • The renderedContent field contains the formatted content

• groundingSupports (Array of support objects | null)

  • Contains details about how specific response parts are supported by search results
  • Each support object includes:
    • segment: Information about the grounded text segment
      • text: The actual text segment
      • startIndex: Starting position in the response
      • endIndex: Ending position in the response
    • groundingChunkIndices: References to supporting search result chunks
    • confidenceScores: Confidence scores (0-1) for each supporting chunk

Example response:

{
  "groundingMetadata": {
    "webSearchQueries": ["What's the weather in Chicago this weekend?"],
    "searchEntryPoint": {
      "renderedContent": "..."
    },
    "groundingSupports": [
      {
        "segment": {
          "startIndex": 0,
          "endIndex": 65,
          "text": "Chicago weather changes rapidly, so layers let you adjust easily."
        },
        "groundingChunkIndices": [0],
        "confidenceScores": [0.99]
      }
    ]
  }
}

Enterprise Web Search

With Enterprise Web Search, the model has access to a compliance-focused web index designed for highly-regulated industries such as finance, healthcare, and public sector.

import { createGoogleVertex } from '@ai-sdk/google-vertex';
import { generateText } from 'ai';

const vertex = createGoogleVertex({
  project: 'my-project',
  location: 'us-central1',
});

const { text, sources, providerMetadata } = await generateText({
  model: vertex('gemini-4-argon'),
  tools: {
    enterprise_web_search: vertex.tools.enterpriseWebSearch({}),
  },
  prompt: 'What are the latest regulatory updates for financial services?',
});

Enterprise Web Search provides the following benefits:

• Does not log customer data
• Supports VPC service controls
• Compliance-focused web index for regulated industries

File Search

The File Search tool lets Gemini retrieve context from your own documents that you have indexed in File Search stores. The provider enables this tool for Gemini 2.5 and Gemini 3-and-later model IDs, including unrecognized future Gemini IDs.

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const { text, sources, providerMetadata } = await generateText({
  model: google('gemini-4-argon'),
  tools: {
    file_search: google.tools.fileSearch({
      fileSearchStoreNames: [
        'projects/my-project/locations/us/fileSearchStores/my-store',
      ],
      metadataFilter: 'author = "Robert Graves"',
      topK: 8,
    }),
  },
  prompt: "Summarise the key themes of 'I, Claudius'.",
});

File Search responses include citations via the normal sources field and expose raw grounding metadata in providerMetadata.google.groundingMetadata.

Custom metadata attached to the indexed documents is available in groundingMetadata.groundingChunks[].retrievedContext.customMetadata.

URL Context

Google provides a provider-defined URL context tool.

The URL context tool allows you to provide specific URLs that you want the model to analyze directly in from the prompt.

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const { text, sources, providerMetadata } = await generateText({
  model: google('gemini-4-argon'),
  prompt: `Based on the document: https://ai.google.dev/gemini-api/docs/url-context.
          Answer this question: How many links can we consume in one request?`,
  tools: {
    url_context: google.tools.urlContext({}),
  },
});

const metadata = providerMetadata?.google as GoogleProviderMetadata | undefined;
const groundingMetadata = metadata?.groundingMetadata;
const urlContextMetadata = metadata?.urlContextMetadata;

The URL context metadata includes detailed information about how the model used the URL context to generate the response. Here are the available fields:

• urlMetadata ({ retrievedUrl: string; urlRetrievalStatus: string; }[] | null)
  • Array of URL context metadata
  • Each object includes:
    • retrievedUrl: The URL of the context
    • urlRetrievalStatus: The status of the URL retrieval

Example response:

{
  "urlMetadata": [
    {
      "retrievedUrl": "https://ai-sdk.dev/providers/ai-sdk-providers/google",
      "urlRetrievalStatus": "URL_RETRIEVAL_STATUS_SUCCESS"
    }
  ]
}

With the URL context tool, you will also get the groundingMetadata.

"groundingMetadata": {
    "groundingChunks": [
        {
            "web": {
                "uri": "https://ai-sdk.dev/providers/ai-sdk-providers/google",
                "title": "Google - AI SDK Providers"
            }
        }
    ],
    "groundingSupports": [
        {
            "segment": {
                "startIndex": 67,
                "endIndex": 157,
                "text": "**Installation**: Install the `@ai-sdk/google` module using your preferred package manager"
            },
            "groundingChunkIndices": [
                0
            ]
        }
    ]
}

Combine URL Context with Search Grounding

You can combine the URL context tool with search grounding to provide the model with the latest information from the web.

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const { text, sources, providerMetadata } = await generateText({
  model: google('gemini-4-argon'),
  prompt: `Based on this context: https://ai-sdk.dev/providers/ai-sdk-providers/google, tell me how to use Gemini with AI SDK.
    Also, provide the latest news about AI SDK V5.`,
  tools: {
    google_search: google.tools.googleSearch({}),
    url_context: google.tools.urlContext({}),
  },
});

const metadata = providerMetadata?.google as GoogleProviderMetadata | undefined;
const groundingMetadata = metadata?.groundingMetadata;
const urlContextMetadata = metadata?.urlContextMetadata;

Google Maps Grounding

With Google Maps grounding, the model has access to Google Maps data for location-aware responses. This enables providing local data and geospatial context, such as finding nearby restaurants.

import { google, type GoogleLanguageModelOptions } from '@ai-sdk/google';
import { GoogleProviderMetadata } from '@ai-sdk/google';
import { generateText } from 'ai';

const { text, sources, providerMetadata } = await generateText({
  model: google('gemini-4-argon'),
  tools: {
    google_maps: google.tools.googleMaps({}),
  },
  providerOptions: {
    google: {
      retrievalConfig: {
        latLng: { latitude: 34.090199, longitude: -117.881081 },
      },
    } satisfies GoogleLanguageModelOptions,
  },
  prompt:
    'What are the best Italian restaurants within a 15-minute walk from here?',
});

const metadata = providerMetadata?.google as GoogleProviderMetadata | undefined;
const groundingMetadata = metadata?.groundingMetadata;

The optional retrievalConfig.latLng provider option provides location context for queries about nearby places. This configuration applies to any grounding tools that support location context, including Google Maps and Google Search.

When Google Maps grounding is enabled, the model's response will include sources pointing to Google Maps URLs. The grounding metadata includes maps chunks with place information:

{
  "groundingMetadata": {
    "groundingChunks": [
      {
        "maps": {
          "uri": "https://maps.google.com/?cid=12345",
          "title": "Restaurant Name",
          "placeId": "places/ChIJ..."
        }
      }
    ]
  }
}

RAG Engine Grounding

With RAG Engine Grounding, the model has access to your custom knowledge base using the Vertex RAG Engine. This enables the model to provide answers based on your specific data sources and documents.

import { createGoogleVertex } from '@ai-sdk/google-vertex';
import { GoogleProviderMetadata } from '@ai-sdk/google';
import { generateText } from 'ai';

const vertex = createGoogleVertex({
  project: 'my-project',
  location: 'us-central1',
});

const { text, sources, providerMetadata } = await generateText({
  model: vertex('gemini-4-argon'),
  tools: {
    vertex_rag_store: vertex.tools.vertexRagStore({
      ragCorpus:
        'projects/my-project/locations/us-central1/ragCorpora/my-rag-corpus',
      topK: 5,
    }),
  },
  prompt:
    'What are the key features of our product according to our documentation?',
});

// access the grounding metadata. Casting to the provider metadata type
// is optional but provides autocomplete and type safety.
const metadata = providerMetadata?.google as GoogleProviderMetadata | undefined;
const groundingMetadata = metadata?.groundingMetadata;
const safetyRatings = metadata?.safetyRatings;

When RAG Engine Grounding is enabled, the model will include sources from your RAG corpus in the response.

Additionally, the grounding metadata includes detailed information about how RAG results were used to ground the model's response. Here are the available fields:

• groundingChunks (Array of chunk objects | null)

  • Contains the retrieved context chunks from your RAG corpus
  • Each chunk includes:
    • retrievedContext: Information about the retrieved context
      • uri: The URI or identifier of the source document
      • title: The title of the source document (optional)
      • text: The actual text content of the chunk

• groundingSupports (Array of support objects | null)

  • Contains details about how specific response parts are supported by RAG results
  • Each support object includes:
    • segment: Information about the grounded text segment
      • text: The actual text segment
      • startIndex: Starting position in the response
      • endIndex: Ending position in the response
    • groundingChunkIndices: References to supporting RAG result chunks
    • confidenceScores: Confidence scores (0-1) for each supporting chunk

Example response:

{
  "groundingMetadata": {
    "groundingChunks": [
      {
        "retrievedContext": {
          "uri": "gs://my-bucket/docs/product-guide.pdf",
          "title": "Product User Guide",
          "text": "Our product includes advanced AI capabilities, real-time processing, and enterprise-grade security features."
        }
      }
    ],
    "groundingSupports": [
      {
        "segment": {
          "startIndex": 0,
          "endIndex": 45,
          "text": "Our product includes advanced AI capabilities and real-time processing."
        },
        "groundingChunkIndices": [0],
        "confidenceScores": [0.95]
      }
    ]
  }
}

Configuration Options

The vertexRagStore tool accepts the following configuration options:

• ragCorpus (string, required)

  • The RagCorpus resource name in the format: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}
  • This identifies your specific RAG corpus to search against

• topK (number, optional)

  • The number of top contexts to retrieve from your RAG corpus
  • Defaults to the corpus configuration if not specified

Image Outputs

Gemini models with image generation capabilities (e.g. gemini-3.1-flash-image-preview) support generating images as part of a multimodal response. Images are exposed as files in the response.

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google('gemini-3.1-flash-image-preview'),
  prompt:
    'Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme',
});

for (const file of result.files) {
  if (file.mediaType.startsWith('image/')) {
    console.log('Generated image:', file);
  }
}

Safety Ratings

The safety ratings provide insight into the safety of the model's response. See Google AI documentation on safety settings.

Example response excerpt:

{
  "safetyRatings": [
    {
      "category": "HARM_CATEGORY_HATE_SPEECH",
      "probability": "NEGLIGIBLE",
      "probabilityScore": 0.11027937,
      "severity": "HARM_SEVERITY_LOW",
      "severityScore": 0.28487435
    },
    {
      "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
      "probability": "HIGH",
      "blocked": true,
      "probabilityScore": 0.95422274,
      "severity": "HARM_SEVERITY_MEDIUM",
      "severityScore": 0.43398145
    },
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "probability": "NEGLIGIBLE",
      "probabilityScore": 0.11085559,
      "severity": "HARM_SEVERITY_NEGLIGIBLE",
      "severityScore": 0.19027223
    },
    {
      "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
      "probability": "NEGLIGIBLE",
      "probabilityScore": 0.22901751,
      "severity": "HARM_SEVERITY_NEGLIGIBLE",
      "severityScore": 0.09089675
    }
  ]
}

Troubleshooting

Schema Limitations

The Google Generative AI API supports a subset of JSON Schema. Google notes that very large or deeply nested schemas may be rejected. When a schema exceeds Google's complexity limit, the API may return the following generic error:

Request contains an invalid argument.

You can work around this by simplifying the schema sent to Google. For example, remove unnecessary constraints or reduce nesting while preserving the fields and types the model needs to generate. If you need stricter client-side validation than the schema sent to Google, use jsonSchema with a custom validation function or validate the generated output separately.

By default, structured outputs are enabled (and for tool calling they are required). You can also disable provider-enforced structured outputs for object generation:

const { output } = await generateText({
  model: google('gemini-4-argon'),
  providerOptions: {
    google: {
      structuredOutputs: false,
    } satisfies GoogleLanguageModelOptions,
  },
  output: Output.object({
    schema: z.object({
      name: z.string(),
      age: z.number(),
      contact: z.union([
        z.object({
          type: z.literal('email'),
          value: z.string(),
        }),
        z.object({
          type: z.literal('phone'),
          value: z.string(),
        }),
      ]),
    }),
  }),
  prompt: 'Generate an example person for testing.',
});

When structuredOutputs is false, Google still receives the JSON response MIME type but not the schema. Describe the required schema in your prompt. AI SDK will still validate the response against the schema in Output.object.

Model Capabilities

Batch

The Google provider supports asynchronous text generation through the Gemini Batch API. Pass the Google provider to the AI SDK's Batch API for the complete workflow, including polling, persistence, and result handling.

Each request specifies its type and model. Google requires every text request in a batch to use the same model and throws before submission when the models differ.

Webhooks

You can pass a webhookUrl to receive a notification when the batch reaches a terminal state:

import { google } from '@ai-sdk/google';
import { experimental_startBatch as startBatch } from 'ai';

const model = 'gemini-4-argon';

const batch = await startBatch({
  provider: google,
  requests: [
    {
      id: 'capital-france',
      type: 'text',
      model,
      prompt: 'What is the capital of France?',
    },
    {
      id: 'capital-germany',
      type: 'text',
      model,
      prompt: 'What is the capital of Germany?',
    },
  ],
  webhookUrl: 'https://example.com/api/google-batch-webhook',
});

Google sends a thin event to the webhook URL. After receiving and verifying the event, use the persisted batch reference with getBatchStatus or getBatchResults. Your application is responsible for handling the webhook and verifying Google's dynamic webhook signature.

Large Batches

When the serialized batch creation body is under 20 MB, the provider sends the requests inline. At 20 MB or more, it uploads a JSONL input file through the Gemini Files API.

Realtime Models

You can create models that call the Gemini Live API using the .experimental_realtime() factory method.

import { google } from '@ai-sdk/google';

const model = google.experimental_realtime('gemini-3.1-flash-live-preview');

Realtime sessions run in the browser and require a short-lived token created on your server with google.experimental_realtime.getToken():

const token = await google.experimental_realtime.getToken({
  model: 'gemini-3.1-flash-live-preview',
});

Google realtime models may require provider-specific audio formats, depending on the model and modality. See Realtime for the complete setup and tool calling pattern.

Gemini lifecycle signals that do not have provider-neutral equivalents are emitted as custom events. Inspect rawType for goAway, sessionResumptionUpdate, and generationComplete and use the event's raw payload for provider-specific details.

With input audio transcription enabled, parseServerEvent emits input-transcription-completed events with a stable itemId for each user utterance. Each transcript contains the accumulated text so far. If you consume these events directly, replace the text for that itemId with transcript on each event. The realtime session handles this automatically.

Google's finished transcription marker ends an utterance even when the marker contains no text. For payloads without this marker, response completion and interruption provide fallback boundaries. These fallback boundaries cannot unambiguously associate all delayed transcription fragments. Input item IDs use their own sequence and need not match the model's response IDs.

Live Translation

Use gemini-3.5-live-translate-preview for low-latency speech-to-speech translation. Configure the target language with providerOptions.google.translationConfig in the realtime session config you use when creating the token:

import {
  google,
  type Experimental_GoogleRealtimeModelOptions as GoogleRealtimeModelOptions,
} from '@ai-sdk/google';

const token = await google.experimental_realtime.getToken({
  model: 'gemini-3.5-live-translate-preview',
  sessionConfig: {
    outputModalities: ['audio'],
    inputAudioTranscription: {},
    outputAudioTranscription: {},
    providerOptions: {
      google: {
        translationConfig: {
          targetLanguageCode: 'pl',
          echoTargetLanguage: true,
        },
      } satisfies GoogleRealtimeModelOptions,
    },
  },
});

Set targetLanguageCode to a BCP-47 language code (defaults to en). When echoTargetLanguage is true, input audio already in the target language is echoed instead of producing silence.

Gemini Live Translation accepts audio input and produces translated audio output. Text input, tools, and custom instructions are not supported by this model.

Gemini 3.8 Live

gemini-3.8-live and gemini-3.8-live-extended-thinking are audio-only realtime models: request outputModalities: ['audio'], and add outputAudioTranscription: {} if you want the assistant's transcript as audio-transcript-delta events. Server-side voice activity detection and proactive audio are always on.

gemini-3.8-live-extended-thinking reasons in the background while streaming audio. Google requires exactly one of thinkingLevel (low, medium, high) or thinkingBudget for it; the provider sends thinkingLevel: 'low' when you set neither. Override it through providerOptions.google.thinkingConfig:

import {
  google,
  type Experimental_GoogleRealtimeModelOptions as GoogleRealtimeModelOptions,
} from '@ai-sdk/google';

const token = await google.experimental_realtime.getToken({
  model: 'gemini-3.8-live-extended-thinking',
  sessionConfig: {
    outputModalities: ['audio'],
    outputAudioTranscription: {},
    providerOptions: {
      google: {
        thinkingConfig: { thinkingLevel: 'high' },
      } satisfies GoogleRealtimeModelOptions,
    },
  },
});

Tools declared in the session config run asynchronously (NON_BLOCKING) by default on these models, so the model keeps talking while a tool call is in flight. Set providerOptions.google.defaultToolBehavior: 'BLOCKING' on gemini-3.8-live to make it wait for the result instead.

On the extended thinking model, turnComplete (the response-done event) does not mean the model is idle. Watch the interactionStatus custom event: its raw.interactionStatus is IN_PROGRESS, IDLE, or WAITING_FOR_INPUT. A waitingForInput custom event is emitted when the model has stopped and needs user input to continue.

Translation Models

For server-side streaming translation, you can create models that call the Gemini Live API using the .translation() factory method. Translation models are streaming-only and are used with experimental_streamTranslate.

The first argument is the model id e.g. gemini-3.5-live-translate-preview.

const model = google.translation('gemini-3.5-live-translate-preview');

import { experimental_streamTranslate as streamTranslate } from 'ai';
import { google } from '@ai-sdk/google';

const result = streamTranslate({
  model: google.translation('gemini-3.5-live-translate-preview'),
  audio: audioStream, // ReadableStream<Uint8Array | string>
  inputAudioFormat: { type: 'audio/pcm', rate: 16000 },
  targetLanguage: 'es',
});

for await (const part of result.fullStream) {
  if (part.type === 'output-text-delta') {
    process.stdout.write(part.delta);
  }
}

The Gemini Live API auto-detects the source language (sourceLanguage is not supported) and always outputs 24kHz 16-bit PCM audio (outputAudioFormat is not supported). Unsupported settings surface as call warnings.

The following provider options are available:

• echoTargetLanguage boolean Whether input audio already in the target language should be echoed instead of producing silence. Optional.

Model Capabilities

Interactions API

The Gemini Interactions API (POST /v1beta/interactions) is a separate Google endpoint with server-side state, unified content blocks, first-class built-in tools, agent presets, managed agents that run in a sandboxed Linux environment, and native multimodal image and video output. It is reached via the google.interactions(...) factory:

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const { text } = await generateText({
  model: google.interactions('gemini-4-argon'),
  prompt: 'Hello, how are you?',
});

google.interactions(...) accepts a model ID string (e.g. 'gemini-4-argon', 'gemini-3.1-pro-preview'), { agent: <name> } to use a Gemini agent preset, or { managedAgent: <name> } to invoke a managed agent you created on Google's side. The returned model can be passed to generateText and streamText like any other AI SDK language model.

Provider Options

The Interactions model reads its options from the shared providerOptions.google.* namespace. Validate them with the GoogleLanguageModelInteractionsOptions type:

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText } from 'ai';

await generateText({
  model: google.interactions('gemini-4-argon'),
  prompt: 'What color is the sky in one word?',
  providerOptions: {
    google: {
      serviceTier: 'priority',
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

The following optional provider options are available:

• previousInteractionId string

  Server-side interaction id from a prior turn. When set, the server pulls prior context from its own state and only the new user message is sent on the wire. Pair with the default store: true to chain stateful conversations. See Stateful chaining.

• store boolean

  Whether the server should persist the interaction. Defaults to true. Set to false for stateless multi-turn conversations where the full message history is re-sent on every turn.

• agent string

  Name of a Gemini agent preset (e.g. 'deep-research-pro-preview-12-2025').

  Note

  Prefer the factory form google.interactions({ agent: '...' }) over setting agent in provider options — the factory is type-checked against the supported agent names.

• agentConfig object

  Per-agent configuration. Currently supports { type: 'dynamic' } and { type: 'deep-research', thinkingSummaries?, visualization?, collaborativePlanning? }.

• thinkingLevel 'minimal' | 'low' | 'medium' | 'high'

  Controls reasoning depth for thinking-enabled models. Mapped onto the Interactions request's thinking_level.

• thinkingSummaries 'auto' | 'none'

  Whether the model returns synthesized thought summaries on reasoning parts. Defaults to the API default.

• responseFormat Array<ResponseFormatEntry>

  Output-format entries that map directly to the API's response_format array. Entries have the following shape:

  type ResponseFormatEntry =
    | { type: 'text'; mimeType?: string; schema?: unknown }
    | {
        type: 'image';
        mimeType?: string;
        aspectRatio?: string;
        imageSize?: '1K' | '2K' | '4K' | '512';
      }
    | { type: 'audio'; mimeType?: string }
    | {
        type: 'video';
        aspectRatio?: '16:9' | '9:16';
        resolution?: '360p' | '720p' | '1080p' | '4k';
        duration?: string;
        delivery?: 'inline' | 'uri';
        gcsUri?: string;
      };
  

  Use this for fine-grained control over image, audio, video, or non-JSON text outputs. Video entries can control aspect ratio, resolution, duration, and inline or URI delivery; set gcsUri when delivering to Google Cloud Storage. Inline videos are returned in result.files by generateText and emitted as file parts by streamText. The AI SDK call-level responseFormat: { type: 'json', schema } still drives JSON-mode automatically and prepends a matching text entry; entries listed here are appended.

  For image entries, aspectRatio accepts 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:8, 8:1, 1:4, 4:1.

• imageConfig { aspectRatio?: string; imageSize?: '1K' | '2K' | '4K' | '512' } (deprecated)

  Use responseFormat with a { type: 'image', ... } entry instead. Retained for backwards compatibility; the SDK translates imageConfig into a matching response_format image entry and emits a warning when set. Ignored when responseFormat already supplies an image entry.

• mediaResolution 'low' | 'medium' | 'high' | 'ultra_high'

  Media resolution applied to image inputs / outputs.

• serviceTier 'flex' | 'standard' | 'priority'

  Service tier for the request. Mirrored back on result.providerMetadata.google.serviceTier for observability.

• systemInstruction string

  Alternative to the AI SDK system message. If both are set, the AI SDK system message wins and a warning is emitted.

• background boolean

  Run the interaction in the background. Required for agents whose server-side workflow cannot complete within a single request/response; rejected by agents that only support synchronous calls. When true, the POST returns a non-terminal status and the SDK polls GET /interactions/{id} until the work completes.

• environment string | object

  Sandbox environment configuration for managed agents. Pass 'remote' to provision a fresh sandbox, an environment_id string to reuse an existing one, or an object of the form { type: 'remote', sources?, network? } to preload files and/or constrain outbound traffic. Only applies to agent calls.

• pollingTimeoutMs number

  Maximum time, in milliseconds, to poll a background interaction before giving up. Defaults to 30 minutes (1,800,000 ms). Long-running agents may need longer.

Provider Metadata

result.providerMetadata.google (typed via GoogleInteractionsProviderMetadata) exposes:

• interactionId string

  Server-side interaction id. Pass this back as previousInteractionId on the next turn to chain.

• serviceTier string

  Service tier the request actually ran on.

• signature string

  Per-block signature hash, set by the SDK on output reasoning and tool-call or agentic video processing parts. Round-tripped automatically on the next turn.

Agentic video custom parts additionally expose:

• processingId string

  ID of an agentic video processing_call. Present on google.processing_call custom parts.

• processingCallId string

  ID of the matching agentic video processing call. Present on google.processing_result custom parts.

Stateful chaining

With the default store: true, the server retains the prior turn so the next request only needs to send the new user message and the previousInteractionId:

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText } from 'ai';

const turn1 = await generateText({
  model: google.interactions('gemini-4-argon'),
  prompt: 'What are the three largest cities in Spain?',
});

const interactionId = turn1.providerMetadata?.google?.interactionId as
  | string
  | undefined;

const turn2 = await generateText({
  model: google.interactions('gemini-4-argon'),
  prompt: 'What is the most famous landmark in the second one?',
  providerOptions: {
    google: {
      previousInteractionId: interactionId,
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

For stateless multi-turn conversations, set store: false and re-send the full message history on every turn (no previousInteractionId):

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText, type ModelMessage } from 'ai';

const messages: Array<ModelMessage> = [
  { role: 'user', content: 'What are the three largest cities in Spain?' },
];

const turn1 = await generateText({
  model: google.interactions('gemini-4-argon'),
  messages,
  providerOptions: {
    google: { store: false } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

messages.push(...turn1.responseMessages);
messages.push({
  role: 'user',
  content: 'What is the most famous landmark in the second one?',
});

const turn2 = await generateText({
  model: google.interactions('gemini-4-argon'),
  messages,
  providerOptions: {
    google: { store: false } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

Agentic video understanding

Gemini 4 Argon, 3.7 Flash, 3.6 Flash, and 3.5 Flash Lite support agentic video understanding through the Interactions API. Instead of sampling the entire video at a fixed frame rate, the model dynamically navigates the timeline and loads the transcripts, frames, or audio needed for the prompt.

Set processing: 'agentic' in the Google provider options of an individual video file part. You can validate the per-file options with GoogleInteractionsVideoOptions:

import { google, type GoogleInteractionsVideoOptions } from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google.interactions('gemini-4-argon'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'file',
          data: 'https://www.youtube.com/watch?v=9hE5-98ZeCg',
          mediaType: 'video',
          providerOptions: {
            google: {
              processing: 'agentic',
            } satisfies GoogleInteractionsVideoOptions,
          },
        },
        {
          type: 'text',
          text: 'Identify the three most important moments and include timestamps.',
        },
      ],
    },
  ],
  providerOptions: {
    google: {
      thinkingSummaries: 'auto',
    },
  },
});

const processingSteps = result.content.filter(
  part =>
    part.type === 'custom' &&
    (part.kind === 'google.processing_call' ||
      part.kind === 'google.processing_result'),
);

Agentic navigation is exposed as custom content parts:

• google.processing_call marks a request by the model to inspect part of the video. Its providerMetadata.google.processingId contains the processing ID.
• google.processing_result marks completion of that request. Its providerMetadata.google.processingCallId links it to the processing call.

These parts are informational and do not require a tool response. They are available from both generateText and streamText.

For static processing, use 'static' or provide clipping and frame-rate options. startOffset and endOffset are measured in seconds:

const video = {
  type: 'file' as const,
  data: videoBytes,
  mediaType: 'video/mp4',
  providerOptions: {
    google: {
      processing: {
        type: 'static',
        startOffset: 0,
        endOffset: 10.5,
        fps: 0.5,
      },
    } satisfies GoogleInteractionsVideoOptions,
  },
};

With stateful conversations, pass the returned interactionId as previousInteractionId; Gemini retains the video context server-side. With store: false, append result.responseMessages and re-send the full history. The processing custom parts and their signatures are then round-tripped as native processing_call and processing_result steps so the video context is preserved.

Built-in Tools

The Interactions API ships a built-in tool catalog. The provider-defined tools under google.tools.* map onto Interactions tool descriptors:

Function tools (type: 'function') defined with the AI SDK tool(...) helper are translated to Interactions function tool descriptors. Other tool kinds emit a warning and are dropped.

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const { text, sources } = await generateText({
  model: google.interactions('gemini-4-argon'),
  tools: {
    google_search: google.tools.googleSearch({}),
  },
  prompt:
    "What's a notable AI development from this past week? " +
    'Include the date for each item you mention.',
});

Function tools work the same way as on the standard provider:

import { google } from '@ai-sdk/google';
import { generateText, isStepCount, tool } from 'ai';
import { z } from 'zod';

const weatherTool = tool({
  description: 'Get the weather for a city.',
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ city }) => `It is sunny in ${city}.`,
});

const { text, toolCalls } = await generateText({
  model: google.interactions('gemini-4-argon'),
  tools: { getWeather: weatherTool },
  stopWhen: isStepCount(5),
  prompt: 'What is the weather in San Francisco right now?',
});

Image output via Interactions

Add a { type: 'image' } entry to responseFormat on a Gemini image-capable model to get images as LanguageModelV4FilePart files in the response. No tool wrapping is required, and the entry doubles as the place to set aspectRatio, imageSize, and mimeType.

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google.interactions('gemini-3-pro-image-preview'),
  prompt: 'Generate an image of a comic cat in a spaceship.',
  providerOptions: {
    google: {
      responseFormat: [{ type: 'image' }],
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

for (const file of result.files) {
  if (file.mediaType.startsWith('image/')) {
    // file.uint8Array | file.base64 | file.mediaType
  }
}

To control aspect ratio, image size, or output mime type, add those fields to the same image entry:

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google.interactions('gemini-3-pro-image-preview'),
  prompt: 'Generate a high-quality landscape photo of mountains at sunset.',
  providerOptions: {
    google: {
      responseFormat: [
        {
          type: 'image',
          aspectRatio: '16:9',
          imageSize: '4K',
        },
      ],
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

For multimodal output, list one entry per modality. The model returns text in result.text and the accompanying image(s) in result.files:

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google.interactions('gemini-3.1-flash-image-preview'),
  prompt:
    'Tell me a three sentence bedtime story about a unicorn, accompanied by a suitable illustration.',
  providerOptions: {
    google: {
      responseFormat: [
        { type: 'text' },
        { type: 'image', aspectRatio: '16:9' },
      ],
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

console.log(result.text);

const images = result.files.filter(file => file.mediaType.startsWith('image/'));
// images[0].uint8Array | images[0].base64 | images[0].mediaType

Iterative image editing pairs naturally with stateful chaining — keep previousInteractionId set across turns and the model edits its prior output:

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText } from 'ai';

const model = google.interactions('gemini-3-pro-image-preview');

const turn1 = await generateText({
  model,
  prompt: 'Generate an image of a comic cat in a spaceship.',
  providerOptions: {
    google: {
      responseFormat: [{ type: 'image' }],
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

const interactionId = turn1.providerMetadata?.google?.interactionId as
  | string
  | undefined;

const turn2 = await generateText({
  model,
  prompt: 'now make the cat red',
  providerOptions: {
    google: {
      responseFormat: [{ type: 'image' }],
      previousInteractionId: interactionId,
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

Agent presets

Pass { agent: <name> } to target a Gemini agent preset. The factory type-checks the agent name against the supported set:

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google.interactions({
    agent: 'deep-research-pro-preview-12-2025',
  }),
  prompt:
    'Briefly summarize the most-cited papers on retrieval-augmented generation since 2024 (2-3 sentences).',
  providerOptions: {
    google: {
      background: true,
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

Whether an agent runs synchronously or in the background depends on the agent. Long-running presets (such as the deep-research-* family) require background: true — the POST returns a non-terminal status and the SDK polls GET /interactions/{id} internally until the interaction completes. Other agents accept synchronous calls only and will reject background: true. Set the flag explicitly via providerOptions.google.background.

The default polling timeout is 30 minutes; raise it via pollingTimeoutMs for slower agents:

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText } from 'ai';

await generateText({
  model: google.interactions({ agent: 'deep-research-max-preview-04-2026' }),
  prompt: 'Produce a long-form research brief on ...',
  providerOptions: {
    google: {
      background: true,
      pollingTimeoutMs: 60 * 60 * 1000, // 1 hour
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

Agents also chain through previousInteractionId like model-id calls.

Managed Agents

Managed agents run inside a sandboxed Linux environment provisioned per interaction. Pass the environment provider option to control how the sandbox is set up; the option is only accepted on agent calls.

The simplest form provisions a fresh sandbox:

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google.interactions({ agent: 'antigravity-preview-05-2026' }),
  prompt: 'What is 2 + 2?',
  providerOptions: {
    google: {
      environment: 'remote',
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

environment accepts three shapes:

• 'remote' — provision a fresh sandbox for this call.
• any other string — an environment_id to reuse, forking the previous sandbox so its filesystem and installed packages persist.
• an object — provision a fresh sandbox and optionally preload sources and/or constrain outbound traffic via network:

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText } from 'ai';

await generateText({
  model: google.interactions({ agent: 'antigravity-preview-05-2026' }),
  prompt:
    'Read the file at /data/note.txt and tell me exactly what it contains.',
  providerOptions: {
    google: {
      environment: {
        type: 'remote',
        sources: [
          {
            type: 'inline',
            content: 'hello from the AI SDK example\n',
            target: '/data/note.txt',
          },
        ],
      },
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

Three source types are supported: inline (write a string into the sandbox at target), repository (clone a git repository — pass the URL as source), and gcs (mount a Google Cloud Storage prefix).

The network field accepts the string 'disabled' to block all outbound traffic, or an object with an allowlist array whose entries each carry a domain plus an optional transform array of header objects to inject into matching requests.

Custom managed agents

For user-defined agents that you created on Google's side via the Gemini API's /v1beta/agents endpoint, pass the agent's name through the dedicated managedAgent factory shape instead of agent (which only accepts known preset names):

import {
  google,
  type GoogleLanguageModelInteractionsOptions,
} from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google.interactions({ managedAgent: 'my-custom-agent' }),
  prompt: 'Hello!',
  providerOptions: {
    google: {
      environment: 'remote',
    } satisfies GoogleLanguageModelInteractionsOptions,
  },
});

Streaming

streamText is supported. The stream's finish part exposes interactionId on providerMetadata.google so callers can chain.

import { google } from '@ai-sdk/google';
import { streamText } from 'ai';

const result = streamText({
  model: google.interactions('gemini-4-argon'),
  prompt: 'Hello, how are you?',
});

for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}

const googleMetadata = (await result.providerMetadata)?.google;
console.log('Interaction id:', googleMetadata?.interactionId);

Gemma Models

You can use Gemma models with the Google Generative AI API. The following Gemma models are available:

• gemma-3-27b-it
• gemma-3-12b-it

Gemma models don't natively support the systemInstruction parameter, but the provider automatically handles system instructions by prepending them to the first user message. This allows you to use system instructions with Gemma models seamlessly:

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const { text } = await generateText({
  model: google('gemma-3-27b-it'),
  instructions: 'You are a helpful assistant that responds concisely.',
  prompt: 'What is machine learning?',
});

The system instruction is automatically formatted and included in the conversation, so Gemma models can follow the guidance without any additional configuration.

Embedding Models

You can create models that call the Google Generative AI embeddings API using the .embedding() factory method.

const model = google.embedding('gemini-embedding-2');

The Google provider sends API calls to the right endpoint based on the type of embedding:

• Single embeddings: When embedding a single value with embed(), the provider uses the single :embedContent endpoint, which typically has higher rate limits compared to the batch endpoint.
• Batch embeddings: When embedding multiple values with embedMany() or multiple values in embed(), the provider uses the :batchEmbedContents endpoint.

Google embedding models support additional settings. You can pass them as an options argument:

import { google, type GoogleEmbeddingModelOptions } from '@ai-sdk/google';
import { embed } from 'ai';

const model = google.embedding('gemini-embedding-001');

const { embedding } = await embed({
  model,
  value: 'sunny day at the beach',
  providerOptions: {
    google: {
      outputDimensionality: 512, // optional, number of dimensions for the embedding
      taskType: 'SEMANTIC_SIMILARITY', // optional, specifies the task type for generating embeddings
      content: [[{ text: 'additional context' }]], // optional, per-value multimodal content (only 1 here, since `value` is only a single one)
    } satisfies GoogleEmbeddingModelOptions,
  },
});

When using embedMany, provide per-value multimodal content via the content option. Each entry corresponds to a value at the same index; use null for text-only entries:

import { google, type GoogleEmbeddingModelOptions } from '@ai-sdk/google';
import { embedMany } from 'ai';

const { embeddings } = await embedMany({
  model: google.embedding('gemini-embedding-2'),
  values: ['sunny day at the beach', 'rainy afternoon in the city'],
  providerOptions: {
    google: {
      // content array must have the same length as values
      content: [
        [{ inlineData: { mimeType: 'image/png', data: '<base64>' } }], // pairs with values[0]
        null, // text-only, pairs with values[1]
      ],
    } satisfies GoogleEmbeddingModelOptions,
  },
});

The following optional provider options are available for Google embedding models:

• outputDimensionality: number

  Optional reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.

• taskType: string

  Optional. Specifies the task type for generating embeddings. Supported task types include:

  • SEMANTIC_SIMILARITY: Optimized for text similarity.
  • CLASSIFICATION: Optimized for text classification.
  • CLUSTERING: Optimized for clustering texts based on similarity.
  • RETRIEVAL_DOCUMENT: Optimized for document retrieval.
  • RETRIEVAL_QUERY: Optimized for query-based retrieval.
  • QUESTION_ANSWERING: Optimized for answering questions.
  • FACT_VERIFICATION: Optimized for verifying factual information.
  • CODE_RETRIEVAL_QUERY: Optimized for retrieving code blocks based on natural language queries.

• content: array

  Optional. Per-value multimodal content parts for embedding non-text content (images, video, PDF, audio). Each entry corresponds to the embedding value at the same index — its parts are merged with the text value in the request. Use null for entries that are text-only. The array length must match the number of values being embedded. Each non-null entry is an array of parts, where each part can be { text: string }, { inlineData: { mimeType: string, data: string } } for inline base64 data, or { fileData: { fileUri: string, mimeType: string } } to reference remote content via HTTP URL or Google Cloud Storage URI (gs://...). Supported by gemini-embedding-2-preview.

Model Capabilities

Image Models

You can create image models that call the Google Generative AI API using the .image() factory method. For more on image generation with the AI SDK see generateImage().

The .image() factory supports Gemini multimodal language models with image output capabilities through the :generateContent API.

Gemini Image Models

Gemini image models (e.g. gemini-3.1-flash-image-preview) are technically multimodal output language models, but they can be used with the generateImage() function for a simpler image generation experience. Internally, the provider calls the language model API with responseModalities: ['IMAGE'].

import { google } from '@ai-sdk/google';
import { generateImage } from 'ai';

const { image } = await generateImage({
  model: google.image('gemini-3.1-flash-image-preview'),
  prompt: 'A photorealistic image of a cat wearing a wizard hat',
  aspectRatio: '1:1',
});

Gemini image models also support image editing by providing input images:

import { google } from '@ai-sdk/google';
import { generateImage } from 'ai';
import fs from 'node:fs';

const sourceImage = fs.readFileSync('./cat.png');

const { image } = await generateImage({
  model: google.image('gemini-3.1-flash-image-preview'),
  prompt: {
    text: 'Add a small wizard hat to this cat',
    images: [sourceImage],
  },
});

You can also use URLs for input images:

import { google } from '@ai-sdk/google';
import { generateImage } from 'ai';

const { image } = await generateImage({
  model: google.image('gemini-3.1-flash-image-preview'),
  prompt: {
    text: 'Add a small wizard hat to this cat',
    images: ['https://example.com/cat.png'],
  },
});

Google Search Grounding

Gemini image models support Google Search grounding through providerOptions.google.googleSearch. The value matches the args of google.tools.googleSearch(...); pass {} to enable with defaults, or { searchTypes: { imageSearch: {} } } to ground on reference photos.

import { google, type GoogleImageModelOptions } from '@ai-sdk/google';
import { generateImage } from 'ai';

const result = await generateImage({
  model: google.image('gemini-3.1-flash-image-preview'),
  prompt:
    'Search for live footage of the 2026 Super Bowl halftime show artist, then generate a close-up in space.',
  providerOptions: {
    google: {
      googleSearch: { searchTypes: { imageSearch: {} } },
    } satisfies GoogleImageModelOptions,
  },
});

// Grounding metadata is forwarded onto the image result:
console.log(result.providerMetadata?.google?.groundingMetadata);

Gemini Image Model Capabilities

Speech Models

You can create models that call the Gemini text-to-speech API using the .speech() factory method.

The first argument is the model ID, such as gemini-3.8-flash-tts or gemini-3.8-flash-lite-tts. Speech generation uses the generateContent API.

const model = google.speech('gemini-3.8-flash-tts');

The voice argument can be set to one of Gemini's 30 prebuilt voices e.g. Kore, Puck, Zephyr, or Charon. Voice names are case-sensitive. The default voice is Kore. Custom voice IDs and replication keys are not supported.

import { generateSpeech } from 'ai';
import { google } from '@ai-sdk/google';

const result = await generateSpeech({
  model: google.speech('gemini-3.8-flash-tts'),
  text: 'Hello, world!',
  voice: 'Kore', // Gemini voice name
});

By default the generated audio is returned as a playable WAV file (result.audio.mediaType is audio/wav). Gemini 3.8 returns a complete WAV file; the provider passes those bytes through unchanged. Older models return raw PCM, which the provider wraps in a WAV container. Write result.audio.uint8Array directly to disk without adding another WAV header.

Gemini 3.8 supports the following outputFormat values:

These map to generationConfig.responseFormat.audio.mimeType in generateContent. Older models support wav and pcm. The source MIME type and sample rate are available in result.providerMetadata.google.

Gemini 2.5 and 3.1 model IDs retain the legacy request format. Other model IDs, including custom aliases, use the structured speech format.

Speech directions in Gemini 3.8

Gemini 3.8 treats text as a verbatim transcript. The provider sends instructions as speechMetadata.style, leaving the text unchanged. You can also supply providerOptions.google.speechMetadata with style and speaker fields. An explicit style overrides instructions, including an empty style string.

const result = await generateSpeech({
  model: google.speech('gemini-3.8-flash-tts'),
  text: 'Welcome back. <short pause> It is good to see you. <laugh>',
  instructions: 'Warm, relaxed, and speaking slowly',
});

Put sustained delivery directions such as whispering, speaking slowly, or being out of breath in metadata. Keep momentary vocal events and pauses such as <laugh>, <sigh>, <cough>, <breath>, and <short pause> in the transcript. Avoid sound-effect tags such as applause or thuds. The provider preserves inline tags as written.

For Gemini 3.1 and earlier, the provider retains the existing behavior of prepending instructions to single-speaker text. It ignores instructions with a warning for older multi-speaker requests. Structured turns and speechMetadata require Gemini 3.8.

Multi-speaker audio

For Gemini 3.8 dialogue, pass multiSpeakerVoiceConfig and turns through providerOptions.google. Every turn must include speechMetadata.speaker matching a configured speaker; missing or unknown speakers produce an error before the request is sent. Speaker labels belong in metadata, not the text.

The turns array replaces the top-level text, so pass text: ''. The combined turn text must be non-empty. Passing nonempty top-level text with turns produces a warning. Put metadata on each turn instead of combining turns with top-level speechMetadata. Each turn's style overrides instructions; turns without a style inherit instructions.

multiSpeakerVoiceConfig overrides the top-level voice. Each voiceConfig uses prebuiltVoiceConfig: { voiceName: 'Kore' }. Google supports up to two prebuilt voices in a multi-speaker request.

import { generateSpeech } from 'ai';
import { google, type GoogleSpeechModelOptions } from '@ai-sdk/google';

const result = await generateSpeech({
  model: google.speech('gemini-3.8-flash-lite-tts'),
  text: '',
  providerOptions: {
    google: {
      multiSpeakerVoiceConfig: {
        speakerVoiceConfigs: [
          {
            speaker: 'Joe',
            voiceConfig: { prebuiltVoiceConfig: { voiceName: 'Kore' } },
          },
          {
            speaker: 'Jane',
            voiceConfig: { prebuiltVoiceConfig: { voiceName: 'Puck' } },
          },
        ],
      },
      turns: [
        {
          text: 'How are you?',
          speechMetadata: { speaker: 'Joe', style: 'curious' },
        },
        {
          text: '<laugh> Doing great, thanks!',
          speechMetadata: { speaker: 'Jane', style: 'cheerful' },
        },
      ],
    } satisfies GoogleSpeechModelOptions,
  },
});

Older models continue to use labelled transcripts, such as text: 'Joe: How are you? Jane: Doing great, thanks!', with multiSpeakerVoiceConfig and without turns.

Model Capabilities

Decision Models

Create an experimental decision model with google.decisionModel(modelId). It uses Gemini structured output for Choice, Score, and Boolean questions. Choose a model that supports structured output, such as gemini-4-argon.

import { google } from '@ai-sdk/google';
import { experimental_decide } from 'ai';

const { answers } = await experimental_decide({
  model: google.decisionModel('gemini-4-argon'),
  state: 'I was charged twice.',
  questions: {
    requestsRefund: {
      type: 'boolean',
      instructions: 'Is the customer requesting money back?',
    },
    department: {
      type: 'choice',
      instructions: 'Which team should handle this?',
      criteria: { billing: 'Charges and refunds', support: 'Other requests' },
    },
  },
  providerOptions: {
    google: { thinkingConfig: { thinkingLevel: 'low' } },
  },
});

The factory respects createGoogle settings and forwards providerOptions.google, including thinking configuration. Thinking controls depend on the selected model; use options supported by that model. The existing Gemini implementation sends the answer schema as generationConfig.responseJsonSchema.

Choice labels are returned exactly, and Scores are finite fractional positions within the ordered rubric. The adapter validates complete answers after parsing and rejects safety-blocked, truncated, or invalid output. It preserves usage (including reasoning tokens), warnings, response data, and provider metadata.

Choice and Score answers do not include probability distributions. Boolean answers contain prompted estimates of P(true), validated to be finite and in [0, 1]. These estimates are not guaranteed to be calibrated. Apply thresholds in application code, for example answers.requestsRefund.probability >= 0.5. See Decisions.

Decision models can also be accessed through customProvider aliases or createProviderRegistry().decisionModel('provider:model'). Direct string IDs use Gateway by default, or an explicitly configured default provider with an decisionModel method. See model aliases and registries.