Prompt Layers#
The Squirro platform employs a multi-layered prompt architecture that integrates several instruction layers to direct large language model behavior. That approach maintains a balance between consistency and flexibility, allowing administrators to adjust agent responses to specific requirements while preserving platform-wide standards.
Architecture at a Glance#
The prompt architecture consists of three main components:
Hierarchical Prompt Composition
Prompts in the Squirro platform are constructed from multiple layers that combine to form a cohesive instruction set. These layers include system instructions, which define core agent behavior and rules, as well as personas that assign specific roles and areas of expertise to agents. Language settings ensure responses align with the user’s preferred language, while citation formats standardize how sources are referenced. The final layer incorporates user input, which provides the actual request or instruction.
Two-Stage Templating System
The system constructs prompts through a two-stage process. In the first stage, static values such as persona definitions, language settings, and citation formats are substituted before the conversation starts. The second stage replaces runtime values, including user input, chat history, and retrieved information, as the conversation unfolds.
Specialized Prompt Chains
In addition to the main conversation prompts, the system employs specialized prompts designed for specific tasks. These include query formulation, which transforms natural language questions into effective search queries, and language detection, which identifies the language used by the user. Summarization prompts condense lengthy documents or conversation histories, while response validation ensures that retrieved information directly addresses the user’s requests. Those specialized prompts operate behind the scenes to enhance and support the main conversation flow.
Customization Levels#
The architecture provides customization points at multiple levels that work together as a fallback chain.
Deployment level
Core system templates and default behaviors configured during the deployment and initial configuration phase of the Squirro platform. Those serve as the final fallback when no higher-level customization is configured.
Server level
Default persona for conversational AI, configured by administrators using the Server space. When set, it takes precedence over deployment-level defaults for all projects on the server.
Project level
Default personas and language settings for all agents in a project, configured by administrators at the project configuration level using the Setup space.
Agent level
Agent-specific personas, tool configurations, and grounding modes that override project-level settings for individual agents.
Tool level
Custom tool names, descriptions, and parameter guidance for specific tools within an agent.
User level
Personal prompt libraries and language preferences that apply to individual user interactions.
That hierarchy follows a fallback pattern where each level can override the previous level, but if a level is not configured, the system falls back to the next lower level. It ensures consistent baseline behavior while allowing granular customization when needed.
User Features#
Several prompt layers work together to shape how agents respond to prompts. Users have control over certain aspects of how agents respond.
Personal Prompt Library#
Users can create and save reusable prompt templates in the personal library. That feature is useful when frequently asking similar types of questions.
Example use cases:
Summarization templates for different document types.
Analysis templates for specific data formats.
Report generation templates with consistent structure.
For more information about the Prompt Library, see the Prompt Library page.
Conversation Context#
Conversation history affects how agents respond to follow-up requests. The agent remembers:
Previous messages.
Documents referenced in the conversation.
Information retrieved in earlier steps.
That context allows for clarifying questions or adjustments without repeating information. Note that long conversations are automatically summarized to keep recent context accessible while managing system limits. Older conversation stages are condensed, but important information is preserved.
System Configuration#
Administrators can configure the prompt architecture at multiple levels to adjust conversational AI behavior to organizational requirements. Understanding the architecture enables administrators to configure personas, citation formats, language settings, and tool descriptions across deployment, server, project, and agent levels.
Understanding Persona vs User Prompt Instructions#
The prompt architecture distinguishes between two key configuration elements that serve different purposes.
Persona
The persona defines the agent’s identity, personality, and character by establishing who the agent is and how it communicates, with a focus on role, personality traits, and communication style. Its purpose centers on shaping the agent’s identity and tone, and it is typically located in the system message.
User Prompt Instructions
The user prompt instructions define the behavioral rules, constraints, and operational requirements that the agent must follow. These instructions enforce specific behaviors, regardless of the agent’s personality. Their purpose is to establish mandatory behaviors and rules.
Deployment-Level Defaults#
Deployment-level settings are hardcoded Python constants in the GenAI service source code that serve as final fallback values when no customization is configured at higher levels. These constants are defined in the templates.py file within the GenAI service container.
Default Persona#
The following example illustrates the default persona definition that applies when no other customization is configured:
DEFAULT_PERSONA = """\
You are Squirro Chat, a truthful and friendly AI assistant.
"""
Default User Prompt Instructions#
The example below shows the default user prompt instructions that apply when no other customization is configured:
DEFAULT_USER_PROMPT_EXTRA = """\
You are an assistant designed to answer user queries based solely on information retrieved from available tools.
## Key Rules
### 1. Mandatory Retrieval
You must call at least one retrieval tool before generating any response.
### 2. Context-Bound Responses
Your answers must rely strictly on the retrieved context.
### 3. Citation Requirements
Always follow citation rules when referencing retrieved information.
"""
Customizing Deployment-Level Defaults#
Customize deployment-level defaults using environment variables for the GenAI service container. That approach persists across container restarts and does not require modifying files inside the container.
Use the following environment variables to customize deployment-level defaults:
DEFAULT_PERSONAOverrides the default persona for all agents.
DEFAULT_USER_PROMPT_EXTRAOverrides the default user prompt instructions.
DEFAULT_ASSISTANT_LANG_INSTRUCTIONOverrides language instructions for agent responses.
DEFAULT_RETRIEVAL_LANG_INSTRUCTIONOverrides language instructions for retrieval queries.
For detailed information about setting GenAI environment variables, including configuration steps and examples, see the genai.ini page.
These environment variable customizations apply across all projects on the server instance. For more granular control, use Server-level, Project-level, or Agent-level configuration as described in the following sections.
Server-Level Customization#
At the server level, administrators configure default settings that apply to all projects on the server instance.
Default Persona#
Administrators configure the default persona to set a server-wide standard for all conversational AI interactions.
Configuration:
Navigate to Server space.
Select the Configuration section.
Locate the
genai.sqgpt.default-settingsconfiguration key.Click Edit.
Update the
personafield.Save the configuration.
Once set, the server-level persona applies to every project on the server instance, taking precedence over deployment-level defaults. Individual projects can specify their own personas to override the server-level setting.
Project-Level Customization#
At the project level, administrators configure default settings that apply to all agents within the project.
Default Persona#
Administrators define the default persona, which sets the personality and role for the conversational AI within the project.
Navigate to Setup space.
Select the Settings tab.
Locate the
genai.sqgpt.settingsconfiguration key.Click Edit.
Update the
personafield.Save the configuration.
Once set, the project-level persona serves as the default for all agents in the project, overriding server-level and deployment-level defaults. Individual agents can specify their own personas to override the project-level setting.
User Prompt Instructions#
Administrators can customize additional instructions that are applied to all user messages within the project.
Configuration:
Navigate to Setup space.
Select the Settings tab.
Locate the
genai.sqgpt.user-prompt-extraconfiguration key.Click Edit.
Update the instructions as needed.
Save the configuration.
That configuration allows administrators to customize the behavioral rules that govern how agents interact with data and formulate responses. When not configured, the system falls back to deployment-level default instructions.
Agent-Level Customization#
At the agent level, administrators configure individual agents with specific personas, grounding modes, and tool selections. Agent-specific personas override project-level defaults, allowing each agent to have unique characteristics and behavior tailored to specific use cases.
For detailed instructions on configuring agents and their tools, see the Configuring Agents and Tools page.
Tool-Level Customization#
At the tool level, administrators customize how individual tools are presented to the LLM. This includes configuring tool names, descriptions, and input parameter guidance. These customizations influence how the LLM understands and uses each tool within an agent.
For detailed instructions on configuring tools, see the Configuring Agents and Tools page.
Hierarchical Prompt Composition#
The final prompt sent to the LLM is composed hierarchically:
System message
Base system instructions
Persona definition
Language instructions
Citation format rules
Chat history
Previous user messages
Previous assistant messages
Context continuity
User message
Current user input
File context (if files uploaded)
Additional guidelines
Agent scratchpad
Tool calls and results
Intermediate reasoning
Retrieved information
That hierarchical structure ensures that static configuration is established first, followed by dynamic conversation elements.