Skip to main content
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
The file has two levels. id, language, and persona are the agent’s identity and live inside the agent: block. rules, fillers, knowledge_answering, 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.

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

fillers

The short message before a tool call. Every key is optional; an empty or absent value falls back to the built-in default.
Unknown keys under fillers fail the load. On voice channels, the pauses between agent messages are set per channel in integrations.yml: pause_after_filler after a filler, and pause_between_messages between other consecutive messages.

prompts

Settings that are not the pre-tool line or a channel style. Unknown keys are ignored.

knowledge_answering

Controls how the agent answers from retrieved knowledge. Unknown keys under knowledge_answering 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.
agent.yml
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, which rebuilds the index. Serving does not re-read references/ from disk. top_k is not stored in the index; it is read from the packaged spec when the model loads, so changing it also needs another train. See References for when to override the chunking defaults.

skill_retrieval

Optional top-level block. When retrieval runs, each user turn offers only a retrieved subset of startable skills in the routing catalogue and the activate tool — not the full list. A startable skill is one the model can start itself with activate. Retrieval indexes and can return only those skills. A skill is startable when it is not engine-managed, not disabled, not hidden, and it has a routable entry. Other skills stay out of the index and out of search results:
  • Engine-managed skills are started by the engine (for example silence timeout). They never appear in the routing prompt or the activate list, so retrieval does not return them.
  • hidden and disabled skills are omitted from the routing catalogue, so they are not returned either.
  • A skill with no routable entry is internal. call:, link:, and resolve_with can still start it, and it does not take a search slot.
This is not knowledge search. knowledge_answering / search_knowledge retrieve passages from references/ to answer questions. skill_retrieval chooses which startable skills the model may start. Omit the block, or omit active, to leave retrieval off. The full legal catalogue stays, and no index is written. Set active: true to opt in. Retrieval runs only when there are more startable skills than num_skills. Skills that are not startable do not take a num_skills slot. At or below that count, train does not write the index and logs a warning with both counts. The turn keeps the full catalogue. active stays true. The next train writes the index once the catalogue is larger than num_skills, or once num_skills is lowered below the current count. When retrieval runs, the index is required. A model whose startable count is above num_skills and was trained without that index must be retrained. Silence-timeout turns do not search; they keep always-include, previously started, and the live skill. Unknown keys under skill_retrieval fail the load. num_skills below 1 fails the load. To keep every legal skill, set active: false.
agent.yml
At rasa train, when retrieval runs, only startable skills are indexed. The same filter applies at runtime, so a retrieved or pinned skill stays out of the catalogue when the model cannot start it. Engine-managed, hidden, disabled, and skills with no routable entry stay out because they never appear in the routing prompt. 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 while retrieval is running, 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 startable skills logs a warning with that count. The catalogue is large enough that turning retrieval on would filter it. A train with active: true and a startable count at or below num_skills logs a warning with both counts and does not write the index.

conversation

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.
agent.yml
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

Voice

Voice is a channel in integrations.yml. Speech recognition and synthesis are model groups named by asr and tts here, or on that channel. The runtime detects a voice channel and applies the voice settings from this file:
agent.yml
See Voice agents for what else changes on a call, and Designing for voice for how to use these settings.

asr and tts

Optional, under the top-level voice: key. Each value is the id of a speech model group in integrations.yml. asr is speech recognition. tts is speech synthesis. Leave a side empty when every voice channel sets that side itself. A string on the channel replaces that side. The Inspector still uses Deepgram when both the channel and these keys omit a side. Every other voice channel fails to start until the missing side is set here or on the channel. A value that is not a string, or that names a group the side cannot use, fails rasa data validate.
agent.yml
Changing either id, or the group it names, is read from the live project. Restart to pick it up. A retrain is not required.

silence_timeout

Optional, under the top-level voice: key. This is where interaction_handling.global_silence_timeout from endpoints.yml moves. A silence_timeout on the voice channel overrides this value. Omit the key to keep 30 seconds.
agent.yml

interruptions

Optional, under the top-level voice: key. Sets, for every voice channel:
  • whether the caller can talk over the agent
  • when short speech is ignored as a backchannel
  • an optional cooldown after a burst of interruptions
A voice channel’s interruptions block overrides only the keys it sets; the others come from this block. Omit the block to keep the defaults. Unknown keys under interruptions fail the load.
The Inspector always sets enabled itself, true by default, so voice.interruptions.enabled has no effect there. Set enabled on the Inspector channel in integrations.yml to change it.
agent.yml
See How backchannels are classified for how short speech is scored.

cooldown

Optional, under voice.interruptions. After too many interruptions in a short time, the agent ignores further interruptions until a cooldown passes. Use it when a caller and the agent keep cutting each other off. A voice channel’s interruptions.cooldown block in integrations.yml replaces this one as a whole. Omit the block to leave the protection off.
agent.yml

