> ## Documentation Index
> Fetch the complete documentation index at: https://mantle.rasa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install Mantle, build your first agent with the Rasa Copilot, and talk to it by chat or voice.

This guide takes you from an empty folder to a working, tested agent that you
can chat with or talk to. You'll install Mantle, then use the **Rasa Copilot**,
a set of MCP tools that plug into your IDE, to build, evaluate, and refine your
first skill in a tight loop.

The skill you build here works on both text and voice without changes. Mantle
adapts how it speaks to the channel the conversation arrives on, so a voice agent
is the same project with speech switched on.

## The build loop

Agent development works in a loop. Rasa provides you with a harness that allows you to accelerate that loop and if you're ready for it - run it on autopilot.

```mermaid theme={null}
flowchart LR
    A[Transcripts / Prompt] --> B[Agent]
    B --> C[Evals + Sims]
    C --> D[Recommendations to fix]
    D --> E[Test / Inspect]
    E -->|loop| A
```

| Stage | What happens |
| - | - |
| **Requirements + References** | You give the Copilot real conversation transcripts or a plain-language description of the skill you want. |
| **Agent** | The Copilot scaffolds skills, tools, and config into your project. |
| **Evals + Simulations** | An LLM plays the user and runs multi-turn conversations against your agent, scored against goals you define. |
| **Insights + Recommendations** | The Copilot reads the results and proposes concrete changes to instructions, constraints, and tools. |
| **Test / Inspect** | You chat with the agent, or talk to it out loud, in the Inspector and step through what happened turn by turn. |

## 1. Install Mantle

Mantle ships in the `rasa-pro` package. Install it into a fresh virtual
environment on Python 3.10 to 3.13:

```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate
pip install rasa-pro==3.22.0.dev5
```

Check it worked:

```bash theme={null}
rasa --version
```

> [!NOTE]
>
> Mantle is currently pre-release, so pin the exact version rather than letting
> pip resolve the latest stable one.

You will also need a Rasa license key and an API key for your LLM provider. The
setup wizard in the next step asks for both.

