> 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

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](https://docs.interactive.ai/agents/concepts/policies.md) and [routines](https://docs.interactive.ai/agents/concepts/routines.md).
>
> YAML examples follow **manifest schema 1.4.0**. Manifest and content shapes are schema-versioned and differ across runtime versions — see [Versioning & compatibility](https://docs.interactive.ai/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](https://docs.interactive.ai/agents/concepts/policies.md)                               |
| Stable business facts the agent cites constantly                        | Multi-step procedures → [routines](https://docs.interactive.ai/agents/concepts/routines.md)                                |
| Global prohibitions phrased as identity ("you never give legal advice") | Reference content that varies / is large → [knowledge base](https://docs.interactive.ai/agents/concepts/knowledge-base.md) |
| What the agent does and doesn't handle                                  | Vocabulary definitions → [glossaries](https://docs.interactive.ai/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.

## Instructions from the prompt library

Every instruction the model reads in a routine or policy is written inline by default. To share one instruction across routines and policies, write it as a prompt in the platform catalog and reference it by exact version, like the system prompt:

```yaml
nodes:
  - id: write_scenario
    think:
      id: write-scenario
      version: 3
    output: {type: object, properties: {scenario: {type: string}}}
  - id: reply_refund
    chat_state:
      id: refund-reply
      version: 2
```

| Where                                 | Fields that take a reference              |
| ------------------------------------- | ----------------------------------------- |
| Routine                               | `conditions`, or each of its entries      |
| Node                                  | `think`, `chat_state`, `tool_instruction` |
| Transition                            | `condition`                               |
| Tool argument with `source: llm`      | `instructions`                            |
| Policy (agent-wide or routine-scoped) | `condition`, `action`, `tool_instruction` |

* The version is required, so a routine or policy version always runs with the same instructions.
* The agent fetches every referenced prompt when it starts and uses its text as if it were written inline (`${macro-id}` tokens in a referenced `chat_state` are expanded as usual). A missing prompt or version stops the agent from starting; the error names the prompt, its version, and every place it is used.
* Display fields (`title`, `description`, a policy's `name`) stay plain text.
* In local mode (`CONFIG_DIR` set) the agent reads `<CONFIG_DIR>/<id>.yaml` (its `text:` field), as for the system prompt, whatever the version.
* References need schema 1.2.0 or later.

## Language

```yaml
agent_config:
  context:
    language: match_user
```

| Value                                              | Behaviour                                                                                                       |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `match_user`                                       | Mirror the customer's language on every reply.                                                                  |
| A language name (`French`, `Brazilian Portuguese`) | The agent replies in that language regardless of the customer's.                                                |
| An ISO 639-1 code (`fr`, `pt-BR`)                  | Read as the language's name, keeping the country: `fr` becomes `French`, `pt-BR` becomes `Portuguese (Brazil)`. |
| A name with its country (`Portuguese (Brazil)`)    | The same as the matching code.                                                                                  |
| A comma-separated list (`French, Spanish`)         | The agent replies in whichever listed language the customer uses, and in the first one otherwise.               |

The exact rules:

* `match_user` must be the whole value; it can't be combined with languages.
* Separate several languages with commas. An empty entry fails (`French,`).
* Names in the ISO 639-1 list are case-insensitive (`french` works). Any other name is accepted as written if it is one to three words of letters only, each starting with a capital letter (`Brazilian Portuguese`, `Swiss German`).
* A code must be a real ISO 639-1 code (`xx` fails). A country subtag is kept (`en-GB` becomes `English (United Kingdom)`); other subtags are dropped (`zh-Hant` becomes `Chinese`, `es-419` becomes `Spanish`).
* A country in parentheses must follow a language from the ISO 639-1 list and be the country's full English name: `English (United Kingdom)`, not `English (UK)`.

Anything else is rejected, including instructions in prose. For example:

| Rejected value                                             | Write instead                                                       |
| ---------------------------------------------------------- | ------------------------------------------------------------------- |
| `French, but mirror the customer if they write in English` | `French, English`, plus the nuance in the system prompt or a policy |
| `Hebrew and English`                                       | `Hebrew, English`                                                   |
| `English (UK)`                                             | `en-GB` or `English (United Kingdom)`                               |
| `Respond formally in German`                               | `German`, plus the tone in the system prompt                        |

The value is checked when the agent starts, not when you edit the manifest. The published JSON Schema (`iai agents schema`) accepts any non-empty string here, so a value can pass editor validation and still stop the agent from starting. The agent's logs then name the value and suggest a fix.

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](https://docs.interactive.ai/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](https://docs.interactive.ai/agents/concepts/conversation-lifecycle.md) — where generation sits in the turn
* [Glossaries & macros](https://docs.interactive.ai/agents/concepts/glossaries-and-macros.md) — vocabulary and reusable text
* [Manifest & content schemas](https://docs.interactive.ai/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.interactive.ai/agents/concepts/prompts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
