> ## Documentation Index
> Fetch the complete documentation index at: https://maestro.rasa.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting Started
> Install Maestro and build your first agent with the Rasa Copilot.
This guide takes you from an empty folder to a working, tested agent. You'll
install Maestro, 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 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 talk to the agent in the Inspector and step through what happened turn by turn. |
## 1. Install Maestro
Maestro 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.19.0.dev5
```
Check it worked:
```bash theme={null}
rasa --version
```
Maestro 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.
## 2. Create a project
Run `rasa init` to start the setup wizard:
```bash theme={null}
rasa init --engine maestro
```
The wizard walks you through the full setup:
1. Asks where to create your project
2. Collects your keys and writes them to a `.env`
3. Installs Cursor and Claude Code compatible skills
4. Validates and trains your agent
5. Opens the Inspector so you can chat with it immediately
Once it completes, your project looks like this:
```bash theme={null}
my-agent/
├── agent.yml # identity, persona, global rules
├── integrations.yml # LLM provider, input channels, optional Langfuse tracing
├── 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](/docs/maestro/reference/project-structure) 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=""
```
To use a different LLM provider, edit the `llm:` block in
[`integrations.yml`](/docs/maestro/reference/integrations-yml).
## 4. Connect your coding agent
If you created your project with `rasa init`, Claude Code and Cursor compatible
skills are already installed. Open the project in either tool and your coding
agent has the context it needs to build and iterate on Maestro skills.
For an existing project that wasn't created with `rasa init`, install them
manually:
```bash theme={null}
rasa tools skills install maestro
```
## 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:
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.
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.
```
`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.
## 7. Test and inspect
Start your agent and open a browser window where you can talk to it directly:
```bash theme={null}
rasa inspect
```
Try the conversation yourself and step through each turn in the Inspector to see
which skill was active, what memory was set, and which tools ran.
## 8. Loop
Feed what you learn back into the prompt: tighten the instructions, add a
[tool constraint](/docs/maestro/build-guide/tool-constraints), or add
[scoped instructions](/docs/maestro/build-guide/scoped-instructions). Re-run the simulations,
inspect again, and repeat until the agent behaves the way you need.
## What's next
Understand the building block you just created.
Write the prose that drives your skill.
Give your skill actions it can take.
Add guarantees where mistakes are expensive.