Prompts

A prompt is a Handlebars template with full version history. It is the core unit of Raison — everything else (agents, environments, deployments) exists to organize and deliver prompts.

What a Prompt Is

A prompt has:

A name — human-readable, used for lookups in the SDK (e.g., "system-prompt")
Content — Handlebars template text ({{variable}} syntax for dynamic values)
A version history — every published change is tracked as an immutable version
Deployments — each environment can run a specific version of the prompt

The Three States

At any point, a prompt exists in one or more of these states:

State	Description
Draft	An unpublished edit. Changes are saved and tracked but not delivered to the SDK. Multiple draft edits are tracked in revision history.
Version	An immutable snapshot created when a draft is published. Versions are numbered sequentially (v1, v2, v3, ...) and never modified.
Deployment	The active version of this prompt in a specific environment. Only one version can be deployed per prompt per environment at a time.

Lifecycle: From Draft to Production

Create a prompt inside an agent in the dashboard.
Edit the draft — write your Handlebars template. Changes are saved but not yet live.
Publish the draft — creates an immutable version (v1). The draft is now v1.
Deploy v1 to Development — instantly available to SDK instances on that environment.
Test in Development — your app connected with rsn_development_xxx picks it up.
Promote to Staging — deploy v1 to Staging when ready.
Promote to Production — deploy v1 to Production. It goes live within milliseconds.
Create a new draft — once published, the version is immutable. To make changes, create a new draft. Publishing creates v2. Deploy v2 on your schedule.

Key point: Deploying a prompt creates no new version. Publishing a draft creates a new version. Deploying picks which existing version to make active.

Version Immutability

Versions are permanent snapshots. Once v3 is published, it never changes. If you deploy v3 to Production and later discover an issue, you do not modify v3 — you either:

Deploy v2 (roll back), or
Edit the draft, publish v4, and deploy v4

This gives you a complete, auditable history of every prompt that has ever run in production.

Revision History

Every change to a draft is saved in revision history before publishing. If you make ten edits to a draft before publishing, all ten revisions are preserved. This is separate from version history — revisions are draft-level checkpoints, while versions are published snapshots.

Variables

Prompt content uses Handlebars syntax for dynamic values:

You are a helpful assistant for {{companyName}}.
The user's name is {{userName}}.
Today's date is {{date}}.

Pass variables when calling render:

const message = await raison.render("PROMPT_ID", {
  companyName: "Acme Corp",
  userName: "Alice",
  date: new Date().toISOString(),
});

See the Templating Guide for the full Handlebars feature set.

Finding Prompt IDs

Open your project in the dashboard.
Click on an agent.
Click on a prompt.
The prompt ID is shown at the top of the prompt detail — click to copy.

Prompt IDs are stable. The same ID works in Development, Staging, and Production — the deployed content differs, but the ID is the same.

Agents

Environments