Skip to main content

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