## Overview

A **Modelo** — the name the screen uses for a saved bot configuration — is a bot's setup stored for
reuse: persona, instructions, language model, enabled tools, guardrails, handoff policy, service
sequence and everything else you tuned.

The library lives in **Settings → Bots**, just below the bot list — and it shows up even when the
account has no bot yet, because importing a Modelo is one of the ways to get your first one.

| Action | Where it is | What it does |
|---|---|---|
| **Save as Modelo** | in the bot's form | Stores the configuration in this account's library. |
| Apply a Modelo | in the bot's form, under **Quick-start templates** | Brings the stored configuration into the form; you review it and save the bot. |
| **Duplicate** | in the Modelos list | Creates a **copy of the Modelo** in this account, editable. |
| **Edit** | in the Modelos list | Changes name, vertical and description. It does **not** touch the stored configuration. |
| **Delete** | in the Modelos list | Removes the Modelo. Bots already created from it keep working. |
| **Export** / **Import** | in the Modelos list | Produces and reads a `.maestro-template.json` file another installation can open. |

> **Read this before migrating:** a Modelo is **not** a complete copy of the bot. Two classes of
> thing are left behind by design — **secrets** and **local references**. Whenever something is
> saved, exported or imported, the **What did not travel** panel states exactly what was removed or
> cleared. Never assume "100% imported".

## Prerequisites

- **Maestro enabled** and at least one configured bot (or a Modelo file to import).
- **Administrator** permission to save, duplicate, edit, delete, export and import.
- To import on another installation: administrator access **there too**.

## Step by step

### Save a bot as a Modelo

1. Go to **Settings → Bots** and open the bot that is already the way you want it.
2. Under **Quick-start templates**, use **Save as Modelo**.
3. Fill in **Name**, and optionally **Vertical (optional)** and **What is this Modelo for?
   (optional)**. Name it after the use case, not the client.
4. Confirm with **Save Modelo**. It appears at the top of the Modelos list.

**Careful — there are two behaviours, and the dialog tells you which one applies:**

- **The bot is already saved:** it stores the configuration the bot is **currently running**, not
  unsaved edits on the form. If you just changed something, **save the bot first**.
- **The bot does not exist yet:** since there is no bot, the configuration **on screen** is stored
  as it is.

### Apply a Modelo to a bot

This is the path from Modelo to bot — duplicating creates no bot at all.

1. Open an existing bot, or start creating a new one.
2. Under **Quick-start templates**, open the **Vertical agent** picker. Your account's Modelos (and
   the installation library's) appear **in front of** the product's ready-made presets.
3. Pick the Modelo and use **Apply**. The notice tells you how many settings it brought in: applying
   merges **only the fields the Modelo carries** — the rest of the form stays as it was.
4. Review the configuration, **save the bot**, and attach it to the inboxes where it should work.

### Find, duplicate, edit and delete

1. Use the **Search Modelos** field to filter by name, description or vertical. **Clear search**
   brings the full list back.
2. **Duplicate** creates a **copy of the Modelo** in this account, already editable (the notice
   confirms: "Duplicated as …"). That is how you customise a **Shared** Modelo, which is read-only.
3. **Edit** changes **Name**, **Vertical** and **Description** — the stored configuration is not
   touched. To change the configuration itself, apply the Modelo to a bot, tweak it, and use
   **Save as Modelo** again.
4. **Delete** removes the Modelo from the library. Bots created from it keep working: a Modelo is a
   starting point, not a link.

### Export and import between installations

1. On the Modelo, choose **Export**. The browser downloads a `.maestro-template.json` file.
2. On the target installation, use **Import** and pick the file.
3. **Read the "What did not travel" panel** — it lists, item by item, what was removed or cleared.
4. Reconfigure whatever the panel flagged (keys, teams, knowledge base, media).
5. Apply the Modelo to a bot, review it and **save**.

## Settings & options

### Two scopes: account Modelos and the installation library

The list shows both together, and they behave differently on purpose:

- **Account Modelos** — the ones you saved, duplicated or imported. They are **editable** and can be
  **deleted**.
- **Installation library** — they carry the **Shared** badge and are **read-only**: they offer no
  **Edit** and no **Delete**. To customise one, use **Duplicate**: the copy lands in this account,
  editable, leaving the original untouched.

Publishing a Modelo to the **whole installation** is a **platform operator** action and has no path
in the account panel: the effect crosses every account on the box, and restricting is reversible
while unpublishing from the world is not.

### The "What did not travel" panel

It appears after you save, edit, export or import a Modelo, and lists **only** what could not be
carried — references re-matched by name are left out, so the panel stays worth reading. **Dismiss**
closes it.

### What NEVER travels: secrets

Neither the **values** nor the **names**. A secret's name is already a map of where the credentials
live.

These are removed when saving to the library **and** on export:

