Templates

A template is a document with named fields. Three are required and the rest are optional, but the optional ones are where most of the leverage sits — outputFormat in particular does far more than describe the answer.

A template can declare variables so the UI can collect values for them. Each carries an id, a name, an optional description, a type — Text, Number or Select — an options string for select lists, and an isManual flag marking it as supplied by hand rather than derived.

Four booleans on the template switch off parts of the research stage for requests it matches. This is per-template, not per-agent: an agent can have one template that needs the knowledge base and another that must never touch it.

An agent lists the templates it may use. For each request exactly one is applied, or none — never two. Concatenating several would blur the persona, so the candidate list is deliberately truncated to a single winner at the end.

Only three fields are embedded: templateName, context and task, joined by newlines as plain label-free text. The labels (TemplateName:, Context:) were deliberately removed — they are tokens a user query never contains, so they only added noise to the document vector and widened the gap between how a query reads and how a template reads.

Every template also stores embeddingModel, the id of the model that produced its vector. That is what makes staleness detectable: querying with a vector from one model against documents embedded by another silently degrades relevance instead of failing.

Selection is a sequence of filters, each able to return nothing:

1. Single-template shortcut. If the agent maps exactly one template, no search runs at all. It is used — but only if its status is active. A draft or inactive template is deliberately not used even when mapped one-to-one. It is stamped with a maximum vector score so downstream gates treat it as a definite match.
2. Vector search. With two or more templates, a shared search path fetches the top candidates — the same code the Vector Tester uses, so the tester mirrors execution rather than approximating it. Templates whose stored embedding dimensions no longer match the query are excluded and reported, because Atlas would otherwise drop them silently and the template would simply vanish from the candidate set with no signal.
3. Relevance floor. Scores are Atlas cosine normalised to 0–1, where 0.5 means orthogonal — unrelated. Anything below the configured floor is dropped. If nothing clears it, the turn proceeds with no template at all.
4. LLM re-rank, with a confidence override. A model re-ranks the surviving candidates and is allowed to abstain. If it abstains, the top vector match is used only when it clears an absolute floor and beats the runner-up by a clear margin. A clustered band such as 0.80 against 0.78 is treated as ambiguous lexical overlap, not relevance — so the turn proceeds template-agnostic.

Retrieval used to see only the raw user message — whatever the template said it needed was never passed along. A matched template now produces a lightweight retrieval intent, built deterministically with no extra model round-trip.

Fields are extracted only from outputFormat, because that is the one machine-readable statement of what must be populated. Extraction tries three strategies in order: parse it as strict JSON and take the keys (top level plus one nested level); otherwise scrape "key": patterns from loose JSON-ish text; otherwise, only if the spec is short and comma-separated, treat it as a plain field list.

Free text in context and task is deliberately not scraped for field names — verb and NLP extraction proved noisy and produced bogus tokens. Instead the raw context and task are preserved in an intent text that the MCP tool planner reads as natural language.

Candidates are filtered so noise cannot leak through: at most eight fields, each no longer than 48 characters and at most five words, and each must contain a letter. Anything longer is a sentence, not a field name.

The extracted fields fan out into multiple RAG queries. Query zero is always the raw user message, which preserves existing recall. Each additional query appends one required field to the user's topic, biasing that vector toward the field. A template that needs five things gets field-specific coverage instead of one top-K blob that happens to be dominated by whichever field the user phrased most strongly.

Workflow steps can inherit from the matched template rather than repeating its content. Two sentinel values do the work, and both mean "whatever template won this turn":

A workflow can also be bound to a single template by id, so it runs only on turns the classifier routed to that template — one agent, several pipelines, no manual switching.

The llm_generate action has its own instructionMode: in template mode it drives generation from a saved template's persona, context, task, constraints and output format; in custom mode you write the instruction inline.

Writing eight good fields from scratch is work, so the studio can generate them. Give it a one-line prompt and an enhancement model expands it into the full structure — name, category, persona, context, task, reasoning, constraints, examples and output format — returning every value as a string. Or hand it a partially filled template and it enhances the fields already there instead of replacing them.

The enhancer is explicitly told to keep things tight: the persona stays within about 30 words, constraints are bulleted never/always rules, reasoning is a single short line, and examples are one realistic case with no nested JSON. The output format field is where it is told to be maximally specific, since that is the field the rest of the platform parses.

You pick the provider and model per enhancement run, so drafting can use a cheaper model than production traffic.

• Model name and id recorded per run
• Input, output and total tokens
• USD cost, frozen at write time from model pricing
• Re-enhance count per template
• Running token and cost totals
• Timestamp of the last enhancement

A template's status is active, inactive or draft, and only active templates are ever eligible for selection. Separately, isActive is a soft-delete flag — deleting sets it false and excludes the template from listings, but the document is retained.

When the system default embedding model changes, existing vectors become incomparable to new queries. A maintenance pass scans every live template whose recorded embedding model is missing or differs from the current default and re-embeds it, reporting how many were scanned and how many were rewritten. Until that runs, affected templates are the ones the dimension check excludes from search.

• Share with named users
• Share with whole roles
• Creator and last modifier tracked
• Created and updated timestamps
• System fields cannot be set by clients
• Per-template and global analytics views