> ## Documentation Index
> Fetch the complete documentation index at: https://rasa.com/docs/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

# Optional. Wall-clock limit for local @tool and MCP tool calls (seconds).
# tool_timeout: 30

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`, `tool_timeout`, 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.

## `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. When omitted, enabled on **voice** turns and disabled on **text** turns. Set explicitly to override both modalities. |
| `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.

## `tool_timeout`

Optional top-level key. Wall-clock timeout in seconds for tool calls.

| Key | Required | Default | Description |
| - | - | - | - |
| `tool_timeout` | No | `10` | Positive finite number of seconds. Applies to local `@tool` functions. Also used for imported MCP tools when the server omits its own `tool_timeout` in [`integrations.yml`](https://rasa.com/docs/mantle/reference/integrations-yml#mcp_servers); a per-server value overrides this default. |

```yaml agent.yml theme={null}
tool_timeout: 30
```

When a tool exceeds the limit, the runtime cancels the call and returns an
error payload to the LLM so it can recover (for example, retry or ask the
user). Raise this value for slow backends (databases, long HTTP calls); leave
it unset to keep the `10` second default.

## `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`](https://rasa.com/docs/mantle/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.

## Starting a conversation

The bundled `default_session_start` skill does not greet. Who speaks first
decides whether you should override it:

* **Agent speaks first**: override `default_session_start` with a greeting and
  have the channel send `/session_start` as the first user message.
* **User speaks first**: leave the bundled skill silent so Mantle handles the
  first real utterance immediately.

`rasa shell`, the Inspector, and the built-in voice channels already send
`/session_start`. See
[Start a conversation](https://rasa.com/docs/mantle/orchestration/runtime-loop.md#start-a-conversation).

## See also

* [Start a conversation](https://rasa.com/docs/mantle/orchestration/runtime-loop.md#start-a-conversation): who speaks
  first, and when to override `default_session_start`
* [`integrations.yml`](https://rasa.com/docs/mantle/reference/integrations-yml): LLM provider, channels, MCP servers (per-server `tool_timeout`), optional Langfuse tracing
* [Tools](https://rasa.com/docs/mantle/reference/tools.md): `@tool` interface and timeout behaviour
* [`memory.yml`](https://rasa.com/docs/mantle/reference/memory-yml): project-wide memory


## Related topics

- [integrations.yml](https://rasa.com/docs/mantle/reference/integrations-yml.md)
- [Authoring files](https://rasa.com/docs/mantle/reference/schemas/index.md)
- [Build a voice agent](https://rasa.com/docs/mantle/voice/tutorial.md)
- [Prompt templates](https://rasa.com/docs/mantle/reference/prompt-templates.md)
- [Writing prose](https://rasa.com/docs/mantle/best-practices/writing-prose.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.