--- title: Exportar e importar fluxos (.adflow) description: Como levar um fluxo completo — com agents, skills, conhecimento e credenciais — de um workspace para outro usando um pacote .adflow totalmente criptografado, protegido por senha. --- # Exportar e importar fluxos (.adflow) Às vezes você monta um fluxo inteiro — com seus agents, ferramentas MCP, artigos de conhecimento e credenciais — e precisa levá-lo para outro workspace: um cliente novo, um ambiente de testes, ou simplesmente um backup fora da plataforma. É para isso que existe o **pacote `.adflow`**: um arquivo único, **totalmente criptografado** (protegido por um código secreto matemático, do mesmo jeito que um cofre digital), que empacota o fluxo e tudo que ele usa, protegido por uma senha que você escolhe. --- ## O que é um pacote `.adflow` Um pacote `.adflow` é um arquivo opaco — não dá para abrir e ler o conteúdo num editor de texto comum, como se faz com uma planilha ou um documento. Ele carrega, de forma cifrada, junto com o fluxo: - Os **agents** vinculados ao fluxo (inclusive sub-agents, recursivamente, se um agent chamar outro). - As **skills** de cada agent (o conteúdo em texto, recursos e metadados). - Os **servidores MCP** usados pelos agents — tanto os do catálogo público da plataforma quanto os configurados por você. - As **ferramentas de função** (conexões com sistemas externos via HTTP). - Os **artigos da Base de Conhecimento** ligados aos agents. - As **credenciais** referenciadas (opcionalmente, com o valor secreto incluído). Tudo isso viaja em um único arquivo, sem depender de identificadores internos do workspace de origem — por isso o mesmo pacote pode ser importado em qualquer workspace ao qual você tenha acesso, inclusive um diferente do de origem. Pense no `.adflow` como um "cofre" do seu fluxo: ele carrega a receita completa (fluxo + agents + ferramentas + conhecimento) trancada por senha — abrir o arquivo num editor de texto sem a senha não revela nada além de alguns detalhes técnicos de como ele foi cifrado. Nome do fluxo, prompts dos agents, estrutura do canvas e segredos ficam todos ilegíveis. --- ## A senha do pacote Todo pacote `.adflow` é protegido por uma **senha** que você define no momento da exportação. Essa senha: - É **obrigatória** — tanto para exportar quanto para importar, mesmo que você opte por não incluir credenciais no pacote. - Precisa ter **no mínimo 8 caracteres**. - É usada para cifrar **o pacote inteiro**. Sem ela, ninguém consegue ler absolutamente nada do conteúdo do arquivo — nem a estrutura do fluxo, nem os agents, nem os segredos das credenciais. Guarde essa senha em um lugar seguro e combine com quem for importar o pacote. A plataforma não guarda a senha em nenhum lugar — se você perder, o arquivo `.adflow` fica inutilizável. Não há como "recuperar" a senha depois. --- ## Exportando um fluxo Passo a passo Abra o fluxo no editor e, no canto superior direito do canvas, clique em **Recursos → Exportar (.adflow)**. Escolha a versão a exportar: a **versão publicada** (a que está em produção) ou a **versão em rascunho** (o que está salvo no editor, ainda não publicado). Decida se quer **incluir as credenciais** (senhas, tokens e chaves de acesso usadas pelos servidores MCP e ferramentas). Se desmarcar, o pacote leva só a referência de quais credenciais existem, sem o valor secreto. Defina a **senha do pacote** (mínimo 8 caracteres). Confirme. O download do arquivo `{nome-do-fluxo}.adflow` começa automaticamente. Se você só quer mover a estrutura do fluxo entre ambientes (sem levar senhas de produção), deixe **"incluir credenciais"** desmarcado e recadastre as credenciais manualmente no destino. É a opção mais segura para levar um fluxo para um ambiente de testes, por exemplo. --- ## Importando um fluxo Passo a passo Abra qualquer fluxo no editor (dentro do workspace de destino) e, no menu **Recursos**, escolha **Importar (.adflow)**. Selecione o arquivo `.adflow` que você exportou anteriormente. Informe a **senha** usada na exportação. Confirme. A plataforma recria o fluxo, os agents, as skills, os servidores MCP e os artigos de conhecimento no workspace atual — o fluxo importado é um fluxo **novo e independente**, não sobrescreve o fluxo que você tinha aberto. Use o botão **Abrir fluxo importado** no resumo da importação para ir direto ao novo fluxo (criado como rascunho). ### O que acontece ao importar - Tudo é **recriado do zero** no workspace de destino — o import nunca sobrescreve nada que já existe lá, mesmo que você reimporte o mesmo arquivo várias vezes. - O **fluxo importado sempre entra como rascunho** (não publicado, inativo). Ele não passa a atender clientes automaticamente — você precisa revisá-lo e publicar manualmente quando estiver pronto (veja [Testar e Publicar](/guia/flow-builder/testar-e-publicar)). - Servidores **MCP do catálogo público** (os oferecidos pela própria plataforma) são **reaproveitados por nome** — se o destino já tem aquele mesmo MCP cadastrado no catálogo, o fluxo importado é conectado a ele em vez de duplicar. - Servidores MCP **customizados** (cadastrados por você) são **sempre recriados** como um novo registro no workspace de destino, mesmo que já exista um parecido. - **Skills Globais** (veja [Skills Globais](/guia/agents/ferramentas#skills-globais)) seguem a mesma lógica de reaproveitamento por nome: se um Agent do fluxo usa uma Skill Global, o pacote `.adflow` guarda apenas a **referência** a ela (o nome), não uma cópia do conteúdo. Na importação, o Agent é **religado** à Skill Global já existente no workspace de destino — nada é duplicado. Já as Skills **próprias do workspace de origem** continuam sendo recriadas normalmente, como qualquer outro recurso do fluxo. - As **Skills usadas por sub-agents inline** (aqueles configurados diretamente dentro do Agent orquestrador, sem virar um Agent separado) também são **reconectadas na importação**: a Skill local é religada à cópia recriada no destino, e a Skill Global à homônima já existente no workspace de destino. Se alguma Skill referenciada não existir no destino (por exemplo, uma Skill Global que não foi provisionada lá, ou um pacote `.adflow` antigo que ainda carrega uma referência do ambiente de origem), a referência é **removida do sub-agent** e listada no resumo da importação como "skills pendentes" — o import nunca deixa passar uma referência "morta" que causaria falha silenciosa do agente em produção. - As **ações de plataforma do fluxo** (etiquetar contato, transferir para um departamento, criar negócio no funil) também são **reconectadas na importação**: a etiqueta, o departamento, o funil e a etapa apontados por elas passam a ser os do workspace de destino. Se alguma dessas entidades não existir no destino — o caso típico de um pacote `.adflow` antigo, que ainda carrega uma referência do ambiente de origem —, a referência é **removida da ação** e o resumo da importação avisa. É deliberado: manter a referência de outro workspace faria a ação falhar em silêncio (ou, pior, agir sobre o registro errado). - As **credenciais que vieram com valor secreto** são recriadas e **recifradas com a chave do ambiente de destino** — nunca reaproveitam a cifra original do workspace de origem. - A **versão publicada de cada Agent importado é reconstruída no workspace de destino**, e não copiada tal como estava na origem. Isso garante que a especificação final do Agent aponte para as Skills, servidores MCP, ferramentas e artigos de conhecimento corretos, já religados no passo anterior — evitando referências quebradas depois do import. - Como proteção adicional, a **publicação de um Agent falha** se algum sub-agent inline referenciar uma Skill que não existe (ou não é visível) no workspace — o erro aparece na hora de publicar, citando o sub-agent e a referência problemática, em vez de gerar uma configuração quebrada que só falharia silenciosamente em produção. O import não tem trava de "mesmo workspace de origem" — qualquer usuário com permissão de importar pode trazer o pacote para outro workspace, inclusive de outra organização, desde que tenha a senha correta. Trate o arquivo `.adflow` com o mesmo cuidado que trataria uma cópia de backup: só compartilhe com quem deveria ter acesso ao que está dentro dele. --- ## Quando faltam credenciais Depois de importar, a plataforma mostra um resumo do que foi criado. Se algum item aparecer em **"credenciais pendentes"**, significa que: - O pacote foi exportado **sem incluir credenciais** (opção desmarcada na exportação), ou - Um servidor MCP do catálogo **não foi encontrado** no workspace de destino (por exemplo, um MCP que só existe no ambiente de origem). Nesses casos, a credencial é criada "vazia" e o fluxo **não vai funcionar de verdade** até que você: 1. Abra cada credencial listada como pendente e preencha o valor (senha, token, chave de acesso) manualmente. 2. Revise os servidores MCP sem catálogo resolvido e reconfigure-os, se necessário. Só depois disso o fluxo deve ser testado e publicado. --- ## Isolamento entre workspaces - Você só pode **exportar** um fluxo que pertence ao seu workspace atual. - Ao **importar**, o fluxo entra no workspace em que você está autenticado no momento — não é possível escolher outro workspace na hora do import. - O pacote `.adflow` em si não carrega nenhum vínculo fixo com o workspace de origem (nenhum dado sensível de identificação do ambiente original fica exposto no arquivo). --- ## Limites e formato do arquivo - O arquivo é um pacote `.adflow` (opaco, não é um texto legível), com tamanho **máximo de 10 MB** por padrão. - Uma senha errada (ou um arquivo corrompido/adulterado — mesmo que seja um único caractere alterado no meio do arquivo) impede a importação. A plataforma não consegue distinguir entre os dois casos, por segurança, e retorna apenas uma mensagem genérica de falha. Se o import falhar com uma mensagem sobre a senha, confira se você está usando exatamente a mesma senha definida na exportação. Não há como recuperar ou redefinir essa senha — se ela foi perdida, é preciso exportar o fluxo novamente a partir da origem. --- ## Para desenvolvedores: endpoints Os endpoints abaixo pertencem ao módulo Flow Builder e exigem autenticação JWT (`Authorization: Bearer {token}`), além das permissões dedicadas `flow-builder.export` e `flow-builder.import` (separadas de `flow-builder.edit`, por serem operações sensíveis — decifram segredos e clonam agregados inteiros a partir de um arquivo externo). Gerenciar as credenciais do Flow Builder em si (`POST`/`PATCH`/`DELETE`/`GET /flow-builder/credentials`) exige outra permissão dedicada, `flow-builder.credentials` — também separada de `flow-builder.edit`/`flow-builder.view`. Ou seja, quem só edita ou visualiza fluxos **não** ganha acesso automático a criar, atualizar, listar ou remover credenciais; sem `flow-builder.credentials`, a API responde `403`. ### Exportar um fluxo ``` POST /flow-builder/flows/{flow}/export ``` **Corpo da requisição:** | Campo | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | `passphrase` | `string` | Sim | Senha do pacote, mínimo 8 caracteres. | | `include_secrets` | `boolean` | Não | Inclui o valor das credenciais no pacote (padrão: `true`). | | `version` | `string` | Não | `active` (versão publicada) ou `draft` (rascunho). | **Respostas:** | Status | Quando | |--------|--------| | `200` | Download opaco do arquivo `{flow-slug}.adflow` — `Content-Type: application/octet-stream`, `Content-Disposition: attachment`. O corpo é o envelope cifrado (ver formato abaixo), não JSON legível do fluxo. | | `403` | Usuário sem a permissão `flow-builder.export`, ou fluxo de outro workspace. | | `422` | Senha ausente/curta, ou fluxo sem a versão solicitada (ex.: `version=active` sem publicação). | **Formato do envelope `.adflow` (corpo da resposta 200):** um JSON pequeno contendo **apenas metadados não sensíveis da cifra** em claro — nunca a estrutura do fluxo: ```jsonc { "format": "adflow", "version": 1, "kdf": "pbkdf2_sha256", "kdf_iterations": 210000, "salt": "", "nonce": "", "cipher": "aes-256-gcm", "ciphertext": "" } ``` O `ciphertext` decifrado (com a senha correta) é que contém o manifest completo (`entities`, `secrets_blob`, checksum interno etc.) — é exatamente aí que mora tudo que antes ficava em claro no arquivo. ### Importar um fluxo ``` POST /flow-builder/flows/import ``` **Corpo da requisição:** | Campo | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | `package` | `file` | Sim | Arquivo `.adflow`, até 10 MB (configurável). | | `passphrase` | `string` | Sim | A mesma senha usada na exportação. | **Respostas:** | Status | Quando | |--------|--------| | `201` | Fluxo importado como rascunho. Retorna o fluxo criado e um resumo (`summary`) com contagem de agents, skills, MCP servers e as listas `missing_secrets` e `missing_skills`. | | `422` | Senha incorreta, arquivo corrompido/adulterado, formato de pacote incompatível, ou workspace de destino sem nenhum canal/projeto para associar o fluxo. | O throttle de exportação é mais permissivo (30 requisições/minuto) do que o de importação (10 requisições/minuto), já que importar envolve mais processamento — clonagem de vários agregados em uma única transação. --- ## Próximos passos - [Testar e Publicar](/guia/flow-builder/testar-e-publicar) — publique o fluxo importado depois de revisá-lo - [Categorias, pastas e projetos](/guia/flow-builder/organizacao) — organize o fluxo recém-importado - [Cadastrar MCP Server](/dev/cadastrar-mcp-server) — reconfigure um MCP customizado que não resolveu no import --- ## `.adflow` e o catálogo de Soluções (`recipe-bundle`) O pacote `.adflow` hoje existe em duas variações, com o mesmo formato de envelope mas conteúdo diferente: - **`flow-bundle`** — é tudo que este documento descreve até aqui: exportar e importar **um fluxo seu**, para levá-lo entre workspaces. - **`recipe-bundle`** — é o formato usado pelas **Soluções** do catálogo do Atende Direito: um pacote curado que empacota Flow + Agent + Pipeline + grupos de follow-up, sem nenhum segredo dentro do arquivo. Ver [O que é uma solução](/guia/marketplace/o-que-e). Se você tentar importar um pacote `recipe-bundle` pela tela de importação de fluxos, a plataforma recusa com um aviso orientando você para o catálogo de Soluções — isso é intencional: uma solução não se importa como um fluxo avulso, ela se **instala** pelo fluxo próprio do Marketplace, que também cria o Agent, o Pipeline e os grupos de follow-up que acompanham o pacote. Ver [Instalar uma solução](/guia/marketplace/instalar-uma-solucao).