Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Prompts, language & preamble

The system prompt defines persona and ground rules; the language directive controls reply language; the greeting opens the first turn; the preamble shapes mid-turn filler.

Context — This page covers the four manifest levers that shape the agent's voice: the system prompt, the language directive, the greeting, and the preamble. They live under agent_config.context alongside policies and routines.

YAML examples follow manifest schema 6.1.5. Manifest and content shapes are schema-versioned and differ across runtime versions — see Versioning & compatibility.

The system prompt

The system prompt is the agent's identity: who it is, what it does, the business facts it must know cold, and its style. It is a versioned document in the platform catalog, referenced by exact version:

agent_config:
  context:
    system_prompt:
      id: system-prompt
      version: 1

The DriveAway example (stored as a prompt whose body is the text field):

text: |
  You are Mercedes, a friendly booking specialist at DriveAway, a
  car-rental agency.

  Your job is to help customers find the right car, book it, and manage
  existing reservations. Keep answers short and concrete — confirm the
  important details (dates, pickup location, driver age, licence)
  before locking anything in.

  About DriveAway:
  - Fleet covers economy, compact, SUV, van, and luxury categories.
  - Minimum driver age is 21. Driver's licence held for at least one
    year, checked at pickup.
  - Free cancellation up to 24 hours before pickup.
  - One-way rentals (pickup ≠ return location) incur a flat 50 EUR fee.

  Style:
  - Warm, professional, no fluff. No emoji.
  - Always confirm pickup date, return date, location, and customer name
    before creating a booking.
  - If you don't have an answer, tell the user and offer a handoff to a
    human agent.

Division of labour

The system prompt is in context on every turn — it frames every reply the agent generates, and every routine step and policy the model weighs at runtime. That makes it the right home for some things and the wrong home for others:

Belongs in the system prompt
Belongs elsewhere

Persona, tone, formatting style

Conditional behaviours → policies

Stable business facts the agent cites constantly

Multi-step procedures → routines

Global prohibitions phrased as identity ("you never give legal advice")

Reference content that varies / is large → knowledge base

What the agent does and doesn't handle

Vocabulary definitions → glossaries

A system prompt stuffed with procedures fights the routine engine — the engine drives flows step-by-step, and a prompt narrating a different procedure creates contradictions. Keep procedures in routines.

Language

Value
Behaviour

match_user

Mirror the customer's language on every reply.

Any other string (e.g. French)

Handed to the model verbatim as the reply-language directive; the agent replies in that language regardless of the customer's.

language is free text — match_user is the only special value. Anything else is passed to the model as-is, so you can express a nuance in prose (e.g. French, but mirror the customer if they write in English); there is no built-in parsing of comma-separated language lists.

The directive binds replies, including the greeting and preambles (which are adapted to the active language). It does not restrict what the agent can understand.

Greeting and preamble

While the engine is mid-turn calling tools, seconds pass. The preamble lets the agent emit a short interim utterance so the customer sees life. The greeting is its sibling: a configured opening for the very first reply.

Field
Type
Required
Behaviour

context.greeting

string

no

First-turn opening: the agent's first message approximates this string, adapted to the active language. The preamble is suppressed on turn one — the greeting is the first message.

context.preamble.examples

list of strings (≥ 1)

yes, when the preamble block is present

Few-shot examples of mid-turn filler in the agent's voice. The model matches their tone and length; it does not quote them verbatim.

Behavioural details:

  • Preambles are rate-based, not model-judged. The engine attempts a preamble on the first couple of agent replies, then only when the customer's two most recent turns each kept them waiting (a few seconds or more) — so filler appears when someone has actually been left waiting, not on every turn.

  • In the event stream a preamble is its own kind ("preamble"), distinct from assistant_message. Render it like a typing indicator with text; replace it when the real reply arrives. See Events & callbacks.

  • Omit the preamble block to disable mid-conversation preambles; omit greeting to skip the first-turn opening. The two are independent.

How the pieces assemble at generation time

When the engine generates a reply, the prompt assembles roughly in this order: the system prompt → context variables → glossary terms → the matched policies' actions and the active routine step's instruction (one combined instructions section) → the conversation history → staged tool results (including retrieved knowledge-base snippets) → the language directive. Understanding this stack explains precedence intuitions: a routine step says what to do now; policies say what must hold; the system prompt says who is speaking.

See also

PreviousGlossaries & macrosNextTools

Last updated

Was this helpful?