Prompts API

Prompt definition and execution APIs

Prompts API

Prompts in Genkit provide a structured way to define and manage model interactions with built-in support for templates, schemas, and tool integration.

definePrompt()

Defines and registers a prompt based on a function or template.

Signature:

definePrompt<
  I extends z.ZodTypeAny = z.ZodTypeAny,
  O extends z.ZodTypeAny = z.ZodTypeAny,
  CustomOptions extends z.ZodTypeAny = z.ZodTypeAny
>(
  registry: Registry,
  options: PromptConfig<I, O, CustomOptions>,
  templateOrFn?: string | PromptFn<I>
): ExecutablePrompt<z.infer<I>, O, CustomOptions>

Parameters

options · PromptConfig · required

Prompt configuration

Show properties

name · string · required

Unique prompt identifier

model · ModelArgument

Model to use for this prompt

input · { schema: z.ZodTypeAny, default?: any }

Input schema and default values

output · { schema?: z.ZodTypeAny, format?: string }

Output schema and format specification

config · GenerationCommonConfig

Model configuration (temperature, maxOutputTokens, etc.)

messages · string | MessagesFunction

Template string or function that returns messages

tools · ToolAction[]

Tools available to the prompt

description · string

Human-readable description

templateOrFn · string | PromptFn

Template string or function (deprecated - use options.messages instead)

Returns

prompt · ExecutablePrompt

An executable prompt that can be called like a function

Show methods

() · (input?: I, opts?: PromptGenerateOptions) => Promise<GenerateResponse>

Execute the prompt and generate a response

render() · (input?: I, opts?: PromptGenerateOptions) => Promise<GenerateOptions>

Render the prompt to GenerateOptions without executing

stream() · (input?: I, opts?: PromptGenerateOptions) => GenerateStreamResponse

Execute the prompt with streaming

asTool() · () => Promise<ToolAction>

Convert the prompt to a tool

ref · { name: string }

Reference object with prompt name

Example

import { definePrompt } from '@genkit-ai/ai';
import { z } from 'zod';

// Simple template
const greetingPrompt = definePrompt(
  registry,
  {
    name: 'greeting',
    input: {
      schema: z.object({ name: z.string() }),
    },
    messages: 'Hello, {{name}}! How are you today?',
  }
);

const response = await greetingPrompt({ name: 'Alice' });
console.log(response.text);

// With function
const summaryPrompt = definePrompt(
  registry,
  {
    name: 'summary',
    model: 'googleai/gemini-2.0-flash-exp',
    input: {
      schema: z.object({ text: z.string() }),
    },
    output: {
      schema: z.object({ summary: z.string() }),
      format: 'json',
    },
    messages: async (input) => [
      {
        role: 'user',
        content: [{ text: `Summarize this text: ${input.text}` }],
      },
    ],
  }
);

const result = await summaryPrompt({ text: 'Long article...' });
const { summary } = result.output();

prompt()

Looks up a prompt by name (from .prompt files or defined prompts).

Signature:

prompt<
  I extends z.ZodTypeAny = z.ZodTypeAny,
  O extends z.ZodTypeAny = z.ZodTypeAny,
  CustomOptions extends z.ZodTypeAny = z.ZodTypeAny
>(
  registry: Registry,
  name: string,
  options?: { variant?: string; dir?: string }
): Promise<ExecutablePrompt<z.infer<I>, O, CustomOptions>>

Parameters

name · string · required

Prompt name (without .prompt extension)

options · object

Show properties

variant · string

Prompt variant to load (e.g., ‘long’, ‘short’)

dir · string · default: "'./prompts'"

Directory containing prompt files

Example

import { prompt } from '@genkit-ai/ai';

// Load a .prompt file
const greetingPrompt = await prompt(registry, 'greeting');
const response = await greetingPrompt({ name: 'World' });

// Load a variant
const longGreeting = await prompt(registry, 'greeting', { variant: 'long' });

loadPromptFolder()

Loads all .prompt files from a directory.

Signature:

loadPromptFolder(
  registry: Registry,
  directory: string,
  namespace?: string
): void

Parameters

directory · string · required

Path to directory containing .prompt files

namespace · string · default: "''"

Namespace prefix for loaded prompts

Example

import { loadPromptFolder } from '@genkit-ai/ai';

// Load prompts from ./prompts directory
loadPromptFolder(registry, './prompts');

// Load with namespace
loadPromptFolder(registry, './custom-prompts', 'custom');
// Prompts will be accessible as 'custom/promptName'

Dotprompt Files

Genkit supports .prompt files using a YAML-like format:

---
model: googleai/gemini-2.0-flash-exp
input:
  schema:
    name: string
    style?: string
output:
  format: json
  schema:
    greeting: string
config:
  temperature: 0.7
---

{{#if style}}{{style}} greeting for{{else}}Hello{{/if}} {{name}}!

Usage

// Automatically loaded from ./prompts/greeting.prompt
const greeting = await ai.prompt('greeting');

const response = await greeting({ name: 'Alice', style: 'Formal' });
const { greeting: text } = response.output();

Prompt Types

PromptConfig

interface PromptConfig<
  I extends z.ZodTypeAny = z.ZodTypeAny,
  O extends z.ZodTypeAny = z.ZodTypeAny,
  CustomOptions extends z.ZodTypeAny = z.ZodTypeAny
> {
  name: string;
  model?: ModelArgument<CustomOptions>;
  input?: {
    schema?: I;
    default?: z.infer<I>;
  };
  output?: {
    schema?: O;
    format?: string;
  };
  config?: z.infer<CustomOptions>;
  messages?: string | MessagesFunction<I>;
  tools?: ToolAction[];
  description?: string;
}

ExecutablePrompt

interface ExecutablePrompt<I = any, O = any, CustomOptions = any> {
  (input?: I, opts?: PromptGenerateOptions<O, CustomOptions>): Promise<GenerateResponse<O>>;
  
  render(
    input?: I,
    opts?: PromptGenerateOptions<O, CustomOptions>
  ): Promise<GenerateOptions<O, CustomOptions>>;
  
  stream(
    input?: I,
    opts?: PromptGenerateOptions<O, CustomOptions>
  ): GenerateStreamResponse<O>;
  
  asTool(): Promise<ToolAction<I, O>>;
  
  ref: { name: string };
}

PromptGenerateOptions

Options when executing a prompt:

interface PromptGenerateOptions<O = any, CustomOptions = any> {
  model?: ModelArgument<CustomOptions>;
  config?: z.infer<CustomOptions>;
  docs?: Document[];
  messages?: MessageData[];
  // Override output settings
  output?: {
    schema?: z.ZodTypeAny;
    format?: string;
  };
}

Usage with Genkit Instance

import { genkit } from 'genkit';
import { z } from 'zod';

const ai = genkit({ plugins: [googleAI()] });

// Define a prompt
const myPrompt = ai.definePrompt(
  {
    name: 'myPrompt',
    input: { schema: z.object({ topic: z.string() }) },
    messages: 'Tell me about {{topic}}',
  }
);

// Use the prompt
const response = await myPrompt({ topic: 'TypeScript' });

// Look up a .prompt file
const dotPrompt = ai.prompt('greeting');
const result = await dotPrompt({ name: 'World' });

See Also

• Genkit API
• Models API
• Tools API