Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/firebase/genkit/llms.txt

Use this file to discover all available pages before exploring further.

​
Plugin API Reference

Complete reference for the Genkit Plugin API, including interfaces, types, and helper functions.

​
Core Plugin Interfaces

​
PluginProvider

The main interface for defining a plugin: 
export interface PluginProvider {
  name: string;
  initializer: () =>
    | InitializedPlugin
    | void
    | Promise<InitializedPlugin | void>;
  resolver?: (action: ActionType, target: string) => Promise<void>;
  listActions?: () => Promise<ActionMetadata[]>;
}
Properties:
  • name - Unique plugin identifier (e.g., 'anthropic', 'my-plugin')
  • initializer - Function that returns registered actions or void
  • resolver - Optional function to resolve actions dynamically
  • listActions - Optional function to list available actions for discovery

​
InitializedPlugin

Return type of the plugin initializer: 
export interface InitializedPlugin {
  models?: Action<z.ZodTypeAny, z.ZodTypeAny>[];
  retrievers?: Action<z.ZodTypeAny, z.ZodTypeAny>[];
  embedders?: Action<z.ZodTypeAny, z.ZodTypeAny>[];
  indexers?: Action<z.ZodTypeAny, z.ZodTypeAny>[];
  evaluators?: Action<z.ZodTypeAny, z.ZodTypeAny>[];
}
Properties:
  • models - Array of model actions
  • retrievers - Array of retriever actions
  • embedders - Array of embedder actions
  • indexers - Array of indexer actions
  • evaluators - Array of evaluator actions

​
ActionType

Types of actions that can be registered: 
type ActionType = 
  | 'model'
  | 'retriever'
  | 'embedder'
  | 'indexer'
  | 'evaluator'
  | 'flow'
  | 'tool';

​
Plugin Creation Functions

​
genkitPlugin (API v1)

Legacy plugin creation function: 
function genkitPlugin(
  name: string,
  initializer: (ai: Genkit) => Promise<void> | void,
  resolver?: (ai: Genkit, actionType: ActionType, actionName: string) => Promise<void>,
  listActions?: () => Promise<ActionMetadata[]>
): GenkitPlugin
Parameters:
  • name - Plugin name
  • initializer - Function to register actions with Genkit instance
  • resolver - Optional dynamic action resolver
  • listActions - Optional action listing function
Example: 
import { genkitPlugin } from 'genkit/plugin';

export function myPlugin(options) {
  return genkitPlugin(
    'my-plugin',
    async (ai) => {
      ai.defineModel(/* ... */);
    }
  );
}
New plugin creation function with direct model usage support: 
function genkitPluginV2(config: {
  name: string;
  init: () => Promise<InitializedPlugin> | InitializedPlugin;
  resolve?: (actionType: ActionType, name: string) => Action | undefined;
  list?: () => Promise<ActionMetadata[]>;
}): GenkitPluginV2
Parameters:
  • name - Plugin name
  • init - Function returning actions to register
  • resolve - Optional dynamic action resolver
  • list - Optional action listing function
Example: 
import { genkitPluginV2 } from 'genkit/plugin';

export function myPlugin(options) {
  return genkitPluginV2({
    name: 'my-plugin',
    init: async () => {
      return [createModel('model-1'), createModel('model-2')];
    },
    resolve: (actionType, name) => {
      if (actionType === 'model') {
        return createModel(name);
      }
    },
  });
}

​
Model API

​
ModelAction

Model action interface: 
interface ModelAction {
  name: string;
  label?: string;
  configSchema: z.ZodTypeAny;
  info?: ModelInfo;
  generate: (
    input: GenerateRequest,
    streamingCallback?: (chunk: GenerateResponseChunk) => void
  ) => Promise<GenerateResponseData>;
}

​
ModelInfo

Model capability information: 
interface ModelInfo {
  supports?: {
    multiturn?: boolean;      // Multi-turn conversations
    media?: boolean;          // Image/audio input
    tools?: boolean;          // Tool calling
    toolChoice?: boolean;     // Tool choice control
    systemRole?: boolean;     // System messages
    constrained?: 'all' | 'structured' | false;  // Structured output
  };
}

​
GenerateRequest

Input to model generation: 
interface GenerateRequest {
  messages: MessageData[];
  config?: Record<string, any>;
  tools?: ToolDefinition[];
  output?: {
    schema?: z.ZodTypeAny;
    format?: 'json' | 'text';
  };
}

​
GenerateResponseData

Model generation output: 
interface GenerateResponseData {
  message: MessageData;
  usage?: {
    inputTokens?: number;
    outputTokens?: number;
    totalTokens?: number;
  };
  finishReason: 'stop' | 'length' | 'tool-call' | 'error' | 'blocked' | 'unknown';
}

​
MessageData

Message structure: 
interface MessageData {
  role: 'user' | 'model' | 'system' | 'tool';
  content: Part[];
}

type Part = 
  | { text: string }
  | { media: { url: string; contentType?: string } }
  | { toolRequest: ToolRequest }
  | { toolResponse: ToolResponse }
  | { custom: any };

​
modelRef

Create a model reference: 
function modelRef<ConfigSchema extends z.ZodTypeAny>(params: {
  name: string;
  config?: z.infer<ConfigSchema>;
  configSchema?: ConfigSchema;
  info?: ModelInfo;
}): ModelReference<ConfigSchema>
Example: 
import { modelRef } from 'genkit/model';

