## Visão geral

Um **Modelo** é a configuração de um Robô guardada para ser reaproveitada: persona, instruções,
modelo de linguagem, ferramentas habilitadas, guardrails, política de transferência, sequência de
atendimento e tudo o mais que você ajustou.

A biblioteca fica em **Configurações → Robôs**, logo abaixo da lista de Robôs — e aparece mesmo
quando a conta ainda não tem nenhum Robô, porque importar um Modelo é uma das formas de criar o
primeiro.

| Ação | Onde fica | O que faz |
|---|---|---|
| **Salvar como Modelo** | no formulário do Robô | Guarda a configuração na biblioteca desta conta. |
| Aplicar um Modelo | no formulário do Robô, em **Modelos prontos** | Traz a configuração guardada para o formulário; você revisa e salva o Robô. |
| **Duplicar** | na lista de Modelos | Cria uma **cópia do Modelo** nesta conta, editável. |
| **Editar** | na lista de Modelos | Altera nome, segmento e descrição. **Não** toca na configuração guardada. |
| **Excluir** | na lista de Modelos | Remove o Modelo. Os Robôs já criados a partir dele continuam funcionando. |
| **Exportar** / **Importar** | na lista de Modelos | Gera e lê um arquivo `.maestro-template.json`, que outra instalação consegue abrir. |

> **Leia isto antes de migrar:** um Modelo **não** é uma cópia integral do Robô. Duas classes de
> coisa ficam para trás por decisão de projeto — **segredos** e **referências locais**. Sempre que
> algo é salvo, exportado ou importado, o painel **O que não viajou** diz exatamente o que foi
> removido ou limpo. Nunca assuma "importou 100%".

## Pré-requisitos

- **Maestro habilitado** e pelo menos um Robô configurado (ou um arquivo de Modelo para importar).
- Permissão de **administrador** para salvar, duplicar, editar, excluir, exportar e importar.
- Para importar em outra instalação: acesso de administrador **lá também**.

## Passo a passo

### Salvar um Robô como Modelo

1. Vá em **Configurações → Robôs** e abra o Robô que já está do jeito que você quer.
2. No bloco **Modelos prontos**, use **Salvar como Modelo**.
3. Preencha **Nome**, e opcionalmente **Segmento (opcional)** e **Para que serve este Modelo?
   (opcional)**. Dê um nome que descreva o uso, não o cliente.
4. Confirme em **Salvar Modelo**. Ele aparece no topo da lista de Modelos.

**Atenção — são dois comportamentos, e o diálogo diz qual se aplica:**

- **Robô já salvo:** guarda a configuração que ele está **rodando agora**, e não as edições ainda
  não salvas neste formulário. Se você acabou de mudar algo, **salve o Robô antes**.
- **Robô ainda não criado:** como não existe Robô, a configuração **que está na tela** é guardada
  como está.

### Aplicar um Modelo num Robô

Este é o caminho de Modelo para Robô — duplicar não cria Robô nenhum.

1. Abra um Robô existente ou comece a criar um novo.
2. No bloco **Modelos prontos**, abra o seletor **Agente por vertical**. Os Modelos da sua conta (e
   os da biblioteca da instalação) aparecem **na frente** dos presets prontos do produto.
3. Escolha o Modelo e use **Aplicar**. O aviso informa quantos ajustes ele trouxe: aplicar mescla
   **apenas os campos que o Modelo carrega** — o resto do formulário continua como estava.
4. Revise a configuração, **salve o Robô** e vincule-o às caixas de entrada onde ele deve atender.

### Encontrar, duplicar, editar e excluir

1. Use o campo **Buscar Modelos** para filtrar por nome, descrição ou segmento. **Limpar busca**
   volta à lista completa.
2. **Duplicar** cria uma **cópia do Modelo** nesta conta, já editável (o aviso confirma:
   "Duplicado como …"). É assim que se personaliza um Modelo **Compartilhado**, que é só leitura.
3. **Editar** muda **Nome**, **Segmento** e **Descrição** — a configuração guardada não é tocada.
   Para mudar a configuração em si, aplique o Modelo num Robô, ajuste e use **Salvar como Modelo**
   de novo.
