agent.yml

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

agent.yml

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.

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.

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

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`

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`; a per-server value overrides this default.

agent.yml

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

Reference

The `agent:` block

`persona`

`id`

`rules`

`prompts`

`references`

`conversation`

`tool_timeout`

`session_config`

Voice

Starting a conversation

See also

​The agent: block

​persona

​id

​rules

​prompts

​references

​conversation

​tool_timeout

​session_config

​Voice

​Starting a conversation

​See also

The `agent:` block

`persona`

`id`

`rules`

`prompts`

`references`

`conversation`

`tool_timeout`

`session_config`

Voice

Starting a conversation

See also