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

# Optional. Omit the block to keep skill retrieval on with the defaults below.
# skill_retrieval:
#   active: true
#   num_skills: 20
#   turns_to_embed: 1
#   should_embed_memory: true
#   embeddings: skill_embeddings

conversation:
  before_end:
    - default_customer_satisfaction

orchestrator:
  model_group: main_model
  preconditions:
    customer_authenticated:
      satisfied_when: session.project.authenticated
      resolve_with: authentication

# 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, skill_retrieval, conversation, tool_timeout, orchestrator, 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`

Required, together with orchestrator.model_group. 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.
`chunking`	How markdown files are split before embedding. Omit the key to use the defaults below. Unknown keys under `chunking` fail the load.

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.

`chunking`

At rasa train, each reference .md file is split with recursive character chunking, then each chunk is embedded. search_knowledge returns those sections, not whole files. Size and overlap are characters, not embedding tokens.

Key	Type	Default	Constraints
`chunk_size`	int	`1000`	Must be greater than `0`.
`chunk_overlap`	int	`20`	Must be `>= 0` and smaller than `chunk_size`.

agent.yml

references:
  embeddings: reference_embeddings
  chunking:
    chunk_size: 1000
    chunk_overlap: 20

Keep chunk_size well under the embedder’s maximum input. Azure OpenAI embeddings and OpenAI text-embedding-3-small / text-embedding-3-large cap input at 8192 tokens. The default 1000 characters stays under that limit; a much larger character size can still fail train. Changing chunking requires rasa train. Serving does not re-read references/ from disk. See References for when to override the defaults.

`skill_retrieval`

Optional top-level block. When it is on, each user turn offers only a retrieved subset of independently startable skills in the routing catalogue and the activate tool — not the full list. This is not knowledge search. references / search_knowledge retrieve passages from references/ to answer questions. skill_retrieval chooses which skills the model may start. Omit the block to keep retrieval on with the defaults below. Set active: false to keep today’s full legal catalogue (no index is written). Models trained before the index existed must be retrained, or set active: false and retrain. Silence-timeout turns do not search; they keep always-include, previously started, and the live skill.

Key	Type	Default	Description
`active`	bool	`true`	Whether skill retrieval runs.
`num_skills`	int	`20`	Maximum skills returned by search (`>= 0`). `0` offers none from search.
`turns_to_embed`	int	`1`	How many recent user and agent utterance lines go into the search query. `1` is only the current user message.
`should_embed_memory`	bool	`true`	Include each skill’s memory field names, descriptions, and allowed values in the index.
`embeddings`	string	empty	Id of a `model_groups` entry in `integrations.yml`. Empty uses the built-in default embedder.

Unknown keys under skill_retrieval fail the load.

agent.yml

skill_retrieval:
  active: true
  num_skills: 20
  turns_to_embed: 1
  should_embed_memory: true
  embeddings: skill_embeddings

At rasa train, independently startable skills (not engine-managed, not disabled, not hidden, with a routable entry) are indexed. Those same filters apply at runtime, so a retrieved or pinned skill stays out of the catalogue when it is not legal to route. Skills with always_include_in_prompt stay in the catalogue when they are legal, even if search missed them. Skills started in the last 20 utterance lines of the current conversation stay offered the same way. A restart or a new session starts a new window. If search or embedding fails at runtime, the turn fails the same way as an LLM outage. The agent does not fall back to listing every skill. A train with active: false and more than 20 independently startable skills logs a count-only warning.

`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. Voice silence is engine-managed: three check-ins, then goodbye and hangup on the next timeout. Any user speech resets that counter. Builders can override the bundled silence responses; the retry count is not configurable. Default wording is on Silence timeout.

`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. The other bundled skills and their default wording are in Default skills.

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 the first real utterance can be handled immediately.

rasa shell, the Inspector, and the built-in voice channels already send /session_start. See Start a conversation.

`orchestrator`

Names the model group that runs the agent, and binds skill precondition names. The group itself — provider, model, and API key — is defined in integrations.yml model_groups.

agent.yml

orchestrator:
  model_group: main_model
  max_prompt_tokens: 12000

Key	Required	Default	Description
`model_group`	Yes	none	Id of a group declared under `model_groups` in `integrations.yml`.
`max_prompt_tokens`	No	`8000`	Positive token budget for the assembled prompt.
`preconditions`	No	none	How each skill precondition is cleared. See below.

A missing orchestrator: block, or a blank model_group, fails the load. Changing model_group needs a retrain. Changing the models inside that group in integrations.yml needs a restart. A leftover llm: section in integrations.yml is invalid.

`preconditions`

Maps each precondition name to how the engine clears it before a skill may start. The name must match a skill’s precondition: field (for example customer_authenticated on Card Replace). Define an entry here for every precondition: used in the project.

agent.yml

orchestrator:
  model_group: main_model
  preconditions:
    customer_authenticated:
      satisfied_when: session.project.authenticated
      resolve_with: authentication
      unmet_utterance: true

Key	Required	Description
`satisfied_when`	Yes	Condition string. When true, the waiting skill starts normally.
`resolve_with`	Yes	Skill id to call while the waiting skill is pending. That skill must not declare its own `precondition`.
`unmet_utterance`	No	Default `true`. After one failed resolver attempt, utter `utter_precondition_unmet`. Set `false` when the resolver already explained. Default text is on Default skills.

The waiting skill stays in routing. The engine parks it as pending, calls the resolver, then promotes or abandons — no resume prompt. If resolve_with is already the active skill (for example the session opener is also the resolver), the engine parks the waiting skill under that run instead of interrupting it and starting a second resolver. See skill.md precondition.

File Reference

Language

Tools

Customizations

Runtime

Observability

Prompts

Schemas

The `agent:` block

`persona`

`id`

`rules`

`prompts`

`references`

`chunking`

`skill_retrieval`

`conversation`

`tool_timeout`

`session_config`

Voice

Starting a conversation

`orchestrator`

`preconditions`

See also

​The agent: block

​persona

​id

​rules

​prompts

​references

​chunking

​skill_retrieval

​conversation

​tool_timeout

​session_config

​Voice

​Starting a conversation

​orchestrator

​preconditions

​See also

The `agent:` block

`persona`

`id`

`rules`

`prompts`

`references`

`chunking`

`skill_retrieval`

`conversation`

`tool_timeout`

`session_config`

Voice

Starting a conversation

`orchestrator`

`preconditions`

See also