Starting a conversation

The bundled builtin_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 Builtin skills.
  • Agent speaks first — override builtin_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, binds skill precondition names, and optionally tunes built-in tools. The group itself — provider, model, and API key — is defined in integrations.yml model_groups.
agent.yml
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
satisfied_when is decided only from memory that was already saved. Values stated on activate are not part of that check, and the skill’s own fields are reset first. See the precondition check. 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. When that running resolver is waiting on a collect step with an utterance, the engine repeats that question (with its buttons) right away, so the user sees what is still needed before the queued skill can start. Asking for the queued skill again repeats the question again. The question is also repeated when the agent answers such a request in its own words, and when it declines an off-topic request and returns to the step in the same turn. A collect with no utterance has no question for the engine to repeat, so the model asks for the field again in its reply. See skill.md precondition.

tool_constraints

Optional mapping from a built-in tool name to that tool’s levers. Omitting the section, or omitting a tool inside it, keeps the default offer rules. enabled: true does not force a tool onto a turn where it would not be offered. The section is packaged with the model, so a change takes effect on the next train. The offer rules and the per-tool lever table are on Built-in framework tools.
agent.yml
activate, enter, and set_memory must stay enabled: none of them accept enabled: false. A conversation cannot start a skill, enter a skill, or record memory without them. You may still set description on any of the three to replace the default tool description. description changes what the model sees in the tool list for that built-in. The system prompt still includes fixed instructions the engine adds — for example when to call search_knowledge, to answer from tool results before complete(), the resume-prompt set_memory bullet while the continue-interrupted skill is active, out-of-scope handling while cannot_help is offered, and to call activate when routing. Those prompt lines are not removed when you set description. Keep tool wording and prompt instructions aligned so the model does not see conflicting guidance. A custom description replaces the entire default tool string the model sees, including per-turn suffixes the engine appends when the key is omitted (for example the set_memory correction rule or the activate hint to use enter). Copy the published defaults from the tools reference and merge your wording when you customize. Turn complete off only when every skill that would have used it finishes without the orchestrator: a complete_when.condition with no criteria, or an ordered block that reaches END. Otherwise leave it on and use description if you need different when-to-call wording. requires_confirmation is rejected on every built-in tool other than cancel, and the error names that tool. Turning off search_knowledge still allows cannot_help before any search. The references index stays packaged. Turning off only cannot_help leaves search in place. A declined optional step is not a cancel. Record it with set_memory and continue the skill. That rule is in the cancel and set_memory descriptions, not in a separate prompt line. listen accepts enabled and description. Turning it off does not change ordered-block execute_tool: listen. When description is set, the same string is used on voice and text turns. See Built-in framework tools. hangup, resolve_tool_confirmation, and unknown names fail validation. The error names the tool.

cancel.requires_confirmation

Optional confirmation before the built-in cancel runs. The pause matches a skill tool’s requires_confirmation. The user hears one question. If they confirm, cancel proceeds the way it does today: a side question ends and the paused task is offered again, a called step drops with its parent, and confirming on the resume prompt drops the paused task. If they decline, the skill stays in place. Omitting the block, or enabled: false, keeps immediate cancel. Do not also tell the model, in a skill body or in rules, to ask before cancelling. That asks twice. Name both lines:
agent.yml
Or leave both lines to the model:
agent.yml
A set name must exist in responses.yml and have a non-empty body. A missing or empty name fails train. A bare requires_confirmation: with nothing under it fails train. While the gate is on and another confirmation is already pending, the cancel ask replaces that question. A yes drops the skill and clears the open tool question. A no leaves the skill in place. A reply that neither confirms nor declines leaves the cancel question waiting. The model brings the user back in its own words. The original line is not played again. cancel is offered only while a skill is active, including the resume prompt. A call with nothing open does not ask and does not cancel. With enabled: false on cancel, the tool is not offered and the confirmation never runs.

privacy

Optional top-level block for tracker-store anonymization and deletion cron jobs. It accepts only tracker_store_settings. A rules list is rejected: per-field anonymization belongs on memory fields with pii: true in memory.yml. Mantle ignores a privacy block in endpoints.yml at runtime. Configure the event broker (stream_pii, anonymization_topics) in integrations.yml. Fields marked pii: true are masked on published events. Session-start metadata (system.session_started_metadata) is masked whenever a privacy block or a pii: true field is present. A stored session_started_metadata event is still masked.

See also

  • Start a conversation: who speaks first, and when to override builtin_session_start
  • integrations.yml: model groups, channels, MCP servers (per-server tool_timeout), optional tracing and metrics
  • Speech providers: built-in ASR and TTS providers and their settings
  • Tools: @tool interface and timeout behaviour
  • memory.yml: project-wide memory
  • skill.md: always_include_in_prompt and other skill frontmatter