export const myModel = modelRef({
  name: 'my-provider/my-model',
  config: { temperature: 0.7 },
  configSchema: MyConfigSchema,
});

​
Embedder API

​
EmbedderAction

Embedder action interface: 
interface EmbedderAction {
  name: string;
  info?: {
    dimensions?: number;
    label?: string;
  };
  embed: (input: EmbedRequest) => Promise<EmbedResponse>;
}

​
EmbedRequest

Input to embedder: 
interface EmbedRequest {
  content: Document[];
  options?: Record<string, any>;
}

​
EmbedResponse

Embedder output: 
interface EmbedResponse {
  embeddings: Embedding[];
}

interface Embedding {
  embedding: number[];
}

​
embedderRef

Create an embedder reference: 
function embedderRef<ConfigSchema extends z.ZodTypeAny = z.ZodTypeAny>(params: {
  name: string;
  config?: z.infer<ConfigSchema>;
  configSchema?: ConfigSchema;
}): EmbedderReference<ConfigSchema>

​
Retriever API

​
RetrieverAction

Retriever action interface: 
interface RetrieverAction {
  name: string;
  retrieve: (
    query: Document,
    options?: Record<string, any>
  ) => Promise<{ documents: Document[] }>;
}

​
CommonRetrieverOptionsSchema

Common retriever options: 
const CommonRetrieverOptionsSchema = z.object({
  k: z.number().optional(),  // Number of results
});

​
retrieverRef

Create a retriever reference: 
function retrieverRef<ConfigSchema extends z.ZodTypeAny = z.ZodTypeAny>(params: {
  name: string;
  info?: {
    label?: string;
  };
  configSchema?: ConfigSchema;
}): RetrieverReference<ConfigSchema>

​
Indexer API

​
IndexerAction

Indexer action interface: 
interface IndexerAction {
  name: string;
  index: (
    documents: Document[],
    options?: Record<string, any>
  ) => Promise<void>;
}

​
indexerRef

Create an indexer reference: 
function indexerRef<ConfigSchema extends z.ZodTypeAny = z.ZodTypeAny>(params: {
  name: string;
  info?: {
    label?: string;
  };
  configSchema?: ConfigSchema;
}): IndexerReference<ConfigSchema>

​
Document API

​
Document

Document class for text/data: 
class Document {
  static fromText(text: string, metadata?: Record<string, any>): Document;
  static fromData(data: any, dataType: string, metadata?: Record<string, any>): Document;
  
  text: string;
  metadata?: Record<string, any>;
  
  toJSON(): any;
}
Example: 
import { Document } from 'genkit';

const doc = Document.fromText('Hello world', {
  source: 'example',
  timestamp: Date.now(),
});

​
Configuration Schemas

​
GenerationCommonConfigSchema

Common generation config: 
const GenerationCommonConfigSchema = z.object({
  temperature: z.number().min(0).max(2).optional(),
  maxOutputTokens: z.number().optional(),
  topK: z.number().optional(),
  topP: z.number().min(0).max(1).optional(),
  stopSequences: z.array(z.string()).optional(),
});

​
Utility Functions

​
getBasicUsageStats

Calculate token usage: 
function getBasicUsageStats(
  input: MessageData[],
  output: MessageData
): {
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
}

​
modelActionMetadata

Create model action metadata: 
function modelActionMetadata(params: {
  name: string;
  info: ModelInfo;
}): ActionMetadata

​
Type Guards

​
isModelAction

function isModelAction(action: any): action is ModelAction

​
isRetrieverAction

function isRetrieverAction(action: any): action is RetrieverAction

​
Complete Plugin Example

import {
  genkitPluginV2,
  type GenkitPluginV2,
} from 'genkit/plugin';
import {
  modelRef,
  type ModelReference,
  type GenerateRequest,
  type GenerateResponseData,
} from 'genkit/model';
import { z } from 'genkit';

const ConfigSchema = z.object({
  temperature: z.number().min(0).max(2).optional(),
});

type MyPluginOptions = {
  apiKey?: string;
};

function myPlugin(options?: MyPluginOptions): GenkitPluginV2 {
  const apiKey = options?.apiKey || process.env.MY_API_KEY;

  return genkitPluginV2({
    name: 'my-plugin',
    init: async () => {
      return [
        {
          name: 'my-plugin/model',
          label: 'My Model',
          configSchema: ConfigSchema,
          info: {
            supports: {
              multiturn: true,
              tools: true,
            },
          },
          async generate(
            input: GenerateRequest,
            streamingCallback?
          ): Promise<GenerateResponseData> {
            // Implementation
            return {
              message: {
                role: 'model',
                content: [{ text: 'Response' }],
              },
              finishReason: 'stop',
            };
          },
        },
      ];
    },
  });
}

// Export with model helper
export const myProvider = myPlugin as typeof myPlugin & {
  model: (name: string) => ModelReference<typeof ConfigSchema>;
};

myProvider.model = (name: string) => {
  return modelRef({
    name: `my-plugin/${name}`,
    configSchema: ConfigSchema,
  });
};

export default myProvider;

Build docs developers (and LLMs) love

Get started for freeTalk to us