Prompt Configuration

Overview

The Prompt Configuration System is a unified, versioned system for all LLM prompts used by agents — system prompts, welcome messages, KB context injection templates, and additional prompt types — managed through a single governed system. Key features:

Prompt type registry enforcing what types exist and how they behave
Per-agent prompt overrides with fixed (static text) or generated (LLM-driven) modes
System defaults used when no agent-level override exists
Dynamic variables ({{variable_name}}) injected at runtime
Semantic versioning (major.minor) with changelog on all configs
Streaming configuration at agent and request level

Data Model

prompt_type_registry

Governs all valid prompt types. No prompt config can reference a type not in this table (FK constraint).

Column	Type	Description
`key`	VARCHAR(100) PK	Machine identifier (immutable after creation)
`label`	VARCHAR(255)	Human-readable name
`description`	TEXT	Purpose and usage guidance
`category`	VARCHAR(50)	Grouping: `chat`, `rag`, `engagement`, `tools`
`supported_modes`	TEXT[]	Valid modes: `['fixed']`, `['generated']`, or both
`default_mode`	VARCHAR(20)	Mode when not explicitly specified
`required`	BOOLEAN	Whether every agent must have this configured
`deprecated_at`	TIMESTAMP	Non-null means deprecated

Initial registry entries:

Key	Category	Modes	Required
`system`	`chat`	`fixed`, `generated`	true
`welcome`	`chat`	`fixed`, `generated`	false
`kb_context_injection`	`rag`	`fixed`	false
`creator_analysis`	`chat`	`generated`	false

bot_prompt_configs

Per-agent prompt overrides. One row per prompt type per agent. UNIQUE on (bot_id, prompt_type).

Column	Type	Description
`id`	UUID PK
`bot_id`	UUID FK
`prompt_type`	VARCHAR FK -> prompt_type_registry
`mode`	VARCHAR(20)	`fixed` or `generated`
`content`	TEXT	Literal text (mode=fixed, required)
`prompt`	TEXT	LLM instruction (mode=generated, required)
`enabled`	BOOLEAN	Toggle without deleting config
`metadata`	JSONB	Extensible config
`version_major`, `version_minor`	INTEGER	Semantic version

system_prompt_defaults

Platform-wide defaults. One row per prompt type. Used when no bot-level override exists.

conversation_variables

Per-conversation resolved dynamic variables.

Column	Description
`conversation_id`	PK + FK -> conversations
`initial_variables`	Variables set at conversation start (immutable)
`variables`	Current merged state
`sensitive_variables`	Server-set variables (encrypted, never returned)

Three-Tier Resolution Flow

This three-tier fallback ensures the system always works even if config data is missing.

Welcome Message Flow

Fixed Mode
Generated Mode
No Welcome

POST /bots/:id/conversations
  -> Create conversation record
  -> Resolve + store variables
  -> Resolve welcome config (bot -> system default -> no-op)
  -> Render content with variables
  -> Return welcome message (no loading state needed)
  -> Save as first assistant message

Cost: None (no LLM call).

POST /bots/:id/conversations
  -> Create conversation record
  -> Resolve + store variables
  -> Resolve welcome config
  -> Render prompt template with variables
  -> Call LLM with rendered prompt + system prompt as context
  -> If streaming: stream response
  -> Return generated welcome message
  -> Save as first assistant message

Cost: Calls record_external_cost_event() with operation welcome_message_generation.

If welcome prompt type has enabled=false at bot level, or no config/default exists, the conversation starts empty.

Versioning System

Version Numbering

Major.Minor format (e.g., 1.0, 1.3, 2.0)
Minor bump: Content edits, wording changes, variable adjustments
Major bump: Mode changes, structural changes, breaking variable contract changes

Version Bump Logic

On update:
Compare new state with current
If mode changed -> major bump (1.3 -> 2.0)
If only content/prompt/metadata changed -> minor bump (1.3 -> 1.4)
Snapshot current state into *_versions table with changelog
Update current record with new version numbers

Rollback

Restoring a previous version creates a new version entry with changelog “Rolled back to vX.Y”. History is never rewritten.

Streaming Configuration

Effective Behavior

effective_streaming = bot.streaming_enabled AND request.stream === true

Channel	Sends `stream`
Web widget / landing page	`true`
Telegram / WhatsApp / Instagram	`false` (full response, then send)
Direct API caller	Caller’s choice

bots.streaming_enabled (BOOLEAN, default: true) — agent-level toggle
stream param on POST /bots/:id/chat (default: false) — client declares capability

Adding New Prompt Types

New prompt types require a DB migration with these fields:

key — unique, immutable machine identifier
label — human-readable name
description — clear explanation of purpose
category — one of chat, rag, engagement, tools
supported_modes — which modes are valid
default_mode — must be in supported_modes

Deprecation before deletion: Set deprecated_at to warn before removing. Cannot delete a type with existing bot configs or system defaults referencing it.

API Endpoints

Bot Service — Prompt Config

Method	Path	Description
GET	`/bots/:id/prompt-configs`	List all prompt configs
GET	`/bots/:id/prompt-configs/:type`	Get specific config
PUT	`/bots/:id/prompt-configs/:type`	Create or update
DELETE	`/bots/:id/prompt-configs/:type`	Remove override
GET	`/bots/:id/prompt-configs/:type/versions`	Version history
POST	`/bots/:id/prompt-configs/:type/rollback`	Rollback to version

Auth Service — Superadmin

Method	Path	Description
GET	`/admin/prompt-types`	List registry
POST	`/admin/prompt-types`	Register new type
PUT	`/admin/prompt-types/:key`	Update metadata
POST	`/admin/prompt-types/:key/deprecate`	Deprecate type
GET/PUT	`/admin/prompt-defaults/:type`	System defaults
GET	`/admin/prompt-defaults/:type/versions`	Version history
POST	`/admin/prompt-defaults/:type/rollback`	Rollback

Security

Sensitive variables: Stored encrypted via packages/shared/src/crypto.ts. Never returned in client-facing responses.
Signed context tokens: JWT with expiry; validated server-side on every use.
Prompt injection: Variables should be wrapped in quotes or XML tags in LLM prompts.
Access control: Bot prompt configs scoped to bot owner’s org (existing RBAC). Registry/defaults endpoints require superadmin.

Overview

Services

Architecture

Agent Provisioning API

Deployment

Design System (Neo)

Overview

Data Model

prompt_type_registry

bot_prompt_configs

system_prompt_defaults

conversation_variables

Three-Tier Resolution Flow

Welcome Message Flow

Versioning System

Version Numbering

Version Bump Logic

Rollback

Streaming Configuration

Effective Behavior

Adding New Prompt Types

API Endpoints

Bot Service — Prompt Config

Auth Service — Superadmin

Security

​Overview

​Data Model

​prompt_type_registry

​bot_prompt_configs

​system_prompt_defaults

​conversation_variables

​Three-Tier Resolution Flow

​Welcome Message Flow

​Versioning System

​Version Numbering

​Version Bump Logic

​Rollback

​Streaming Configuration

​Effective Behavior

​Adding New Prompt Types

​API Endpoints

​Bot Service — Prompt Config

​Auth Service — Superadmin

​Security

Overview

Data Model

prompt_type_registry

bot_prompt_configs

system_prompt_defaults

conversation_variables

Three-Tier Resolution Flow

Welcome Message Flow

Versioning System

Version Numbering

Version Bump Logic

Rollback

Streaming Configuration

Effective Behavior

Adding New Prompt Types

API Endpoints

Bot Service — Prompt Config

Auth Service — Superadmin

Security