> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/agents/concepts/prompts.md). # Prompts, language & preamble > **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](/agents/concepts/policies.md) and [routines](/agents/concepts/routines.md). > > YAML examples follow **manifest schema 7.0.0**. Manifest and content shapes are schema-versioned and differ across runtime versions — see [Versioning & compatibility](/agents/operations/versioning.md). ## 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: ```yaml agent_config: context: system_prompt: id: system-prompt version: 1 ``` The DriveAway example (stored as a prompt whose body is the `text` field): ```yaml 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](/agents/concepts/policies.md) | | Stable business facts the agent cites constantly | Multi-step procedures → [routines](/agents/concepts/routines.md) | | Global prohibitions phrased as identity ("you never give legal advice") | Reference content that varies / is large → [knowledge base](/agents/concepts/knowledge-base.md) | | What the agent does and doesn't handle | Vocabulary definitions → [glossaries](/agents/concepts/glossaries-and-macros.md) | 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 ```yaml agent_config: context: language: match_user ``` | 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. ```yaml agent_config: context: greeting: "Hi! I'm Mercedes from DriveAway — how can I help you with your car rental today?" preamble: examples: - "Let me check." - "One moment." - "Sure thing." ``` | 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](/agents/reference/events-and-callbacks.md). * 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 * [Conversation lifecycle](/agents/concepts/conversation-lifecycle.md) — where generation sits in the turn * [Glossaries & macros](/agents/concepts/glossaries-and-macros.md) — vocabulary and reusable text * [Manifest & content schemas](/agents/reference/manifest.md) — field reference --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.interactive.ai/agents/concepts/prompts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.