4. **Excluir** remove o Modelo da biblioteca. Os Robôs criados a partir dele continuam funcionando:
   um Modelo é ponto de partida, não vínculo.

### Exportar e importar entre instalações

1. No Modelo, escolha **Exportar**. O navegador baixa um arquivo `.maestro-template.json`.
2. Na instalação de destino, use **Importar** e escolha o arquivo.
3. **Leia o painel "O que não viajou"** — ele lista item por item o que foi removido ou limpo.
4. Reconfigure o que o painel apontou (chaves, times, base de conhecimento, mídias).
5. Aplique o Modelo num Robô, revise e **salve**.

## Configurações & opções

### Dois escopos: Modelos da conta e biblioteca da instalação

A lista mostra os dois juntos, e eles se comportam de maneira diferente de propósito:

- **Modelos da conta** — os que você salvou, duplicou ou importou. São **editáveis** e podem ser
  **excluídos**.
- **Biblioteca da instalação** — vêm marcados com o selo **Compartilhado** e são **só leitura**:
  não oferecem **Editar** nem **Excluir**. Para personalizar um deles, use **Duplicar**: a cópia
  nasce nesta conta, editável, sem alterar o original.

Publicar um Modelo para a **instalação inteira** é ação do **operador da plataforma** e não tem
caminho no painel da conta: o efeito atravessa todas as contas da caixa, e restringir é reversível
enquanto despublicar do mundo não é.

### O painel "O que não viajou"

Aparece depois de salvar, editar, exportar ou importar um Modelo, e lista **somente** o que não
pôde ser levado — referências reencontradas pelo nome não entram na lista, para o painel continuar
sendo lido. **Dispensar** fecha o aviso.

### O que NUNCA viaja: segredos

Nem os **valores**, nem os **nomes**. Um nome de segredo já é um mapa de onde estão as credenciais.

São removidos ao salvar na biblioteca **e** ao exportar:

- **Chaves de provedor** do Robô e o espelho das chaves nativas da conta.
- **Segredos** cadastrados e a **lista de nomes** deles.
- Credenciais digitadas **literalmente** dentro de ferramentas HTTP e servidores MCP — cabeçalhos
  como `Authorization`, `Cookie`, e qualquer campo cujo nome pareça `api_key`, `token`, `password`,
  `secret`.
- Credencial embutida na **URL** (`https://usuario:senha@host/...`). Só o `usuario:senha` sai; host,
  caminho e query continuam, para a ferramenta seguir reconfigurável.

A política é uma **lista de negação**: tudo viaja, **exceto** o que for nomeado como segredo ou
referência local. Um campo novo cujo **nome** pareça credencial é removido automaticamente. Assim, o
erro possível é "viajou de menos", nunca "vazou um segredo".

**Uma exceção importante e útil:** uma referência no formato `{{secret.NOME}}` **sobrevive** — ela
aponta para um segredo, não é um segredo. Do outro lado, basta cadastrar um segredo com aquele nome
e a ferramenta volta a funcionar sem você reescrever nada. **Use sempre essa forma** nas ferramentas
HTTP.

### O que NÃO viaja: referências locais

Um `time 7` na instalação de destino aponta para um time que não existe — ou, pior, para um time
**diferente**. Por isso cada referência é exportada pelo **nome** que tinha, **reencontrada pelo
nome** na importação, e **limpa** quando nada casa. Nada é inventado: um Robô apontando para o time 1
só porque o 1 existe é pior do que um Robô sem time.

| Item | Na importação |
|---|---|
| **Time de transferência** | Remapeado pelo nome; **limpo** se não existir time com aquele nome. |
| **Subagentes (delegação)** | Remapeados pelo nome. |
| **Base de conhecimento** | Chega **desligada** — o conteúdo já ingerido não viaja. Reingira e ligue de novo. |
| **Mídias da biblioteca** | **Descartadas** — as URLs apontam para o armazenamento da origem. Reenvie no destino. |
| **Banco de dados / voz clonada** | O recurso não viaja; a capacidade chega **desligada** e nomeada no painel. |
| **Atributos de contato** | Conferidos contra os que a conta de destino realmente define. |

