Reference

Preview a Prompt (client-side)

SDK: mgmt.intellects.previewPrompt(configId, ks, opts). Requires an admin KS. This call only reads data — it never writes.

The returned text is rendered client-side. It's a replica of the author layer (prompts[] + base_directive + glossary), assembled by mirroring the server's own prompt-rendering rules. Use it to check a prompt template before shipping it.

By default, it fetches and renders the intellect's current stored config. Pass draftPrompts/draftBaseDirective/draftGlossary to preview an unsaved edit instead.

const p = await mgmt.intellects.previewPrompt(configId, adminKs, {
  requestVars: { sys__user_id: 'learner-123', topic: 'billing' },
});
p.text;                // the assembled system prompt, `{{var}}` interpolated
p.unresolvedVariables; // names left literal because no value was supplied
p.warnings;             // present ONLY when a reserved variable is unresolved (see below)

It is not byte-exact with the live prompt. Server-injected capability-conditional blocks (video_gallery/avatar_show_content/web_search_enabled/user_properties) are not reproduced. And the sys__* values you pass via requestVars only simulate what the server sets per turn — they are not a live read.

Reserved variables the server sets per turn (always available to {{...}} regardless of allow_client_variables):

Variable	Notes
`sys__thread_id`	Current conversation thread id
`sys__message_id`	Current message id
`sys__user_id`	Bound end-user id — see `Sessions.createConversationToken({userId})`
`sys__user_message`	The user's current turn text
`sys__is_new_thread`	`true` on the first turn of a thread
`sys__context_id`	The category/entry id the current context is scoped to
`sys__context_type`	The type of that context (e.g. an `entry` vs. a `category`)
`sys__avatar_enabled`	Whether the current thread has a live avatar attached
`sys__avatar_share_screen_enabled`	Whether the current avatar session has screen-share analysis enabled
`sys__ks`	The raw session token. Never reference this in a prompt that could be echoed back to a user or logged. It is a live credential.
`sys__user_obj.first_name` / `.last_name` / `.title` / `.company` / `.gender` / `.email`	Attributes of the bound-user object. The rendered preview from `previewPrompt()` carries a `reserved_user_attr_unresolved` warning when a prompt references these — treat it as a hard stop before shipping.
`secrets.NAME`	A named secret configured on the intellect (write-only — `previewPrompt()` never has access to the raw value, so it cannot confirm one is set)

Unresolvable reserved-variable warnings: say a prompt references one of the variables above, and no value is available in the simulated context (no requestVars entry, or an explicit null/undefined). In that case previewPrompt() returns a warnings[] entry naming the variable and explaining why, instead of silently rendering the placeholder as empty text.

warnings is an additive field. It appears only when there's something to report, so a fully-resolved preview's return shape stays the same.

const p = await mgmt.intellects.previewPrompt(configId, adminKs, {
  draftPrompts: [{ key: 'greet', headerTemplate: 'Greeting', value: 'Hi {{sys__user_obj.first_name}}', type: 'custom' }],
  draftBaseDirective: 'You are Ron.',
  draftGlossary: '',
  requestVars: {}, // no bound user simulated
});
p.warnings;
// [{
//   severity: 'warning',
//   code: 'reserved_user_attr_unresolved',
//   message: '`{{sys__user_obj.first_name}}` has no bound value in this preview\'s
//              requestVars. Referencing an unbound sys__user_obj.* attribute in a
//              LIVE turn currently causes a silent turn failure, not an empty render —
//              bind a user (Sessions.createConversationToken({userId})) or supply
//              "sys__user_obj.first_name" in requestVars to simulate the bound case
//              before shipping this prompt.'
// }]

Supplying the value in requestVars (e.g. { 'sys__user_obj.first_name': 'Jane' }, or { sys__user_id: 'learner-123' }) simulates the bound case and clears the warning.

Warning `code`	Fires for
`reserved_var_unresolved`	A scalar `sys__*` variable
`reserved_user_attr_unresolved`	A `sys__user_obj.*` attribute — this is the class of reference that can crash a live turn
`reserved_secret_unresolved`	A `secrets.*` reference. `previewPrompt()` can't verify these: it only ever sees the rendered text, never the raw secret value

Doc	What it adds
Agent Components · Create and Configure an Intellect	The `prompts[]`/`base_directive`/`glossary` fields this preview renders
Agent Components	The Agent Components index

Preview a Prompt (client-side)

Related docs