SystemPrompt

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

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

A single entry in chat({ systemPrompts: [...] }).

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

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

Type Parameters#

TMetadata#

TMetadata = unknown

Examples#

// 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.',
    ],
  })