- The bot's **provider keys** and the mirror of the account's native keys.
- Registered **secrets** and the **list of their names**.
- Credentials typed **literally** inside HTTP tools and MCP servers — headers such as
  `Authorization`, `Cookie`, and any field whose name looks like `api_key`, `token`, `password`,
  `secret`.
- A credential embedded in the **URL** (`https://user:password@host/...`). Only the `user:password`
  is removed; host, path and query stay so the tool remains reconfigurable.

The policy is a **denylist**: everything travels **except** what is named as a secret or a local
reference. A new field whose **name** looks like a credential is stripped automatically. That way the
possible mistake is "too little travelled", never "a secret travelled".

**One important and useful exception:** a reference in the form `{{secret.NAME}}` **survives** — it
points at a secret, it is not one. On the other side you just register a secret with that name and
the tool works again without rewriting anything. **Always use that form** in HTTP tools.

### What does NOT travel: local references

`team 7` on the target installation points at a team that does not exist — or, worse, at a
**different** team. So every reference is exported as the **name** it had, **re-matched by name** on
import, and **cleared** when nothing matches. Nothing is invented: a bot pointing at team 1 just
because 1 exists is worse than a bot with no team.

| Item | On import |
|---|---|
| **Handoff team** | Remapped by name; **cleared** if no team has that name. |
| **Sub-agents (delegation)** | Remapped by name. |
| **Knowledge base** | Arrives **switched off** — the ingested content does not travel. Re-ingest, then re-enable. |
| **Media library assets** | **Dropped** — the URLs point at the source installation's storage. Re-upload on the target. |
| **Database / cloned voice** | The resource does not travel; the capability arrives **off** and named in the panel. |
| **Contact attributes** | Checked against the ones the target account actually defines. |

A capability whose backing resource could not travel arrives **disabled** on purpose: leaving it on
would ship a bot that answers "I checked our knowledge base" against an empty one.

### The file

- Extension `.maestro-template.json`, carrying a format marker and a version.
- A file **without** the marker is not treated as a Modelo: it is **refused**, not guessed at.
- A version this installation does not know is refused too — **never** half-read. A half-read Modelo
  is a bot that looks configured and is not.

## Use cases

- **Standardise service** — one "Tier 1 support" Modelo applied to several bots.
- **Try a variant** — duplicate the Modelo, apply the copy to a test bot and compare.
- **Staging → production** — configure calmly on staging, export and import.
- **Agency / multi-client** — one Modelo per vertical, exported and imported into each account.
- **Configuration backup** — export before a large change.
- **Installation migration** — carry your bots over without reconfiguring everything by hand.

## Tips, limits & best practices

- **Always read the "What did not travel" panel.** It is your to-do list on the other side.
- After importing, run a **real test** conversation before putting the bot on live traffic.
- Prefer `{{secret.NAME}}` over pasting the credential: it is the only form that survives the trip.
- Name Modelos by **use case** ("Clinic — booking"), not by client.
- **Edit does not change behaviour**: it only touches the label (name, vertical, description).
- **Duplicate before experimenting** — that way the Modelo that already works stays intact.
- A Modelo is a **snapshot**: changing the bot afterwards does **not** update the Modelo, and vice
  versa.

## Troubleshooting

- **"I duplicated it and no bot appeared"** — duplicating copies the **Modelo**, it does not create
  a bot. To get a bot, open the bot's form, apply the Modelo under **Vertical agent**, save, and
  attach it to the inboxes.
- **"This Modelo has no Edit and no Delete"** — it comes from the installation (**Shared** badge)
  and is read-only. Use **Duplicate** to get an editable copy in this account.
- **"A Modelo with this key already exists"** — you are importing a file that is already in the
  library. Duplicate the existing one instead, or rename it before importing again.
- **"The file was refused on import"** — it is not a valid `.maestro-template.json`, or it was
  produced by a version this installation cannot read.
- **"The bot hands off to the wrong team"** — no team existed under the same name; the panel marked
  it cleared. Create the team and select it.
- **"It says it checked the knowledge base and found nothing"** — the base arrives off and **empty**.
  Re-ingest the content and enable it.
- **"The HTTP tools return authentication errors"** — credentials do not travel. Register the secrets
  on the target.
- **"The media is missing"** — the files do not travel; re-upload them in the target's media library.
- **"I applied the Modelo and not everything changed"** — applying merges only the fields the Modelo
  carries, and the notice shows how many settings came in. The rest stays as the form already had it.

## See also

- [What Maestro AI and the Account Brain are](/hc/ajuda/articles/maestro-brain-overview-en)
- [Where each bot is used](/hc/ajuda/articles/maestro-brain-onde-cada-robo-e-usado-en)
- [Knowledge base and ontology](/hc/ajuda/articles/maestro-brain-base-de-conhecimento-e-ontologia-en)
- [DeepSeek as a model provider for your bot](/hc/ajuda/articles/maestro-brain-provedor-deepseek-en)
- [Maestro tools by module](/hc/ajuda/articles/maestro-brain-ferramentas-maestro-por-modulo-en)