@standardagents/google
v0.45.10
Published
Google Gemini provider for Standard Agents
Readme
@standardagents/google
Google Gemini and Imagen provider for Standard Agents.
This package exports a Standard Agents provider factory for Google's Gemini chat/multimodal models and Imagen image models. It handles:
- model discovery via the Google model list API
- Standard Agents message and tool translation to Google
generateContentrequests - Gemini text, JSON, tools, and multimodal inputs
- Imagen generation and image-edit style requests
- usage and cost calculation from Google usage metadata
Install
npm install @standardagents/google @standardagents/specUsage
import { google } from '@standardagents/google';
const provider = google({
apiKey: process.env.GOOGLE_API_KEY!,
});
const result = await provider.generate({
model: 'gemini-2.5-flash',
messages: [
{
role: 'user',
content: 'Write a one sentence summary of Saturn.',
},
],
});
console.log(result.content);
console.log(result.usage?.cost);Factory
The package exports:
google(config)- provider factoryGoogleProvider- provider classgoogleProviderOptions- Zod schema for provider-specific options- pricing helpers from
@standardagents/google/pricing
Factory config follows ProviderFactoryConfig from @standardagents/spec:
type ProviderFactoryConfig = {
apiKey: string;
baseUrl?: string;
timeout?: number;
};Supported Features
The provider exposes capabilities per model where available. In practice:
- Gemini models support text generation, streaming, tool calling, and multimodal input
- Gemma hosted models support text and selected multimodal inputs, with more limited tool support
- Imagen models support image generation/edit-style requests and are handled as non-streaming image models
Use getModels() and getModelCapabilities() to inspect the currently available surface:
const models = await provider.getModels?.();
const capabilities = await provider.getModelCapabilities?.('gemini-2.5-pro');Provider Options
This package validates Google-specific provider options through google.providerOptions.
Common options:
candidateCountresponseModalitiessafetySettingsthinkingConfigimageConfignumberOfImagesaspectRationegativePromptguidanceScaleoutputMimeTypelanguageeditMode
Example:
const result = await provider.generate({
model: 'gemini-2.5-pro',
messages: [
{ role: 'user', content: 'Return valid JSON with a title and summary.' },
],
responseFormat: {
type: 'json',
schema: {
type: 'object',
properties: {
title: { type: 'string' },
summary: { type: 'string' },
},
required: ['title', 'summary'],
},
},
providerOptions: {
candidateCount: 1,
safetySettings: [
{ category: 'HARM_CATEGORY_HARASSMENT', threshold: 'BLOCK_ONLY_HIGH' },
],
},
});Images
For multimodal Gemini requests, pass Standard Agents image parts or image attachments and the provider will translate them to Google inline parts. For Imagen requests, the provider will route through the image generation path automatically when the target model is an Imagen model.
Tool results carry images and files as parts in ProviderToolMessage.content. Custom providers read these parts from content. The Google provider transforms image parts at send time:
- Gemini 3 series models keep image data nested inside
functionResponse.parts - Older Google chat models receive a text-only
functionResponse, with image attachments lifted into sibling inline image parts so the request remains accepted by those models
Debugging
Use inspectRequest() to view the transformed Google-native request body:
const inspected = await provider.inspectRequest?.({
model: 'gemini-2.5-flash',
messages: [{ role: 'user', content: 'hello' }],
});
console.log(inspected?.body);Notes
- Model IDs are normalized so variants like
google/...,models/..., andpublishers/google/models/...resolve to the same pricing and capability entries where possible. - Cost is computed from Google usage metadata and pricing tables when available; Google does not currently return a direct monetary cost field for Gemini requests.
- The same pricing helpers are exported from the package root and the pure
@standardagents/google/pricingsubpath for consumers that need identical cost math without importing provider runtime code. - Gemini thought signatures attached to tool-call parts are preserved through Standard Agents history so multi-step Google tool calling can continue across turns.
Reasoning level zero
For reasoning level 0, the provider sends thinkingBudget: 0 to Gemini 2.5
Flash and Flash-Lite. The provider sends thinkingLevel: "minimal" to Gemma 4
to disable thinking. Gemini 2.5 Pro and Gemini 3 or later cannot disable
thinking. For level 0, the provider sends thinkingBudget: 128 to Gemini 2.5 Pro.
The provider sends thinkingLevel: "low" to Gemini 3 Pro, Gemini 3.1 Pro,
Gemini 3.8, and Gemini 4 or later. The provider sends thinkingLevel: "minimal"
to other Gemini 3 models. An unset level preserves native thinking options.
See Gemini thinking and Gemma thinking controls.
When a reasoning level is set, unknown capabilities use the spec's no-control default.
The provider removes native thinking effort and token budgets in this case.
Other thinking options, including includeThoughts, remain in the request.
