Skip to main content

​
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
​
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

​
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

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us