Type Alias: SystemPrompt<TMetadata>

type SystemPrompt<TMetadata> = 
  | string
  | {
  content: string;
  metadata?: TMetadata;
};

type SystemPrompt<TMetadata> = 
  | string
  | {
  content: string;
  metadata?: TMetadata;
};

Defined in: packages/ai/src/system-prompts.ts:39

A single entry in .

Accepts a plain string (the common case) or a structured object that lets providers attach typed metadata to the prompt — e.g. Anthropic for prompt caching, future per-prompt safety overrides for Gemini, etc.

At the chat call site, is narrowed by the adapter via . Providers that don't declare one inherit the default , which makes the field carry no meaningful value: TS only accepts there, and provider-foreign metadata that reaches an adapter via JS / is silently dropped, never written to the wire. For type-safe per-provider metadata, refer to the provider's interface (e.g. ).

Type Parameters

TMetadata

Examples

// The 90% case — plain strings work everywhere.
  systemPrompts: ['Be concise.', 'Cite sources.']

// The 90% case — plain strings work everywhere.
  systemPrompts: ['Be concise.', 'Cite sources.']

// Provider-specific metadata via the object form. No `satisfies` cast
  // is needed — the adapter narrows the `metadata` field's type at the
  // call site so users get autocomplete and structural checking
  // automatically.
  import { anthropicText } from '@tanstack/ai-anthropic'

  chat({
    adapter: anthropicText(),
    systemPrompts: [
      {
        content: 'Stable instructions — cache me.',
        metadata: { cache_control: { type: 'ephemeral' } },
      },
      'Volatile per-request instruction.',
    ],
  })

// Provider-specific metadata via the object form. No `satisfies` cast
  // is needed — the adapter narrows the `metadata` field's type at the
  // call site so users get autocomplete and structural checking
  // automatically.
  import { anthropicText } from '@tanstack/ai-anthropic'

  chat({
    adapter: anthropicText(),
    systemPrompts: [
      {
        content: 'Stable instructions — cache me.',
        metadata: { cache_control: { type: 'ephemeral' } },
      },
      'Volatile per-request instruction.',
    ],
  })

SystemPrompt

Type Alias: SystemPrompt<TMetadata>#

Type Parameters#

TMetadata#

Examples#

Type Alias: SystemPrompt<TMetadata>

Type Parameters

TMetadata

Examples