> ## Documentation Index
> Fetch the complete documentation index at: https://maestro.rasa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# agent.yml

> Agent identity, persona, global rules, prompt tuning, and session settings.

`agent.yml` is required at the project root. It carries the agent's identity in
an `agent:` block, plus several top-level tuning sections.

```yaml agent.yml theme={null}
agent:
  id: telco-support
  language: en
  persona: |
    You are Telco support. A friendly, concise customer service assistant.

rules:
  - Help with billing and plan questions only.
  - Never quote a balance without looking up the account first.

prompts:
  text_rules: |
    Plain sentences only. No markdown or bullet lists.
  routing_no_active_skill: |
    Greeting: welcome briefly and ask what they need.

references:
  embeddings: reference_embeddings

conversation:
  before_end:
    - default_customer_satisfaction

session_config:
  session_expiration_time: 60
  start_session_after_expiry: true
```

The file has two levels. `id`, `language`, and `persona` are the agent's
identity and live **inside** the `agent:` block. `rules`, `prompts`,
`references`, `conversation`, and `session_config` are tuning sections and sit
at the **top level** as siblings of it.

## The `agent:` block

Required. A missing or non-mapping `agent:` section fails the load.

| Key        | Required | Default   | Description                                                             |
| ---------- | -------- | --------- | ----------------------------------------------------------------------- |
| `persona`  | **Yes**  | none      | Free text prepended to every system prompt. Must be a non-empty string. |
| `id`       | No       | generated | Stable agent identifier.                                                |
| `language` | No       | `en`      | Primary conversation language.                                          |

### `persona`

The only mandatory field in the whole file. A missing or blank `persona` raises
`config.agent.missing_persona` at load.

It sets global tone and identity.

### `id`

When absent or blank, a unique id is generated in the form
`YYYYMMDD-HHMMSS-<duoname>` and **written back into `agent.yml`**, with a warning.
`language` is not written back. The `en` default is applied at parse time only.

## `rules`

A list of strings, rendered into the system prompt as a bullet list. These are
global do/don't guidance applied across every skill: scope limits, tone guards,
ordering constraints.

```yaml theme={null}
rules:
  - You help with card replacement, balance checks, and fraud reports only.
  - Do not mention skill, tool, or memory names to the customer.
  - >
    If the user already provided the information you need, do not ask again:
    record it and continue.
```

<Note>
  A rule containing `:` followed by a space parses as a YAML mapping and breaks
  the load. Quote it, or use a `>` folded scalar as above.
</Note>

## `prompts`

Overrides for individual sections of the system prompt. Every key is optional;
an empty or absent value falls back to the built-in default.

| Key                       | Type   | Description                                                                                                            |
| ------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `text_rules`              | string | Channel rules rendered for text conversations                                                                          |
| `voice_rules`             | string | Channel rules rendered for voice conversations                                                                         |
| `ack_rule`                | string | Guidance for acknowledging a tool call in progress                                                                     |
| `ack_reminder`            | string | Short reminder injected after the user message on the first LLM iteration, to reliably elicit a spoken acknowledgement |
| `ack_enabled`             | bool   | Whether the acknowledgement section and reminder are included (default `true`)                                         |
| `ack_examples`            | list   | Few-shot examples, each `{user, ack}`                                                                                  |
| `routing_no_active_skill` | string | Extra routing guidance appended to the catalogue when no skill is active                                               |

```yaml theme={null}
prompts:
  ack_enabled: true
  ack_examples:
    - user: I lost my card
      ack: Let me pull that up for you.
```

`routing_no_active_skill` is the lever for greeting/closing behaviour and for
telling the orchestrator when *not* to route into a skill.

## `references`

Controls how the agent answers from retrieved knowledge.

| Key          | Description                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `embeddings` | Id of a `model_groups` entry in `integrations.yml`, used to embed `references/**/*.md`. Leave it empty to use the built-in OpenAI default. |

The same model group embeds the corpus at `rasa train` and loads it at serve
time, so keep it declared for as long as the trained model is in use.

## `conversation`

```yaml theme={null}
conversation:
  before_end:
    - default_customer_satisfaction
```

`before_end` lists skill ids that should complete before the conversation ends.
The names are rendered into the routing prompt, so the orchestrator knows to
pick those skills up before wrapping up.

## `session_config`

| Key                          | Default | Description                                                                                   |
| ---------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `session_expiration_time`    | 60      | Session lifetime in minutes. `0` disables expiry entirely. A negative value fails validation. |
| `start_session_after_expiry` | `true`  | Whether a new session auto-starts on the next message after expiry.                           |

## Voice

Voice is configured as a channel in
[`integrations.yml`](/docs/maestro/reference/integrations-yml), including the ASR and TTS
engines under that channel's `asr:` and `tts:` keys. The runtime detects a voice
channel and applies `prompts.voice_rules` from this file, so what belongs here
is the persona and the voice channel rules.

## The opening message

The first thing the agent says comes from the bundled `default_session_start`
skill's `utter_greet` response. Change it by declaring `utter_greet` in your
project `responses.yml`, as described in
[Responses](/docs/maestro/concepts/responses#overriding-built-in-messages).

## See also

* [`integrations.yml`](/docs/maestro/reference/integrations-yml): LLM provider, channels, optional Langfuse tracing
* [`memory.yml`](/docs/maestro/reference/memory-yml): project-wide memory