@ank1015/agents-provider-gemini-spec

Static Gemini provider metadata for the @ank1015/agents packages.

This package contains no live Gemini client. It provides provider identity, config types, an opinionated Gemini Interactions API option surface, provider-specific type augmentation, tool support helpers, native message typing, and a static model catalog.

Install

pnpm add @ank1015/agents-provider-gemini-spec

What This Package Provides

• GEMINI_PROVIDER provider id.
• geminiProviderConfigSchema for provider config validation.
• GeminiProviderOptions for Gemini Interactions API request options not owned by the generic LLM layer.
• GeminiNativeMessage for stateless Interactions responses with replayable steps.
• GEMINI_MODELS, GeminiModelId, getGeminiModel, and isGeminiModelId.
• geminiToolDefinitionSchema and assertGeminiToolsSupported.
• Contract augmentation for @ank1015/agents-contracts.

Provider Config

Gemini provider config uses a secret reference for the API key:

import {
  GEMINI_PROVIDER,
  geminiProviderConfigSchema,
} from '@ank1015/agents-provider-gemini-spec';

const config = geminiProviderConfigSchema.parse({
  provider: GEMINI_PROVIDER,
  apiKey: {
    type: 'env',
    name: 'GEMINI_API_KEY',
  },
});

Callers that already have a key from another secret source can pass a direct value reference:

const config = geminiProviderConfigSchema.parse({
  provider: GEMINI_PROVIDER,
  apiKey: {
    type: 'value',
    value: geminiKey,
  },
});

Provider Options

GeminiProviderOptions intentionally exposes a small Interactions API subset. The generic LLM layer owns model, input, stream, system_instruction, tools, store, and previous_interaction_id.

The option surface currently includes:

• generation_config.thinking_level
• generation_config.thinking_summaries
• generation_config.max_output_tokens
• generation_config.tool_choice
• generation_config.stop_sequences
• generation_config.seed
• generation_config.temperature
• generation_config.top_p
• generation_config.top_k
• response_format for text output and JSON-schema structured output.
• built_in_tools for Gemini-managed tools: Google Search, Google Maps, Code Execution, URL Context, and File Search.

Generic request.tools remains function-tool only in v1. assertGeminiToolsSupported rejects generic custom grammar tools; use providerOptions.response_format with mime_type: "application/json" for structured output.

built_in_tools is intentionally separate from request.tools:

const providerOptions = {
  built_in_tools: [
    { type: 'google_search' },
    { type: 'code_execution' },
  ],
};

The Gemini runtime adapter will combine these Gemini-managed tools with converted generic function tools when building the Interactions API tools array.

Model Catalog

Runtime support is catalog-only:

| Model | Model id | Input | Context | Max output | Input / Cached Input / Output | | --- | --- | --- | --- | --- | --- | | Gemini 3.5 Flash | gemini-3.5-flash | Text, image | 1,048,576 tokens | 65,536 tokens | $1.50 / $0.15 / $9.00 | | Gemini 3.1 Pro Preview | gemini-3.1-pro-preview | Text, image | 1,048,576 tokens | 65,536 tokens | $2.00 / $0.20 / $12.00 up to 200k prompt tokens | | Gemini 3.1 Flash-Lite | gemini-3.1-flash-lite | Text, image | 1,048,576 tokens | 65,536 tokens | $0.25 / $0.025 / $1.50 |

Gemini 3.1 Pro Preview also includes pricingTiers metadata for prompts over 200k tokens: $4.00 input, $0.40 cached input, and $18.00 output per 1M tokens.

All models use 0 as the cache write cost because the shared usage model does not represent hourly cache storage costs.

Type Augmentation

Importing this package augments @ank1015/agents-contracts so Gemini requests can narrow provider-specific fields:

import type { LLMRequest } from '@ank1015/agents-contracts';
import type { GeminiProvider } from '@ank1015/agents-provider-gemini-spec';

const request: LLMRequest<GeminiProvider> = {
  provider: 'gemini',
  modelId: 'gemini-3.5-flash',
  messages: [],
};

Versioning

This package is currently 0.1.1. Until 1.0.0, model metadata and provider option types may evolve as the surrounding agent runtime settles.