Modelos: salvar, aplicar, duplicar, exportar e importar a configuração de um Robô

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.

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.

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
• Onde cada Robô é usado
• Base de conhecimento e ontologia
• DeepSeek como provedor de modelo do Robô
• Ferramentas do Maestro por módulo