Atende Direito · Docs

Tema

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.

Dica

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.

Exportando um fluxo ​

Passo a passo
  1. Abra o fluxo no editor e, no canto superior direito do canvas, clique em **Recursos → Exportar (.adflow)**.
  2. 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).
  3. 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.
  4. Defina a **senha do pacote** (mínimo 8 caracteres).
  5. Confirme. O download do arquivo `{nome-do-fluxo}.adflow` começa automaticamente.
Dica

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
  1. Abra qualquer fluxo no editor (dentro do workspace de destino) e, no menu **Recursos**, escolha **Importar (.adflow)**.
  2. Selecione o arquivo `.adflow` que você exportou anteriormente.
  3. Informe a **senha** usada na exportação.
  4. 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.
  5. 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).
  • 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) 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.

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.

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).

Dica

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:

CampoTipoObrigatórioDescrição
passphrasestringSimSenha do pacote, mínimo 8 caracteres.
include_secretsbooleanNãoInclui o valor das credenciais no pacote (padrão: true).
versionstringNãoactive (versão publicada) ou draft (rascunho).

Respostas:

StatusQuando
200Download 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.
403Usuário sem a permissão flow-builder.export, ou fluxo de outro workspace.
422Senha 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": "<base64>",
  "nonce": "<base64>",
  "cipher": "aes-256-gcm",
  "ciphertext": "<base64 — todo o manifest do fluxo, cifrado>"
}

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:

CampoTipoObrigatórioDescrição
packagefileSimArquivo .adflow, até 10 MB (configurável).
passphrasestringSimA mesma senha usada na exportação.

Respostas:

StatusQuando
201Fluxo 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.
422Senha incorreta, arquivo corrompido/adulterado, formato de pacote incompatível, ou workspace de destino sem nenhum canal/projeto para associar o fluxo.
Dica

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 ​

.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.