Prompt Best Practices

This guide covers practical patterns for writing effective prompts in Seclai Prompt Call and Insight steps. It applies to both manual step configuration and prompts generated by the AI Assistant.

System Template Structure

The system_template defines the model's role, constraints, and output format. A well-structured system template has four parts:

1. Role — Who the model is and what it does
2. Rules — Constraints, boundaries, and behavior guidelines
3. Output format — Exactly how the response should be structured
4. Examples — Concrete input/output pairs that demonstrate the rules

You are a product information specialist for {{organization.name}}.
You help customers find product details and answer technical questions.

## Rules
- Answer ONLY using the provided knowledge base context.
- If the answer is not in the context, respond with:
  "I don't have that information. Please contact support."
- Keep responses under 200 words.
- Do not discuss competitor products.
- Do not make up specifications or pricing.

## Output format
Respond in plain text with short paragraphs. Use bullet points for
lists of features or specifications.

## Examples
User: What battery life does the X200 have?
Assistant: The X200 has a 12-hour battery life under normal usage
and 8 hours under heavy workloads, based on internal testing.

User: How does it compare to the CompetitorY?
Assistant: I can only provide information about our products.
For details about the X200's specifications, I'm happy to help.

Key principles:

• Place rules before examples. The model reads the system prompt sequentially — it needs to see the constraints before seeing them applied in examples.
• Make examples consistent with rules. If a rule says "do not discuss competitors," include an example showing how to deflect a competitor question. Examples are the strongest signal a model receives — if rules and examples conflict, the model follows the examples.
• Be specific about refusals. Instead of "don't answer irrelevant questions," provide the exact fallback response the model should use. Vague instructions produce inconsistent behavior.

Prompt Template Patterns

The prompt_template is the user-facing message sent to the model each time the step runs. Common patterns:

Pass-through (most common):

{{input}}

Uses the output of the previous step (or the agent input for root steps) as the prompt. This is the default when prompt_template is not set.

Labeled context injection:

Context from knowledge base:
{{step.search-kb-retrieval.output}}

User question:
{{agent.input}}

Use labeled sections when combining multiple data sources. This helps the model distinguish between context and the actual question.

Metadata-enriched prompt:

User ID: {{metadata.user_id}}
Session: {{metadata.session_id}}
Language preference: {{metadata.language}}

Request: {{agent.input}}

Use {{metadata.*}} placeholders when agent behavior should vary based on caller-provided metadata.

Multi-step reference:

Web page content:
{{step.fetch-page-web_fetch.output}}

Knowledge base results:
{{step.search-retrieval.output}}

User preferences:
{{step.load-prefs-search_memory.output}}

Based on ALL of the above context, answer: {{agent.input}}

When a prompt_call references outputs from multiple earlier steps via {{step.<id>.output}}, label each section clearly so the model knows what each block represents.

Grounding and Hallucination Prevention

Grounding instructions tell the model to use only the provided context and avoid fabricating information.

Basic grounding pattern:

Answer using ONLY the provided context. If the context does not
contain enough information to answer, say exactly:
"I don't have that information."

Do not infer, speculate, or add information from your training data.

Citation pattern (for RAG agents):

Answer the question using the provided knowledge base excerpts.
For each claim in your answer, cite the source by including the
content URL in parentheses.

If no excerpts are relevant, respond with:
"No relevant information found in the knowledge base."

Handling empty retrieval results:

Context:
{{step.retrieval.output}}

If the context above is empty or contains no relevant information,
respond with: "I could not find relevant information for your query."
Do NOT attempt to answer from general knowledge.

Always provide an explicit fallback message. Without one, the model will fill gaps with its training data.

Structured Output (JSON)

For steps that need structured output (especially before Extract Content or Gate steps), use the Insight step's output_format: json_object mode or instruct the Prompt Call to return JSON.

Insight step with JSON schema (recommended for structured extraction):

The Insight step has built-in output_schema support that constrains the model to a specific JSON structure:

{
  "type": "object",
  "required": ["topic", "severity", "summary"],
  "properties": {
    "topic": { "type": "string" },
    "severity": { "type": "integer", "minimum": 1, "maximum": 5 },
    "summary": { "type": "string" }
  }
}

Prompt Call with JSON output:

When using a Prompt Call instead of Insight, be explicit in the system template:

Extract the requested fields and return ONLY a valid JSON object.
No markdown code fences, no explanations, no text before or after the JSON.

Required fields:
- "answer": string — a concise answer to the question
- "confidence": number between 0 and 1

Example of valid output:
{"answer": "The release date was March 15.", "confidence": 0.95}

Example of INVALID output (do not do this):
```json
{"answer": "..."}
```

Key tips for JSON output:

