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

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, 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 (default `true`)
`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.

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

The opening message

The first thing the agent says comes from the bundled default_session_start skill’s utter_greet response. Change it by declaring utter_greet in your project responses.yml, as described in Responses.

File Reference

Language

Tools

Runtime

Prompts

The `agent:` block

`persona`

`id`

`rules`

`prompts`

`references`

`conversation`

`session_config`

Voice

The opening message

See also

​The agent: block

​persona

​id

​rules

​prompts

​references

​conversation

​session_config

​Voice

​The opening message

​See also

The `agent:` block

`persona`

`id`

`rules`

`prompts`

`references`

`conversation`

`session_config`

Voice

The opening message

See also