# Mantle > Build AI agents with exactly the control you need, and no more. Mantle is a framework for building conversational AI agents with progressive control: start with prose instructions and auto-discovered tools, then add framework-enforced guarantees incrementally without restructuring. A skill is a folder. `skill.md` is the only required file; `memory.yml`, `responses.yml`, `tools.py`, and `references/` are added as the skill needs them. ## Docs ### Get Started - [Introduction](/): What Mantle is, progressive control, what a skill looks like - [Getting Started](/getting-started): Install, build your first agent with the Rasa Copilot, and talk to it by chat or voice. Run `rasa train`, `rasa run`, and `rasa inspect` from the agent project root - [Skills](/skills): The building block of every agent ### Building Skills - [Instructions](/concepts/instructions): The plain-language body of a skill - [Tools](/concepts/tools): Typed functions a skill can call - [Memory](/concepts/memory): Values a skill tracks across a conversation - [References](/concepts/references): Knowledge the agent answers questions from; markdown is chunked at train time - [Responses](/concepts/responses): Verbatim wording the LLM never rewrites ### Progressive Control - [Tool Constraints](/build-guide/tool-constraints): requires:, requires_confirmation:, on_success:/on_failure: - [Scoped Instructions](/build-guide/scoped-instructions): if: markers for deterministic branching - [Ordered Blocks](/build-guide/ordered-blocks): Strict sequence control - [Sub-skills](/build-guide/sub-skills): Composition via @skill. ### Voice - [Voice agents](/voice/overview): How Mantle runs the same skills in a voice conversation, and what it handles for you - [Build a voice agent](/voice/tutorial): Tutorial taking a card replacement skill from first draft to phone-ready - [Designing for voice](/voice/designing-for-voice): Greetings, acknowledgements, lists, exact numbers, confirmations, keypad input, and ending calls - [Connect a phone line](/voice/telephony): Telephony channels and their configuration - [Test and monitor voice](/voice/testing): Inspector voice mode, voice traces, and voice metrics ### Best Practices - [Writing prose](/best-practices/writing-prose): Wording a description so the right skill is picked, and a body the model follows - [When prose is not enough](/best-practices/when-prose-is-not-enough): Memory, tool constraints, responses, and blocks for the cases a sentence in the body cannot cover ### Testing - [Simulate and evaluate](/testing/simulating-and-evaluating): Simulated conversations and deterministic assertions before shipping to production - [Scenarios](/testing/scenarios): Who the simulated user is, how the conversation starts, and what success looks like - [Configuration and results](/testing/configuration-and-results): Models, prompts, how a run is judged, and how to read the result files ### Orchestration - [Mantle](/mantle): The orchestrator - [Runtime Loop](/mantle/runtime-loop): Deterministic-first loop - [Guarantees](/mantle/guarantees): What the framework enforces - [Context](/mantle/context): How Mantle manages conversation context - [Skills & Routing](/mantle/skills): Skill selection and stacking ### Reference - [Project structure](/reference/project-structure): Every file and folder an agent recognises, and which are required. Run Mantle CLI commands from the agent project root - [Conditions](/reference/conditions): The memory expression language used by requires:, if:, complete_when:, next: - [skill.md](/reference/skill-md): Frontmatter properties and body format - [agent.yml](/reference/agent-yml): Identity, persona, rules, prompt tuning, and `voice.silence_timeout` - [integrations.yml](/reference/integrations-yml): LLM provider, channels, MCP servers, voice ASR/TTS, tracing (Langfuse, OTLP, Jaeger), OTLP metrics, event broker, timer store, call recordings, remote model server (`rasa_model_server:`) - [memory.yml](/reference/memory-yml): Memory schema, types, visibility - [responses.yml](/reference/responses-yml): Response templates, interpolation, and static buttons - [Ordered block steps](/reference/ordered-block-steps): Step kinds, step fields, branching, and `ask_before_filling` collects - [Tools](/reference/tools): Tool interface, ToolContext, built-in framework tools, and `ask_before_filling` confirmation writes - [Hooks](/reference/hooks): Observe and modify insertion points (`on_incoming_message` / `modify_incoming_message` wired on final user text; `on_turn_started` / `on_turn_finished` wired around each Mantle turn; `on_model_request` / `modify_model_request` and `on_model_response` / `modify_model_response` wired; `on_outgoing_message` / `modify_outgoing_message` wired on completed agent utterances; `on_tool_call` / `modify_tool_call` and `on_tool_result` / `modify_tool_result` wired on the tool-call batch path; `on_knowledge_query` / `modify_knowledge_query` and `on_knowledge_results` / `modify_knowledge_results` wired around `search_knowledge`; other points authorable but not invoked yet) - [Speech providers](/reference/speech-providers): Supported speech recognition and synthesis providers, with their API keys, defaults, and settings - [Custom speech providers](/reference/custom-speech-providers): Write your own speech recognition or synthesis provider integration (beta) - [Custom integrations](/reference/custom-integrations): Write a Python class that replaces a built-in Mantle component for storage, timers, events, knowledge, channels, or speech, and name it in integrations.yml. - [Custom lock store](/reference/custom-lock-store): Write a lock store that keeps conversation locks in your own backend, or change the built-in Redis lock store. - [Custom timer store](/reference/custom-timer-store): Write a session timer store that keeps timers in your own backend, or change the built-in Redis timer store. - [Custom tracker store](/reference/custom-tracker-store): Write a tracker store that saves conversation history in your own database, or change the built-in tracker stores (SQL, Redis, MongoDB, DynamoDB). - [Custom event broker](/reference/custom-event-broker): Write an event broker that sends conversation events to your own messaging system, or change a built-in broker. - [Custom knowledge store](/reference/custom-knowledge-store): Write a knowledge store that searches documents in your own index, or change the built-in FAISS store, and register it under knowledge_stores. - [Custom channel](/reference/custom-channels): Write an input channel that receives messages from your own service, or change a built-in connector such as Twilio, and register it under channels. - [Execution Loop](/reference/execution-loop): The per-turn loop as a spec - [Constraint Table](/reference/constraint-table): Framework vs LLM at each control level - [Builtin skills](/reference/builtin-skills): Bundled lifecycle skills and the default wording of packaged responses - [Observability](/reference/observability): The OpenTelemetry traces emitted per turn - [Metrics](/reference/metrics): The metrics available for monitoring agents - [Conversation events](/reference/events): Mantle tracker and event-broker JSON shape (ProtoJSON) - [Assertions](/reference/assertions): Deterministic checks a scenario can make against tracker events - [System Prompt](/reference/system-prompt): Prompt assembly order and agent.yml overrides - [Prompt templates](/reference/prompt-templates): The assembled system prompt for each situation, verbatim - [Authoring files](/reference/schemas/index): JSON Schema for the authoring files, generated from the authoring models and not versioned ### More - [What's Next](/whats-next): Designed but not yet built - [Changelog](/changelog): Builder-facing changes per release ## Key facts for code generation ### Skills - The skill id is the folder name. The frontmatter `name:` is a display name. - `skill.md` is YAML frontmatter, then a markdown body. A skill needs prose, an ordered block, or both. - Prose branches with `if: ` on the first line of a paragraph. Write one `if:` paragraph per case, each stating its own condition. `else:` belongs in an ordered-block `next:` list. - Ordered-block ids are fence attributes: `:::ordered_block id=pick_card`. - `@block.` enters a block in the same skill; `@skill.` runs another skill and resumes the parent. Tools are named in plain prose. - A value written by the block, such as an initial value, can already be set and is still asked about. `activate` and `set_memory` do not store that field until the question has been asked. Until that answer is written, tool gates and `next:` branches in that block treat the field as unset. Other blocks in the same skill see the stored value, including an initial value. Correcting an earlier answer asks the question again, including when it was still waiting; a value offered with the correction is not the answer. ### Conditions - Conditions are **strings**: `requires: "session.project.authenticated"`. - Memory references are three segments: `session..`. - Use a folded `>` scalar for a multi-line condition. ### Memory - Skill memory uses `schema:` with `public:` / `private:`, plus optional `access:`. Project memory (root `memory.yml`) is a flat map of entry name to attributes. - Types: `text`, `bool`, `int`, `float`, `list`, `json`, `categorical`, `any`. Enums use `enum_values:`. - `llm_settable: true` lets the LLM write a **skill** entry via `set_memory`. Collect-step targets are settable regardless. Project fields are not LLM-writable (`set_memory` or `collect:`); train rejects those. First write is a tool, a memory validation tool, or session-start metadata on fields with `seed: true`. By default the value then stays locked. `mutable: true` allows later overwrites. `writable_by` is project-only and lists skill directory ids allowed to write, including on a write-once field; omit it and any skill may write. Session-start seed fills an unset `seed: true` field without checking `writable_by` and never overwrites. - Set project values appear under `### Project Memory` in the prompt (including routing). `### Memory:` is skill-scoped only. - Every key a tool writes must be declared in a `memory.yml`, or `rasa train` fails with `undeclared_memory_write`. - A tool's bare entry name resolves against its own skill's schema, then project memory. Another skill's `public` field is readable in conditions and reaches a tool as an argument. ### Tools - Import from `rasa.mantle.tools.decorator` (`tool`, `ToolContext`) and `rasa.mantle.tools.result` (`ToolResult`), not `rasa_sdk`. - A tool is `async`, takes `context: ToolContext = None`, and returns `ToolResult`. `@tool` takes `description=` as a keyword argument. - `context.send()` is a coroutine: `await context.send("…")`. - `tool_constraints` gate a tool at schema build and again at dispatch, including for an ordered-block `execute_tool:` step. Both fail closed. - `orchestrator.tool_constraints` in `agent.yml` can turn off `cancel`, `complete`, `search_knowledge`, `cannot_help`, and `listen`, and can replace a built-in tool's offered description with `description` (whole-string override). `activate`, `enter`, and `set_memory` accept `description` but cannot be turned off. Fixed system-prompt instructions still apply; keep tool text aligned. `hangup` and `resolve_tool_confirmation` cannot be named. Omit `description` to keep engine defaults (text and voice differ for `listen` when omitted). A retrain is required. Ordered-block `execute_tool: listen` is separate from the LLM `listen` tool. ### Responses - Each name in `responses.yml` maps to a list of variants; at delivery the engine selects one (first matching `condition` in YAML order, else the single default variant). The registry is flat, so names are global. - Four things fire a response: a frontmatter `utter:` trigger (`on: activate` or `when:`), `on_success:` / `on_failure:` on a tool constraint, the `requires_confirmation:` utterances, and an ordered-block `utter:` or `utterance:`. - Interpolation takes `{session..}` or the bare `{entry}` form. Prose in `skill.md` is not interpolated. - Variants may declare `buttons:` with a required `title` and optional `payload`. Plain-text payloads (or an omitted payload defaulting to the resolved title) are handled like typed user input; the LLM may call `set_memory` on a collect step. - `set:` payloads (`set:session..=` or `set:session.project.=`) write memory directly on tap (`llm_settable` not required), run memory validation tools, and keep the raw payload out of the LLM prompt. The payload must match a button on the latest agent message. Project payloads write `project.` authoritatively (write-once unless `mutable: true`, and only from a skill in `writable_by` when that list is set). Stale, missing-field, invalid-value, or non-writable taps utter packaged `utter_set_memory_button_skipped` (overridable; uses inbound metadata `button_title` when the channel forwards it) and end without calling the LLM. ### Project config - `agent.yml` requires an `agent:` block with a non-empty `persona` and an `orchestrator:` block with `model_group` (optional `max_prompt_tokens`, default 8000). `orchestrator`, `rules`, `prompts`, `references`, `conversation`, `tool_timeout`, `session_config`, and `voice` are top-level siblings, not nested inside `agent:`. - Optional `voice.silence_timeout` is seconds to wait after the caller stops speaking. Default is `30`. Must be greater than `0`. A `silence_timeout` on the voice channel overrides it. - Optional `references.chunking` (`chunk_size`, `chunk_overlap`) splits `**/*.md` under `references/` at `rasa train` before embedding. Units are **characters**, not tokens. Omit the key for defaults `1000` / `20`. Overlap must be smaller than size; unknown keys under `chunking` fail the load. `search_knowledge` returns those sections, not whole files. Keep `chunk_size` well under the embedder input limit (8192 tokens on Azure OpenAI embeddings and OpenAI `text-embedding-3-*`). Changing chunking or reference files requires `rasa train`. - Optional top-level `tool_timeout` (seconds) caps local `@tool` calls and is the fallback for MCP tools when a server omits its own timeout. Default is `10`. - `integrations.yml` requires a `model_groups:` entry matching `orchestrator.model_group`, and a `channels:` block. Provider settings and `api_key: ${ENV_VAR_NAME}` belong on models in that group. A leftover `llm:` section is invalid. - Optional `mcp_servers:` is a list of named servers (`name`, `url`, auth via `token` / `api_key` / `oauth` / `module`, optional `tool_timeout` and `meta_map`). Per-server `tool_timeout` overrides `agent.yml`; otherwise the agent default (or `10`) applies. Skills import tools with `mcp/:` in `import_tools`; the LLM sees the bare tool name. - The model group named by `orchestrator.model_group`, and `channels:`, are read from the live project. Changing the models inside that group needs a restart. Changing `orchestrator.model_group` needs a retrain. Embeddings groups are read from the packaged snapshot, so changing embeddings needs a retrain. - Voice ASR and TTS are configured under a voice channel's `asr:` and `tts:` keys in `integrations.yml`. - Optional tracing lives under `tracing:` in `integrations.yml`: one tracer (`langfuse`, `otlp`, or `jaeger`), or a list with at most one `langfuse` entry and at most one `otlp` or `jaeger` entry. Langfuse keys must use `${ENV_VAR}` references; they resolve at Langfuse configure time, not YAML load. Example projects ship the block commented until `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` are set. - Optional OTLP metrics live under `metrics:` in `integrations.yml` (`type: otlp`, `endpoint`), independent of tracing. - Mantle reads `tracing:`, `metrics:`, `event_broker:`, `timer_store:`, `tracker_store:`, `lock_store:`, `secrets_manager:`, `recordings:`, and the remote model server only from `integrations.yml`. An `endpoints.yml` file at the project root fails startup, and passing `--endpoints` fails too. `privacy` in `endpoints.yml` has no effect. Configure the inbound A2A server with a top-level `a2a_server` block in `integrations.yml`. A push callback that sets a token or authentication must use `https`. Get and list of a push config omit the token and credentials; send them again to update it. When `auth` is set, the first authenticated caller of a `context_id` owns that conversation. The owner includes whether the caller came from `sub`, `preferred_username`, or `client_id`; changing that claim invalidates existing contexts. Route every request for a `context_id` to the same replica; a generic session cookie, source IP, or connection affinity is not that key. Rotating the JWT secret or public key invalidates existing A2A contexts: the same caller no longer matches conversations they already own, and follow-ups are rejected as context not found. CALM-only keys (`nlg`, `nlu`, `action_endpoint`, `vector_store`, `interaction_handling`) fail `rasa train` in `integrations.yml`. The old `interaction_handling.global_silence_timeout` belongs in `agent.yml` as `voice.silence_timeout`. - Optional `event_broker:` streams conversation events. `type` defaults to `pika`; also `sql`, `file`, `kafka`, `concurrent_kafka`, or a custom class path. `url` is required for `pika`, `kafka`, and `concurrent_kafka`. For Kafka types, `url` may be a string or a list of bootstrap servers. `pika` also requires `username` and `password` (even with an `amqp://` URL). Do not set `host` for `pika` or `sql`. `file` uses `path`. Omit the section to publish no events. An invalid block fails `rasa train` and startup (`mantle.validation.config.invalid_event_broker`). - Optional `timer_store:` stores session timers. `type` is `in_memory` (the default when omitted), `redis` (`host` and `port`; `url` is a deprecated alias for `host`), or a custom class path. Omit the section to keep timers in memory. An invalid block fails `rasa train` and startup (`mantle.validation.config.invalid_timer_store`). - Optional `rasa_model_server:` is the remote model server (`url` required; optional `token` and `wait_time_between_pulls`). It is not the `models` list inside a `model_groups` entry. `wait_time_between_pulls` defaults to 100 seconds; `0` pulls once and does not refresh. Omit the section to load a local model or use `--remote-storage`. With no local model, `rasa run` points at `integrations.yml`. An invalid block fails `rasa train` and startup (`mantle.validation.config.invalid_model_server`). - Optional `tracker_store:` stores conversation trackers. `type` is `in_memory` (the default when omitted), `redis`, `mongod`, `sql`, `dynamo`, or a custom class path. Omit the section to keep conversations in memory. A literal password, token, AWS access key, or credential URL warns at train (`mantle.validation.config.literal_secret`) and does not fail the build. An invalid block fails `rasa train` and startup (`mantle.validation.config.invalid_tracker_store`). - Optional `lock_store:` locks a conversation across overlapping turns. `type` is `in_memory` (the default when omitted), `redis`, `concurrent_redis`, or a custom class path. Use `redis` or `concurrent_redis` with more than one worker or replica. An in-memory lock store with several workers logs a startup warning. An invalid block fails `rasa train` and startup (`mantle.validation.config.invalid_lock_store`). - Optional `secrets_manager:` loads tracker-store credentials from Vault (`type: vault`). `VAULT_URL`, `VAULT_TOKEN`, and `VAULT_RASA_SECRETS_PATH` override the same fields and still work when the section is omitted (`SECRET_MANAGER=vault`). A literal token warns at train. An invalid block fails `rasa train` and startup (`mantle.validation.config.invalid_secrets_manager`).