• Show a concrete example of valid output in the system template
• Explicitly forbid markdown code fences — many models default to wrapping JSON in ```json ``` blocks
• When the JSON feeds into an Extract Content step with JSONPath, verify that the field names in your schema match the JSONPath query exactly
• Consider pairing with a Gate step to validate the output format, and a Retry step to re-attempt on malformed output

Temperature and Model Selection

Temperature guidelines:

When the output feeds into a Gate or Extract Content step, use temperature 0.0 to get consistent, parseable results.

Model selection by task:

Use the Models & Playground page to test different models with your actual prompts before committing to a configuration.

RAG Prompt Patterns

Retrieval-Augmented Generation (RAG) agents retrieve relevant content from a knowledge base and pass it to a Prompt Call. The prompt design significantly affects answer quality.

Basic RAG pattern:

System:
You are a helpful assistant for {{organization.name}}.
Answer questions using ONLY the provided knowledge base excerpts.
If the excerpts do not contain the answer, say "I don't have that information."

Prompt:
Knowledge base results:
{{step.search-retrieval.output}}

Question: {{agent.input}}

RAG with source attribution:

System:
You are an expert research assistant. Answer the question using the
provided excerpts. After each claim, cite the source title in brackets.

If multiple sources agree, prefer the most recent one.
If no sources are relevant, say "No relevant sources found."

Prompt:
Sources:
{{step.search-retrieval.output}}

Question: {{agent.input}}

RAG with fallback behavior:

System:
Answer using the provided context. If the context is insufficient:
1. State what you found (even if partial)
2. Explain what information is missing
3. Suggest how the user might rephrase their question

Never fabricate information to fill gaps.

Tips for better RAG results:

• Use top_n: 10–20 in the retrieval step for most use cases. Higher values add noise; lower values may miss relevant content.
• Put retrieval results in prompt_template (not system_template) when using simple pass-through — this keeps the system prompt stable across queries.
• When using use_step_input_as_messages for conversational RAG, place retrieval results in system_template via {{step.<id>.output}} since prompt_template is not used in messages mode.

Conversational Prompts

For chatbot agents that maintain conversation history via Memory Banks, the prompt pattern differs from single-turn agents.

System template for conversational agents:

You are a helpful customer support assistant for {{organization.name}}.

Guidelines:
- Be friendly and professional
- Reference earlier parts of the conversation when relevant
- If you don't know something, say so honestly
- Keep responses concise unless the user asks for detail

When using use_step_input_as_messages: true, the conversation history flows as individual messages. The system template provides persistent context, and you don't need to format the conversation manually.

Adding external context to conversations:

If your chatbot also uses retrieval or user preferences, inject them into the system template:

You are a helpful assistant. Use the provided context to personalize
your answers.

Knowledge base context (use if relevant to the current question):
{{step.search-kb-retrieval.output}}

User preferences:
{{step.recall-prefs-search_memory.output}}

See Input as Messages for the full recommended conversational workflow.

Multi-Step Orchestration

Complex agents chain multiple Prompt Call steps. Each step should have a focused, single responsibility.

Good: Focused steps

Avoid: One prompt doing everything

Trying to extract, summarize, format, and classify in a single prompt produces inconsistent results. Split complex tasks into focused steps where each step does one thing well.

Referencing earlier steps:

When a later Prompt Call needs output from a non-parent step, use explicit {{step.<id>.output}} references in the system or prompt template:

System:
You are formatting an alert report.

Original analysis:
{{step.extract-insight.output}}

Severity assessment:
{{step.severity-gate.output}}

Format the above into a clear alert email.

Tip: Step IDs are visible in the step editor and in Agent Traces. Use descriptive IDs (e.g., extract-facts-insight, format-email-prompt) to make cross-references readable.

Tool Use Prompts

When a Prompt Call has tools configured, the system template should guide the model on when and how to use them.

Knowledge base tools:

You are a research assistant with access to the company knowledge base.

When answering questions:
1. ALWAYS search the knowledge base first using search_knowledge_base
2. If the initial search doesn't find relevant results, try
   rephrasing the query and searching again
3. Use load_content to read full documents when excerpts aren't enough
4. Base your answer ONLY on content found through these tools

Do not answer from your training data. If the tools return no
relevant results, say "I couldn't find that information in the
knowledge base."

Web tools:

You have access to web search and web fetch tools.

Use seclai_web_search to find current information when:
- The user asks about recent events
- The knowledge base results are outdated
- You need to verify a claim

Use seclai_web_fetch to read a specific URL when:
- The user provides a link
- Search results reference a page you need to read in detail

Always cite the URLs of pages you reference.

Memory tools:

You have access to a memory bank for storing user preferences.

After each conversation:
- If the user expresses a preference (e.g., "I prefer short answers"),
  store it using write_memory with a descriptive key
- Before answering, check for stored preferences using search_memory
- Reference stored preferences in your responses when relevant

Common Mistakes