Studio previewSelf-host Studio locally.Run it
Kortyx
Open Kortyx on GitHub
Open navigation
ProductExamplesOpen sourceDocs

Google Generative AI Provider

Updated 22 days ago • September 11, 2026

@kortyx/google is the Google Gemini provider package for Kortyx.

It gives you two entry points:

  • google: a batteries-included default provider selector
  • createGoogleGenerativeAI(...): an explicit factory for custom setup

1. Install the package

pnpm add @kortyx/google

2. What the package exports

import { MODELS, PROVIDER_ID, createGoogleGenerativeAI, google, } from "@kortyx/google";

What each export is for:

  • google: default provider selector for the fastest start
  • createGoogleGenerativeAI(...): custom provider instance with explicit settings
  • MODELS: built-in Google model ids exposed by the package
  • PROVIDER_ID: the provider id string, currently "google"

3. Basic usage in the same file

If you want to use Google directly in the file where you call useReason(...), import google and call it there.

import { google } from "@kortyx/google"; const model = google("gemini-2.5-flash");

google is a provider selector, which means:

  • it is callable: google("gemini-2.5-flash")
  • it also exposes provider metadata: google.id, google.models
google.id; // "google" google.models; // readonly list of model ids

Good to know: google("gemini-2.5-flash") returns a model ref, not a live API client call. The actual provider-native model is resolved later when Kortyx executes useReason(...).

4. Shared app bootstrap usage

If you want one shared import path across your app, re-export google from a bootstrap file such as src/lib/providers.ts.

src/lib/providers.ts
export { google } from "@kortyx/google";

Then import it from that file where you actually use it:

src/nodes/chat.node.ts
import { google } from "@/lib/providers";

Good to know: export { google } from "@kortyx/google" is only a re-export. It does not create a local google variable in the same file. If you want to call google("...") in that same file, import it normally.

5. Advanced usage with explicit settings

Use createGoogleGenerativeAI(...) when you want app-owned configuration instead of the default environment-based setup.

import { createGoogleGenerativeAI } from "@kortyx/google"; export const google = createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_API_KEY, });

Use the factory when you need to:

  • pass apiKey explicitly
  • use a custom baseUrl
  • provide a custom fetch

6. Credentials and first-use behavior

The default google export resolves credentials on first use, not at import time.

Supported environment variables:

  • GOOGLE_API_KEY
  • GEMINI_API_KEY
  • GOOGLE_GENERATIVE_AI_API_KEY
  • KORTYX_GOOGLE_API_KEY
  • KORTYX_GEMINI_API_KEY

If none of them are set and you did not pass apiKey to createGoogleGenerativeAI(...), the provider throws a configuration error the first time a Google model is actually used.

7. Create model refs for workflow and node params

You can pass model refs through workflow or node params just like any other value.

params: { model: google("gemini-2.5-flash"), temperature: 0.3, }

You can also attach default model options to the ref itself:

const model = google("gemini-2.5-flash", { temperature: 0.2, maxOutputTokens: 800, });

Those become default options for later useReason(...) calls unless you override them at call time.

8. Use the model with useReason(...)

import { useReason } from "kortyx"; import { google } from "@/lib/providers"; const result = await useReason({ model: google("gemini-2.5-flash"), input: "Write a concise launch update for our beta users.", temperature: 0.3, emit: true, stream: true, }); result.text; result.usage; result.finishReason; result.providerMetadata; result.warnings;

Good to know: Provider setup is not done on createAgent(...). Model selection happens where you call useReason(...) by passing a model ref.

9. Supported normalized call options

Google currently maps these generic Kortyx options:

  • temperature
  • streaming
  • maxOutputTokens
  • stopSequences
  • abortSignal
  • reasoning.effort
  • reasoning.maxTokens
  • reasoning.includeThoughts
  • responseFormat.type

Current Google mapping details:

  • responseFormat.type: "json" sets the Google response MIME type to JSON
  • responseFormat.type: "text" sets the Google response MIME type to plain text
  • reasoning.* maps to Google thinking configuration

Current warning-backed gaps:

  • responseFormat.schema maps to native responseJsonSchema
  • providerOptions.google.thinkingConfig supports native thinking controls; unknown options produce warnings
  • unsupported or rejected reasoning.effort values fail explicitly; no request is retried without effort

That means you should check result.warnings if you are relying on advanced generic options and want to confirm how the provider handled them.

10. Normalized metadata you get back

Google returns the normalized Kortyx result fields when the API provides them:

  • usage
  • finishReason
  • providerMetadata
  • warnings
  • raw

Google-specific metadata currently includes fields such as:

  • providerId
  • modelId
  • responseId
  • modelVersion
  • promptFeedback
  • usageMetadata

Use providerMetadata when you need debugging or observability details without coupling your app code to the raw provider payload shape.

Supported scope

@kortyx/google currently supports text generation through useReason(...), including streaming and non-streaming invocation.

It does not currently expose provider-native embeddings, image generation, file APIs, Google-hosted tools, or multimodal output APIs. Check result.warnings when you rely on advanced generic options and want to verify how Google handled them.

Available built-in Google model ids

  • gemini-2.5-flash
  • gemini-2.0-flash
  • gemini-1.5-pro
  • gemini-1.5-flash

Next steps

  • See Hooks for useReason(...) behavior and structured output
  • See Provider API for the shared normalized provider contract

Reasoning, tools, and structured output

Model IDs accept arbitrary non-empty strings; MODELS supplies autocomplete suggestions. useReason preserves thought signatures and original function-call IDs across tool rounds and approval resumes. Thought summaries are kept separate from final text and JSON.

Compatible outputSchema calls use native JSON Schema enforcement. Tool schemas retain references and property names. Gemini 3 models receive reasoning.effort as a thinking level; Gemini 2.5 maps minimal/low/medium/high to budgets of 512/1,024/8,192/24,576 tokens, with a compatibility warning. Use reasoning.maxTokens for a specific budget, or providerOptions.google.thinkingConfig for native controls. Do not supply both generic effort and budget.

Behavior change: rejected reasoning settings now fail explicitly; Kortyx no longer retries without effort. none disables thinking on compatible Gemini 2.5 Flash models and fails on models that cannot disable thinking. No model is substituted automatically.

When combining tools with JSON output, useReason keeps output constraints off tool-selection turns. Gemini 2.x rejects the combined request, and live Gemini 3 generateContent tests repeatedly selected a tool instead of returning the final JSON. With only outputSchema, Kortyx reuses an answer that passes local validation and reports a compatibility warning. Otherwise it makes a separate JSON-only call, using the same model and reasoning and counting toward existing limits. An explicit responseFormat.schema always requires provider-enforced finalization. Direct Gemini 2.x requests combining tools and JSON fail with guidance.

See Google thought signatures and structured output.