Uma capacidade cujo recurso não pôde viajar chega **desligada** de propósito: deixá-la ligada
entregaria um Robô que responde "consultei nossa base de conhecimento" contra uma base vazia.

### O arquivo

- Extensão `.maestro-template.json`, com um marcador de formato e uma versão.
- Um arquivo **sem** o marcador não é tratado como Modelo: é **recusado**, não adivinhado.
- Uma versão que esta instalação não conhece também é recusada — **nunca** lida pela metade. Um
  Modelo meio lido é um Robô que parece configurado e não está.

## Casos de uso

- **Padronizar o atendimento** — um Modelo "Suporte nível 1" aplicado a vários Robôs.
- **Testar uma variante** — duplique o Modelo, aplique a cópia num Robô de teste e compare.
- **Ambiente de testes → produção** — configure com calma no ambiente de teste, exporte e importe.
- **Agência / multi-cliente** — um Modelo por vertical, exportado e importado em cada conta.
- **Backup de configuração** — exporte antes de uma mudança grande.
- **Migração de instalação** — leve os Robôs sem reconfigurar tudo na mão.

## Dicas, limites e boas práticas

- **Sempre leia o painel "O que não viajou".** Ele é a lista de tarefas do outro lado.
- Depois de importar, faça um **teste real** numa conversa antes de ligar o Robô no atendimento.
- Prefira `{{secret.NOME}}` a colar a credencial: é a única forma que sobrevive à viagem.
- Nomeie Modelos pelo **uso** ("Clínica — agendamento"), não pelo cliente.
- **Editar não muda comportamento**: mexe só no rótulo (nome, segmento, descrição).
- **Duplique antes de experimentar** — assim o Modelo que já funciona continua intacto.
- O Modelo é uma **fotografia**: mudar o Robô depois **não** atualiza o Modelo, e vice-versa.

## Solução de problemas

- **"Dupliquei e não apareceu Robô nenhum"** — duplicar copia o **Modelo**, não cria Robô. Para
  virar Robô, abra o formulário do Robô, aplique o Modelo em **Agente por vertical**, salve e
  vincule-o às caixas de entrada.
- **"Este Modelo não tem Editar nem Excluir"** — ele veio da instalação (selo **Compartilhado**) e é
  só leitura. Use **Duplicar** para ter uma cópia editável nesta conta.
- **"Já existe um Modelo com esta chave"** — você está importando um arquivo que já está na
  biblioteca. Duplique o que você já tem, ou renomeie antes de importar de novo.
- **"O arquivo foi recusado na importação"** — não é um `.maestro-template.json` válido, ou foi
  gerado por uma versão que esta instalação não lê.
- **"O Robô não transfere para o time certo"** — o time não existia pelo mesmo nome; o painel marcou
  como limpo. Crie o time e selecione-o.
- **"Ele diz que consultou a base e não achou nada"** — a base chega desligada e **vazia**. Reingira
  o conteúdo e ligue a base.
- **"As ferramentas HTTP dão erro de autenticação"** — as credenciais não viajam. Cadastre os
  segredos no destino.
- **"Faltam as mídias"** — os arquivos não viajam; reenvie na biblioteca de mídia do destino.
- **"Apliquei o Modelo e nem tudo mudou"** — aplicar mescla só os campos que o Modelo carrega; o
  aviso mostra quantos ajustes foram trazidos. O resto continua como o formulário já estava.

## Veja também

- [O que é o Maestro IA e o Cérebro da Conta](/hc/ajuda/articles/maestro-brain-overview-pt-br)
- [Onde cada Robô é usado](/hc/ajuda/articles/maestro-brain-onde-cada-robo-e-usado-pt-br)
- [Base de conhecimento e ontologia](/hc/ajuda/articles/maestro-brain-base-de-conhecimento-e-ontologia-pt-br)
- [DeepSeek como provedor de modelo do Robô](/hc/ajuda/articles/maestro-brain-provedor-deepseek-pt-br)
- [Ferramentas do Maestro por módulo](/hc/ajuda/articles/maestro-brain-ferramentas-maestro-por-modulo-pt-br)