mantle-new-project
Scaffold a complete, working Rasa Mantle project from scratch. Use when the user wants a new Mantle/Rasa agent, a new bot project, or asks to "set up Rasa". Produces every file with the catalog-pinned configuration shapes so the first validate passes.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 44
- Forks
- 19
01 前言 Front Matter
- name
- mantle-new-project
- description
- Scaffold a complete, working Rasa Mantle project from scratch. Use when the user wants a new Mantle/Rasa agent, a new bot project, or asks to "set up Rasa". Produces every file with the catalog-pinned configuration shapes so the first validate passes.
03 SKILL.md 正文
Scaffold a new Rasa Mantle project
Ask for (or infer): the agent's domain, a short persona name, and which channels it needs (text-only vs voice). Then create every file below — do not skip any; each absence is a lint finding or a runtime surprise.
1. pyproject.toml — the version facts are non-negotiable
[project]
name = "<project-slug>"
version = "0.1.0"
description = "<one line>"
readme = "README.md"
requires-python = ">=3.11,<3.13"
dependencies = [
"rasa-pro==3.21.0.dev5",
"python-dotenv>=1.0.0",
]
[tool.uv]
prerelease = "allow"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["lib"]
WHY, so you can defend it: the Mantle engine ships only on the
3.20.0.dev pre-release line — the newest stable rasa-pro contains no
engine package at all, so "latest stable" produces a project whose imports
fail. prerelease = "allow" is what lets uv resolve a dev pin. The
>=3.11 floor is required by 3.20; a lower floor fails uv lock with an
error about "versions not supported by your dependencies" that never
mentions Python.
If the project needs credentials beyond RASA_LICENSE and OPENAI_API_KEY
(e.g. GEMINI_API_KEY), also declare them:
[tool.rasa-catalog]
required-secrets = ["GEMINI_API_KEY"]
2. lib/engine.py — the only file that imports the engine directly
"""Engine imports, resolved in one place.
Rasa renamed the engine package to rasa.mantle in 3.20.0.dev1, with no alias
for the old name. Every tool imports from here, never from rasa.* directly,
so the next rename is a one-file change.
"""
from __future__ import annotations
from rasa.mantle.tools.decorator import ToolContext, tool
from rasa.mantle.tools.result import ToolResult
ENGINE_PACKAGE = "rasa.mantle"
__all__ = ["ENGINE_PACKAGE", "ToolContext", "ToolResult", "tool"]
Also create empty lib/__init__.py and tools/__init__.py.
3. agent.yml — prompt-tuning keys are TOP-LEVEL
agent:
id: <project-slug>
language: en
persona: |
You are <Name>, a concise assistant for <domain>.
Ask one question at a time and keep answers short.
Never invent facts — always use tools for data.
# TOP-LEVEL keys, siblings of `agent:`. Nested inside they parse without
# error and are silently discarded — the engine reads them only from the top
# level of this file.
name: <Name>
description: <one line, shown to the model>
rules:
- "Be polite, clear, and brief."
- "Never state data that did not come from a tool."
- "Activate a skill only when the request clearly matches it."
For a voice agent, set the engines on the channel in integrations.yml
(section 4), not in agent.yml. A nested agent.voice block is ignored by Rasa
Pro 3.21 and rejected by 3.22.
4. integrations.yml — llm is a model-group reference
# The orchestrator LLM is a model-group reference. Provider, model and
# credentials live on the named group, never inline under `llm:` — the
# inline form was removed in 3.20.0.dev6.
llm:
model_group: orchestrator
model_groups:
- id: orchestrator
models:
- provider: openai
model: gpt-4.1-mini
api_key: ${OPENAI_API_KEY}
temperature: 0.0
channels:
rest:
enabled: true
inspector:
enabled: true
# Voice agents only: the engines for this channel.
asr:
name: deepgram # or a dotted path to a custom engine class
tts:
name: deepgram
5. memory.yml — project memory is tool-written
# Project memory — facts that outlive a single skill. Readable and writable
# by EVERY skill. Keep it to facts about the end user and the session.
# NEVER put `llm_settable: true` here — the engine rejects it at the project
# level. LLM-settable fields belong in skills/<id>/memory.yml.
authenticated:
type: bool
# Whether the caller has proven their identity this session.
initial_value: false
Document a project field with a YAML comment, not description:. The model
cannot set project fields, so it never sees their description, and Rasa Pro
3.22 rejects one (mantle.validation.memory.description_not_exposed).
Skill-scoped llm_settable fields keep description:, because the model
reads it.
6. Skills — at least one real skill plus a greeting
Create skills/<skill_id>/skill.md using the mantle-skill-authoring
skill's grammar (frontmatter → prose → top-level if: branches). Put tools
only that skill uses in skills/<skill_id>/tools.py; shared tools in
tools/ and reference them with import_tools: in the frontmatter.
7. Credentials and hygiene
-
.env.example(committed): every key the project reads, values empty, one comment per key saying where to get it. Start with:# Rasa Pro licence (free Developer Edition, a long JWT, one line) RASA_LICENSE= # LLM for routing and conversation OPENAI_API_KEY= -
.gitignoremust contain:.env,.venv/,models/,__pycache__/,.rasa/.
8. Makefile — the beginner's interface
.DEFAULT_GOAL := help
.PHONY: help env install validate train chat lint clean
help: ## Show targets
@grep -E '^[a-z-]+:.*##' $(MAKEFILE_LIST) | awk -F':.*## ' '{printf " make %-10s %s\n", $$1, $$2}'
env: ## Create .env from .env.example
@test -f .env || cp .env.example .env
install: ## Install dependencies
uv sync --prerelease=allow
lint: ## Offline consistency checks
python3 scripts/lint_mantle.py
validate: lint ## Validate the project without training
uv run rasa validate
train: ## Validate and train
uv run rasa train
chat: ## Talk to the agent in the Inspector
uv run rasa inspect
clean: ## Remove models and caches
rm -rf models .rasa
9. Finish
- Copy
scripts/lint_mantle.pyandhooks/from the starter pack if not present; run./hooks/install-hooks.sh. - Run
python3 scripts/lint_mantle.py— must be clean before the first commit. - Tell the user exactly which of the two gates you ran: the offline lint
(consistency) vs
make validate/train(actually exercises the engine — needsuv syncand aRASA_LICENSE). A green lint alone is not "it works".
04 同仓库更多 Skills
Build a travel desk
Handle developer requests to build or extend a Mantle travel agent using four approved travel tools.
Travel briefing
Answer questions about flight status, tonight’s departures, airport weather and currency conversion.
Review Dispute
Ask the outside reviewer about a card dispute, then block the card if the caller confirms. Activate when the caller reports a card transaction they did not make.
Block Card
Block a customer's lost or stolen card. Activate when the caller wants a card blocked.
Block Card
Block a customer's lost or stolen card. Activate when the caller wants a card blocked.
Block Card
Block a customer's lost or stolen card. Activate when the caller wants a card blocked.