To talk to your agent by voice, you also need an API key for a speech provider.
This guide uses [Deepgram](https://deepgram.com). Voice is optional: everything
in this guide works over text without it.

## 2. Create a project

Run `rasa init` to start the setup wizard. It also connects the coding agents
you pick to the rasa-tools MCP server:

```bash theme={null}
rasa init --engine mantle
```

The wizard walks you through the full setup:

1. Asks where to create your project
2. Asks which coding agents to set up (Claude Code and Cursor are pre-selected;
   VS Code and OpenAI Codex are also available), then installs the Mantle skills
   for them, registers the rasa-tools MCP server, and downloads the Mantle
   documentation
3. Collects your keys and writes them to a `.env`
4. Validates and trains your agent
5. Opens the Inspector so you can chat with it immediately

To pick the coding agents without the prompt, pass them with `--ides`, for
example `rasa init --engine mantle --ides claude,vscode`. With `--no-prompt` and
no `--ides`, Claude Code and Cursor are set up; pass `--ides ''` to skip
coding-agent setup.

Once it completes, your project looks like this:

```bash theme={null}
my-agent/
├── agent.yml                     # identity, persona, orchestrator, global rules
├── integrations.yml              # model groups, channels, optional tracing and metrics
├── AGENTS.md                     # context for your coding agent
├── .env                          # secrets, written by the wizard
└── skills/
    └── view_transactions/
        ├── skill.md              # instructions + control declarations
        ├── memory.yml            # what this skill remembers
        └── tools.py              # auto-discovered tools
```

That is what the scaffold writes. A project can hold more: a project-root
`memory.yml` for cross-skill state, `responses.yml` for verbatim wording,
`references/` for knowledge, and `tools/` for tools shared between skills. See
[Project structure](https://mantle.rasa.com/reference/project-structure.md) for the full layout and which
files are required.

## 3. Set your environment variables

The wizard collects your keys and writes a `.env`. To change them later, edit it
directly:

```bash .env theme={null}
RASA_LICENSE=""
OPENAI_API_KEY=""
DEEPGRAM_API_KEY=""   # optional: lets you talk to the agent in the Inspector
```

The wizard does not ask for `DEEPGRAM_API_KEY`. Add it yourself if you want to
try voice in [step 7](#7-talk-to-your-agent), and set the Inspector to use
Deepgram Flux in `integrations.yml`:

```yaml integrations.yml theme={null}
model_groups:
  - id: inspector_asr
    models:
      - provider: deepgram_flux
        api_key: ${DEEPGRAM_API_KEY}
        language_map:
          en:
            language: en
            model: flux-general-en
  - id: inspector_tts
    models:
      - provider: deepgram_flux
        api_key: ${DEEPGRAM_API_KEY}
        language_map:
          en:
            model: flux-alexis-en

channels:
  rest:
    enabled: true
  inspector:
    enabled: true
    asr: inspector_asr
    tts: inspector_tts
```

This guide uses Deepgram, but you can use the speech providers of your choice:
See [Speech providers](https://mantle.rasa.com/reference/speech-providers.md) to switch.

To use a different model, edit the group named by `orchestrator.model_group`
in [`integrations.yml`](https://mantle.rasa.com/reference/integrations-yml).

## 4. Connect your coding agent

If you picked your coding agents during `rasa init`, their Mantle skills are
already installed, the rasa-tools MCP server is registered, and the full Mantle
documentation is bundled at `.rasa/docs/mantle/`. Open the project in your coding
agent and it has the context it needs to build and iterate on Mantle skills, plus
the reference to look up anything the skills do not cover.

For an existing project that wasn't created with `rasa init`, if you skipped
coding-agent setup, or to add another coding agent (including JetBrains IDEs),
run the setup wizard in the project folder:

```bash theme={null}
rasa tools init
```

It detects the Mantle project and connects the IDEs you pick to the Rasa MCP
server, so your coding agent can validate, train, and evaluate your agent. It also
downloads the documentation and offers to install the skills. To add only the
skills and the documentation, run:

```bash theme={null}
rasa tools skills install mantle
rasa tools init docs mantle
```

Install the skills without the documentation and your agent still works, but it
falls back to fetching the reference over the network — which many IDE sandboxes
block.

## 5. Build your first skill from a prompt

With the Copilot connected, describe the skill in plain language, or paste in
real transcripts of the conversations you want it to handle:

**1. Describe it or paste transcripts**

In your IDE chat, tell the Copilot what you want:

```text theme={null}
Build a skill that lets a customer check their account balance.
Ask for the account number, then look it up and report it clearly.
```

Or paste a handful of real support transcripts and ask the Copilot to
turn them into a skill.

**2. Let the Copilot scaffold the agent**

The Copilot writes the `skill.md`, any `tools/`, and wires up config. Review
the diff before accepting.

```markdown skills/check_balance/skill.md theme={null}
---
name: Check Balance
description: Look up a customer's account balance
---

Help the customer check their account balance.

Ask for their account number, then call check_balance to look it up and
report the balance clearly.
```

> [!NOTE]
>
> Run `rasa train`, `rasa run`, and `rasa inspect` from the agent project root,
> the directory that contains `agent.yml` and `integrations.yml`. See
> [Project structure](https://mantle.rasa.com/reference/project-structure.md#what-makes-it-a-mantle-project).
>
> `rasa train` is the validation gate. Before packaging, it checks the whole
> project for undeclared memory writes, unknown response names, and malformed
> conditions. Treat its errors as authoring feedback and fix them before debugging
> conversation behaviour.

## 6. Evaluate with simulations

Rather than scripting every turn, let an LLM simulate a real user and score
whether the agent met its goals.

Ask the Copilot to generate and run a scenario:

```text theme={null}
Generate and run a simulation for the check_balance skill where the user
knows their account number. Assert the balance is reported.
```

The Copilot writes a scenario, validates it, runs the simulation against your
running agent, and returns a **pass/fail summary with a link to the full
transcript**. When something fails, it reads the result and **recommends
concrete fixes**: a missing constraint, an ambiguous instruction, a tool that
should be gated.

The scenario format, the Mantle assertion checks, and how to read a result are
in [Simulate and evaluate](https://mantle.rasa.com/testing/simulating-and-evaluating.md).

## 7. Talk to your agent

Start your agent and open the Inspector in your browser:

```bash theme={null}
rasa inspect
```

You can test the same agent by typing or by speaking. Try both: the skill is
identical, and Mantle changes how it responds to suit the channel.

> [tab] Chat
>
> Type a message such as *Show me my recent transactions* and step through
> each turn in the Inspector to see which skill was active, what memory was
> set, and which tools ran. Those moments are recorded as tracker events — see
> [Tracker events](https://mantle.rasa.com/reference/execution-loop.md#tracker-events).

> [tab] Voice
>
> With `DEEPGRAM_API_KEY` set in `.env` and Deepgram Flux configured as in
> [step 3](#3-set-your-environment-variables):
>
> 1. Leave the message box empty and select **Start voice conversation** (the
>    waveform button) next to it. Allow microphone access when your browser
>    asks.
> 2. Say *Show me my recent transactions*. The scaffolded agent waits for you
>    to speak first.
> 3. Answer its question about which account, then listen to the reply.
>
> Notice what changed without touching the skill:
>
> * **It speaks, rather than formats.** No lists or markdown, one question at
>   a time, and amounts read out as words, for example "forty-two dollars and
>   eighteen cents".
> * **It fills the pause.** While `fetch_accounts` runs, the agent says a short
>   acknowledgement so the caller is not left in silence.
> * **You can interrupt it.** Start talking while it is speaking. Playback
>   stops and the interruption appears in the conversation log.
>
> The Inspector shows the transcribed turns alongside the same skill, memory,
> and tool events as chat, plus voice events such as interruptions and silence
> timeouts, and per-turn latency. Select **End conversation** to hang up.

## 8. Make it sound right on a call (optional)

Two small changes make the most difference on voice.

**Greet the caller.** In a voice conversation, the caller expects the agent to
speak first. The bundled session-start skill stays silent, so replace it with one that
greets:

```markdown skills/builtin_session_start/skill.md theme={null}
---
name: Session Start
description: Greet the user at the start of a session.
routing:
  engine_managed: true
---

:::ordered_block id=main
steps:
  - id: greet
    utter: utter_greet
:::
```

```yaml skills/builtin_session_start/responses.yml theme={null}
responses:
  utter_greet:
    - text: "Hi, thanks for calling. How can I help you today?"
```

**Pick a voice.** The voice is the `model` under `language_map` on the TTS
model group you named from the `inspector` channel in step 3. Swap
`flux-alexis-en` for any other Deepgram Flux voice, or adjust the pace with
`speed` (0.5 to 1.5):

```yaml integrations.yml theme={null}
model_groups:
  - id: inspector_tts
    models:
      - provider: deepgram_flux
        api_key: ${DEEPGRAM_API_KEY}
        language_map:
          en:
            model: flux-alexis-en
        speed: 1.05
```

To use a voice from another provider, set `provider` to `azure`, `cartesia`, or
`rime` and add that provider's API key to `.env`. See
[Speech providers](https://mantle.rasa.com/reference/speech-providers.md).

Run `rasa train` after the skill change, restart `rasa inspect`, and start a new
voice conversation. For more on writing skills that work well out loud, see
[Designing for voice](https://mantle.rasa.com/voice/designing-for-voice.md).

## 9. Loop

Feed what you learn back into the prompt: tighten the instructions, add a
[tool constraint](https://mantle.rasa.com/build-guide/tool-constraints.md), or add
[scoped instructions](https://mantle.rasa.com/build-guide/scoped-instructions.md). Re-run the simulations,
inspect again over chat and voice, and repeat until the agent behaves the way you
need.

## 10. Take it to the phone

When the agent sounds right in the Inspector, connect it to a phone number
through your telephony provider. The skills stay the same; you add a voice
channel to `integrations.yml`. See [Connect a phone line](https://mantle.rasa.com/voice/telephony.md).

## What's next

> [card] [Skills](https://mantle.rasa.com/skills.md)
>
> Understand the building block you just created.

> [card] [Instructions](https://mantle.rasa.com/concepts/instructions.md)
>
> Write the prose that drives your skill.

> [card] [Tools](https://mantle.rasa.com/concepts/tools.md)
>
> Give your skill actions it can take.

> [card] [Progressive Control](https://mantle.rasa.com/build-guide/tool-constraints.md)
>
> Add guarantees where mistakes are expensive.

> [card] [Voice agents](https://mantle.rasa.com/voice/overview.md)
>
> What Mantle does for you on a call, and what you control.

> [card] [Build a voice agent](https://mantle.rasa.com/voice/tutorial.md)
>
> Take a card replacement skill from chat to a voice conversation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.