Templates & Parameters

Template anatomy

Each template in a flow version has:

Field	Type	Description
name	string	Technical name (e.g. main, billing_handler). Used in API calls.
description	string	Human-readable description. Used by the classifier in Route mode.
template	string	The system prompt with [[parameter]] placeholders.
userTemplate	string	Optional user message template. Same parameter syntax.
llm	string	Model to use (e.g. openai/gpt-4o).
temperature	float	Sampling temperature (0-2).
maxToolCalls	integer	Maximum tool-calling iterations before stopping.
toolIds	string array	IDs of tools available to this template.
fallbacks	string array	Ordered fallback models if the primary model fails.
responseSchema	object	JSON Schema for structured outputs.

Parameter syntax

Parameters use double square brackets:

You are a [[role]]. Write a [[document_type]] about [[topic]].

Rules

• Parameter names must be lowercase with letters, digits, and underscores only

• [[my_param]] — valid

• [[MyParam]] — invalid (no uppercase)

• [[my-param]] — invalid (no hyphens)

• [[my param]] — invalid (no spaces)

How parameters are resolved

When a flow is executed, parameters are resolved in this order:

1. Caller-supplied values — Parameters passed in the API request body

2. Sub-template references — If a parameter name matches another template in the same version, that template's content is substituted

3. Unresolved — If neither applies, a warning is returned in the response

Comments in templates

Templates support two comment styles (comments are stripped before sending to the LLM):

/* This is a block comment */
// This is a line comment

System prompt vs. user message

Each template has two prompt fields:

• template (system prompt) — Rendered as a system message. This is where you define the LLM's behavior, persona, and instructions.

• userTemplate (user message) — Rendered as a user message after the system prompt. Use this when you want to separate instructions from the user's input.

Both fields support the same [[parameter]] syntax.

Example

System prompt (template):

You are a professional translator specializing in [[source_language]] to [[target_language]] translation.
Maintain the original tone and style.

User message (userTemplate):

Translate the following text:

[[input_text]]

Discovering parameters

Before executing a flow, you can discover what parameters it expects:

GET /api/v1/flows/{flowId}/parameters?environment=production

Response:

[
  { "token": "source_language", "source": "template" },
  { "token": "target_language", "source": "template" },
  { "token": "input_text", "source": "userTemplate" }
]

The source field indicates where the parameter appears:

Source	Meaning
template	In the system prompt
userTemplate	In the user message template
toolUrl	In an external tool's URL pattern

Parameters that match a sub-template name also include a promptTemplate object.

Structured outputs

You can constrain the LLM to return JSON matching a schema. Set responseSchema on the template:

{
  "type": "object",
  "properties": {
    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
    "confidence": { "type": "number" },
    "summary": { "type": "string" }
  },
  "required": ["sentiment", "confidence", "summary"]
}

The caller can also override this at execution time by passing responseSchema in the flow run request.

Not all models support structured outputs. Check the model's supportsStructuredOutput field via GET /api/v1/models/descriptors.

Tool assignments

Templates can reference tools by their IDs in the toolIds array. When tools are assigned:

1. PromptShuttle includes the tool definitions in the LLM request

2. If the LLM returns tool calls, PromptShuttle executes them automatically

3. Tool results are appended to the conversation and the LLM is re-invoked

4. This loop continues until the LLM responds without tool calls (or maxToolCalls is reached)

See Key Concepts: Tools for the five tool types.

Fallback models

Set fallbacks on a template to define backup models:

{
  "llm": "anthropic/claude-sonnet-4-20250514",
  "fallbacks": ["openai/gpt-4o", "google/gemini-2.5-flash"]
}

If the primary model fails (rate limit, timeout, outage), PromptShuttle automatically tries the next model in the list. The response indicates if a fallback was used.