> For the complete documentation index, see [llms.txt](https://docs.karini.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.karini.ai/prompt-management/create-prompt.md).

# Create Prompt

Karini AI's prompt playground enables domain experts to become prompt engineers with a guided experience. You can develop high quality prompts,  test them and track your prompt experimentation by saving the prompt runs.&#x20;

There are multiple ways to create a prompt:

### Create Prompt Using a Prompt Template

On prompt playground, click "Add new" to start new prompt creation. Click "Prompt templates" to access the available prompt templates. You can then select a template relevant to the task and continue to customize the prompt as required as described in the following section.

### Create New Prompt

1. On the **Prompt Playground,** click "**Add new**" to start new prompt creation.&#x20;
2. Provide a prompt name and select an appropriate task from the available list.
   * [Classification](https://docs.karini.ai/prompt-management/prompt-task-types.md#classification)
   * [Summarization](https://docs.karini.ai/prompt-management/prompt-task-types.md#summarization)
   * [Evaluation](https://docs.karini.ai/prompt-management/prompt-task-types.md#evaluation)
   * [Agent](https://docs.karini.ai/prompt-management/agentic-prompts.md)
   * [Deep Agent (Beta)](https://docs.karini.ai/prompt-management/deep-agent-beta.md)
   * OCR
   * Dynamic Filtering
   * Metadata Extractor
   * Multi-Query Rewrite
   * Query Expansion
   * Question Generator
3. **Max State Updates:** Specifies the maximum number of reasoning iterations allowed for Agent and Deep Agent, with a configurable range of 0 to 100 and a default value of 3.
4. Construct your prompt with appropriate instructions and  variables.&#x20;
5. Variables can be added dynamically using **"Add variable"** button.&#x20;
6. You can select the "**User Input**" option if the variable will be used as an input by the user in [copilot](https://docs.karini.ai/copilots.md) interface.
7. The constructed prompt - including the context and variables can be viewed on the right hand side **Prompt** panel.&#x20;
8. **Attach Tools and Skills:** Enables the attachment of relevant tools and skills to agent and deep agent  prompts, allowing agents to access additional capabilities and perform tasks more effectively.
9. Once the prompt is created, it can be tested on the [Test & Compare](https://docs.karini.ai/prompt-management/test-prompt.md) tab.
10. [Evaluate](https://docs.karini.ai/prompt-management/prompt-and-agent-evaluation.md): Assess the agent's performance against a predefined dataset using the Evaluation tab to validate its accuracy and effectiveness
11. [Publish ](https://docs.karini.ai/prompt-management/prompt-versions.md)an immutable version of the agent to ensure consistency and enable reliable referencing across recipes and workflows

### Prompt text: system and user messages <a href="#prompt-text-system-and-user-messages" id="prompt-text-system-and-user-messages"></a>

Prompt Structure: A prompt consists of one or more messages, each assigned a specific role.&#x20;

* **System messages :** Define the rules and instructions that guide the model’s behavior.
* **User messages :** Provide the input, queries, or tasks to be processed.

| Role     | Purpose                                                                                          | Put here                                                                                   |
| -------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `system` | Defines behavior, persona, constraints and output format. Treated as authoritative instructions. | Role definitions, tone, rules, output format, few-shot examples, stable background context |
| `user`   | The actual query or task to process under the system rules.                                      | Questions, input data, dynamic context, anything that changes per request                  |

**Message Ordering and Management**

* **Message Ordering**: Arrange system messages first, followed by user messages, to maintain the correct prompt structure.
* **Add Message**: Use the Add Message option to create additional messages in the prompt editor.

<figure><img src="https://415930246-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7ZrVuiAUMyuYVvrK5KaB%2Fuploads%2F5e9JYQj6qRYuctuqBJCl%2Fimage.png?alt=media&amp;token=375a24e8-f3f0-49c1-b838-b5340df79c8b" alt=""><figcaption></figcaption></figure>

* **Reorder Messages**: Drag and drop messages to adjust their sequence as needed.
* **Fullscreen View:** Expand individual messages to fullscreen for easier viewing and editing.
* **AI-Assisted Rephrasing:** Use AI to refine, rephrase, or improve message content.
* **Delete Messages:** Remove unnecessary messages while ensuring that at least one message remains in the prompt.

#### Message request format <a href="#message-request-format" id="message-request-format"></a>

The request payload must specify messages in the `prompt.template` field. Two message formats are supported: **simple string templates** and **structured prompt blocks**.

**1. Simple String Template**

A simple string template represents the entire prompt as a single string, without explicit message-role separation. This format is suitable for straightforward interactions where distinct system and user message boundaries are not required.

**Example:**

```json
{
  "prompt": {
    "template": "You are a helpful assistant. Answer this question: {question}",
    "variables": {
      "question": "What is the capital of France?"
    }
  }
}
```

**2. Structured Prompt Blocks (Recommended)**

Structured prompt blocks represent the prompt as an ordered array of objects, each containing a `role` and a `content` field. This format enables explicit role-based message separation and supports multiple `system` message blocks.

**Example:**

```json
{
  "prompt": {
    "template": [
      {
        "role": "system",
        "content": "You are a {role}. Follow these guidelines: {guidelines}"
      },
      {
        "role": "system",
        "content": "Always cite sources when providing factual information."
      },
      {
        "role": "user",
        "content": "Question: {question}\n\nContext: {context}"
      }
    ],
    "variables": {
      "role": "technical documentation assistant",
      "guidelines": "Be concise, accurate, and professional",
      "question": "How does semantic caching work?",
      "context": "User is testing caching features in development"
    }
  }
```

[Tag Insertion:](https://docs.karini.ai/prompt-management/prompt-template-tags.md) The editor’s insert buttons generate tags according to a predefined, standardized syntax.

#### Multimodal input <a href="#multimodal-input" id="multimodal-input"></a>

Images can be attached via the image tag in the prompt text, a File Upload variable in the Test tab. The selected model must support vision.

### Special Variables

When authoring prompts, following variables are treated as special or predefined variables.&#x20;

1. **Context**:  This is a predefined variable for LLM. For prompt testing, authors can provide appropriate text as a value for this variable. However, for production use or use within recipes and copilots, the value for this variable will be replaced with relevant context retrieved from the vector store.  You can also upload a **context file** as a input to this variable. The context file must be of type **.txt** or **.pdf.** The contents from the pdf file are automatically preprocessed by doing OCR before adding them as a input to context.  The limit to file size that can be added as a context is 2 MB.&#x20;
2. **Question:** This is a predefined variable for LLM. For prompt testing ,authors can provide the question related to the context as value for this variable. Enable the **User input** checkbox on the Edit prompt page to display the question under **User Input** in the **Test & compare** section.
3. **Evaluation Metric Name:** This is a predefined variable for LLM used in **Evaluation** prompts. For prompt testing ,authors can provide the evaluation metric name as value for this variable.
4. **Evaluation Metric Description:** This is a predefined variable for LLM used in **Evaluation** prompts. For prompt testing ,authors can provide the evaluation metric description as value for this variable.
5. **Evaluation Grading Criteria:** This is a predefined variable for LLM used in **Evaluation** prompts. For prompt testing ,authors can provide the evaluation grading criteria as value for this variable.
6. **Evaluation Input:** This is a predefined variable for LLM used in **Evaluation** prompts. For prompt testing ,authors can provide the question as as value for this variable.
7. **Evaluation Output:** This is a predefined variable for LLM used in **Evaluation** prompts. For prompt testing ,authors can provide an answer to compare with the ground truth output for assessment.
8. **Evaluation Ground Truth:** This is a predefined variable for LLM used in **Evaluation** prompts. For prompt testing ,authors can provide ground truth answer for assessment.
9. **File System Instructions: Ths i**s a mandatory prompt variable that specifies what data to store, the required format (e.g., JSON, TXT, CSV), and the exact storage path. It ensures deterministic, structured, and auditable persistence. The agent must also maintain and continuously update `/<thread_id>/memories/index.txt` to catalog and summarize all files within the memories directory.

   <br>
