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
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.
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
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
activatelist, so retrieval does not return them. hiddenanddisabledskills are omitted from the routing catalogue, so they are not returned either.- A skill with no routable entry is internal.
call:,link:, andresolve_withcan still start it, and it does not take a search slot.
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
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
10 second default.
session_config
Voice
Voice is a channel inintegrations.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
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
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
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 bundledbuiltin_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_startwith a greeting and have the channel send/session_startas 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
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-servertool_timeout), optional tracing and metrics- Speech providers: built-in ASR and TTS providers and their settings
- Tools:
@toolinterface and timeout behaviour memory.yml: project-wide memoryskill.md:always_include_in_promptand other skill frontmatter