ADR: Langfuse Prompt Folder Hierarchy¶

Status¶

Accepted

Date¶

2026-01-02

Context¶

The multi-agent router architecture (see ADR 2025-12-19) introduced a 3-level prompt hierarchy for response-generating agents. As the system grows with more prompts and agents, we need a clear folder organization in Langfuse to:

Distinguish prompt types: Response agents vs. analysis nodes vs. suggesters
Enable client-specific overrides: Some prompts need per-client customization
Support future agents: Educator, qualifier, and other response agents
Maintain consistency: Clear naming conventions across all prompts

Current State¶

Existing prompts use flat naming with rose-internal- prefix:

Current Slug	Node	Type
`rose-internal-intent-router`	intent_classifier.py	Classifier
`rose-internal-key-signals-detector`	interest_signals_detector.py	Detector
`rose-internal-visitor-profiling`	visitor_profiler.py	Detector
`rose-internal-form-extraction`	form_field_extractor.py	Extractor
`rose-internal-suggested-questions`	follow_up_suggester.py	Suggester
`rose-internal-suggested-answers`	answer_suggester.py	Suggester
`rose-internal-dialog-supervisor`	dialog_supervisor.py	Orchestrator

New response agents require 3-level hierarchy (meta-template, agent instructions, client overrides).

Decision¶

Organize Langfuse prompts into a folder hierarchy under rose-internal/ with categorical groupings:

rose-internal/
│
├── response-agents/                    # Agents that generate visitor responses
│   ├── meta-template                   # Shared template for all response agents
│   │
│   ├── redirect/                       # Redirect agent
│   │   ├── template                    # Agent template with {{lf_client_agent_instructions}}
│   │   └── instructions/               # Client-specific instructions inserted into template
│   │       ├── abtasty.com
│   │       └── other-client
│   │
│   ├── educator/                       # Future: Educator agent
│   │   ├── template
│   │   └── instructions/
│   │       └── ...
│   │
│   └── qualifier/                      # Future: Qualifier agent
│       ├── template
│       └── instructions/
│           └── ...
│
├── classifier/                         # Intent/category classification
│   └── intent                          # Intent classification
│
├── detector/                           # Signal/profile detection
│   ├── interest-signals                # Interest signal detection
│   └── visitor-profile                 # Visitor profiling
│
├── extractor/                          # Structured data extraction
│   └── form-fields                     # Form field extraction
│
├── suggester/                          # Suggestion generation
│   ├── follow-up-questions             # Follow-up question suggestions
│   └── answer-options                  # Answer option suggestions
│
└── orchestrator/                       # Workflow orchestration
    └── dialog-supervisor               # Dialog supervision

Naming Conventions¶

Slug format: Use / for folder separation, - for multi-word names
Domain names: Use as-is (e.g., abtasty.com)
Variable prefixes: lf_ (Langfuse), db_ (database), rt_ (runtime)

3-Level Hierarchy for Response Agents¶

Response agents use a 3-level prompt composition where client instructions are inserted into the agent template:

Level 1: rose-internal/response-agents/meta-template
         └── Shared template with embedded tone, guardrails, formatting

Level 2: rose-internal/response-agents/{agent}/template
         └── Agent template with {{lf_client_agent_instructions}} slot
         └── May include {{rt_request_rag_context}} if agent needs RAG

Level 3: rose-internal/response-agents/{agent}/instructions/{domain}
         └── Client-specific instructions inserted into the template

Key insight: Level 3 is not an "override" - it's instructions that get inserted into the template's {{lf_client_agent_instructions}} slot.

Standalone Prompts¶

Classifiers, detectors, extractors, suggesters, and orchestrators are standalone prompts. They don't use the 3-level hierarchy because:

They are client-agnostic (same behavior for all clients)
They don't generate visitor-facing responses
They analyze, extract, or suggest rather than respond

Consequences¶

Positive¶

Clear categorization: Prompt purpose is evident from folder path
Scalable structure: Easy to add new agents and prompt types
Co-located instructions: Client instructions live next to their agent template
Self-documenting: Folder names describe prompt function (template vs instructions)
Consistent with LangGraph nodes: Folder structure mirrors node organization

Negative¶

Migration effort: Existing prompts must be renamed/moved in Langfuse
Longer slugs: rose-internal/classifier/intent vs rose-internal-intent-router
Learning curve: Team must understand new organization

Neutral¶

Langfuse folder support: Requires Langfuse folder feature (now available)
Code updates: Node files need slug updates when prompts migrate

Alternatives Considered¶

1. Flat Structure with Prefixes¶

Keep flat naming like rose-internal-response-agents-redirect.

Rejected because: Harder to navigate as prompt count grows; no logical grouping.

2. Agent-First Hierarchy¶

Organize by agent name: rose-internal/redirect/instructions, rose-internal/redirect/abtasty.

Rejected because: Mixes response agents with analysis nodes; unclear what's a "response agent" vs other prompt types.

3. Type-First with No Subfolders¶

Use: rose-internal/classifier-intent, rose-internal/detector-interest-signals.

Rejected because: Doesn't support nested client overrides; loses folder navigation benefits.

Migration Plan¶

Phase 1: New Prompts (Current)¶

Create new prompts using the folder hierarchy: - rose-internal/response-agents/meta-template - rose-internal/response-agents/redirect/template - rose-internal/response-agents/redirect/instructions/abtasty.com

Phase 2: Migrate Existing Prompts (Future)¶

Update existing prompts to new slugs:

Old Slug	New Slug
`rose-internal-intent-router`	`rose-internal/classifier/intent`
`rose-internal-key-signals-detector`	`rose-internal/detector/interest-signals`
`rose-internal-visitor-profiling`	`rose-internal/detector/visitor-profile`
`rose-internal-form-extraction`	`rose-internal/extractor/form-fields`
`rose-internal-suggested-questions`	`rose-internal/suggester/follow-up-questions`
`rose-internal-suggested-answers`	`rose-internal/suggester/answer-options`
`rose-internal-dialog-supervisor`	`rose-internal/orchestrator/dialog-supervisor`

Phase 3: Future Agents¶

Add new response agents following the pattern: - rose-internal/response-agents/educator/template - rose-internal/response-agents/educator/instructions/{domain} - rose-internal/response-agents/qualifier/template - rose-internal/response-agents/qualifier/instructions/{domain}