# 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: 1. **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. 2. **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. 3. **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](../chat/prompt-library.md#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. Administrators can restrict that memory to the previous messages only. For more information, see the [Extended Conversation Context](#extended-conversation-context) section. 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: ```python 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: ```python 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_PERSONA` Overrides the default persona for all agents. - `DEFAULT_USER_PROMPT_EXTRA` Overrides the default user prompt instructions. - `DEFAULT_ASSISTANT_LANG_INSTRUCTION` Overrides language instructions for agent responses. - `DEFAULT_RETRIEVAL_LANG_INSTRUCTION` Overrides language instructions for retrieval queries. For detailed information about setting GenAI environment variables, including configuration steps and examples, see the [genai.ini](../admin/configuration/config-files/genai.md#admin-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:** 1. Navigate to the Server space. 2. Click Configuration from the left sidebar menu. 3. Locate the `genai.sqgpt.default-settings` configuration key. 4. Click Edit. 5. Update the `persona` field. 6. Confirm with the check mark. 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. **Configuration:** 1. Navigate to the Setup space. 2. Click the Settings tab. 3. Click Project Configuration from the left sidebar menu. 4. Locate the `genai.sqgpt.settings` configuration key. 5. Click Edit. 6. Update the `persona` field. 7. Confirm with the check mark. 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:** 1. Navigate to the Setup space. 2. Click the Settings tab. 3. Click Project Configuration from the left sidebar menu. 4. Locate the `genai.sqgpt.user-prompt-extra` configuration key. 5. Click Edit. 6. Update the instructions as needed. 7. Confirm with the check mark. 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. #### Extended Conversation Context By default, agents receive the extended conversation context. That context contains the earlier questions and answers of the conversation, the tools that ran in each of those turns, the arguments each tool was called with, and the information those tools returned. It allows an agent to resolve a follow-up request, such as a request to compare the documents it retrieved earlier, without repeating the retrieval. Administrators can restrict the context to the earlier questions and answers only. An agent still receives those questions and answers, so it keeps the thread of the conversation. It no longer receives the tool activity of the earlier turns. The restricted context is useful in two situations: - **Large requests** The extended context replays the complete output of every tool that ran earlier in the conversation, in full, on every later request. There is no limit on the number of turns, and no step condenses the earlier output. In a retrieval-heavy conversation, that output is the full text of every document retrieved so far, sent again with each new question. - **Squirro 3.14.3 only** On that version, a conversation can fail with an agent error when a tool in an earlier turn returned no output. Squirro 3.14.4 corrects that behavior, so the restricted context is a workaround on 3.14.3 and is no longer needed from 3.14.4 onwards. The `genai.sqgpt.disable-extended-context` configuration key controls that behavior and is available from Squirro 3.14.3 onwards. The key accepts a boolean value and defaults to `false`, which means that agents receive the extended conversation context in every project where an administrator has not set the key. Outside the two situations above, Squirro recommends keeping the default value, because the restricted context gives agents less information to work with when a user refines an earlier request. **Configuration:** 1. As a server administrator, navigate to the Setup space. 2. Click the Settings tab. 3. Click Project Configuration from the left sidebar menu. 4. Locate the `genai.sqgpt.disable-extended-context` configuration key. 5. Click Edit. 6. Select the checkbox. 7. Confirm with the check mark. To return to the default, clear the checkbox and confirm again. **Scope:** The setting applies to every conversation in Squirro Chat, which includes the standard, embedded, and copilot chat, as well as Chat with Document. It also applies to conversations that started before the change, and clearing the checkbox restores the extended context for those same conversations. Agents in [Project Neo](../neo/index.md#neo), Batch Q&A, and summarization do not use the extended conversation context, so the setting has no effect on them. Set the key in each project that needs the restricted context. The key has no server-level equivalent, and an individual agent cannot override it. The change is not immediate. Configuration values are cached for the duration of the `config.cache-ttl` server setting, which defaults to 120 seconds, so a follow-up question asked within that window can still use the previous behavior. For more information, see the [Configuration Service](../admin/configuration/config-service.md#admin-config-service) page. ### 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](configuring-agents-and-tools.md#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](configuring-agents-and-tools.md#configuring-agents-and-tools) page. ## Hierarchical Prompt Composition The final prompt sent to the LLM is composed hierarchically: 1. **System message** - Base system instructions - Persona definition - Language instructions - Citation format rules 2. **Chat history** - Previous user messages - Previous assistant messages - Context continuity When agents receive the extended conversation context, the chat history also carries the tools that ran in the earlier turns of the conversation, the arguments they were called with, and the information they returned. For more information, see the [Extended Conversation Context](#extended-conversation-context) section. 3. **User message** - Current user input - File context (if files uploaded) - Additional guidelines 4. **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.