Visão geral

Um deployment é uma versão publicada de um workflow que callers externos podem executar. Enquanto você constrói, um workflow vive no canvas como rascunho que só você pode rodar. Publicar gera uma cópia fixa desse rascunho e dá a ela um endereço: um endpoint REST, uma página de chat ou um conjunto de ferramentas MCP. Cada um é uma superfície, um canal pelo qual callers alcançam o mesmo workflow publicado.

Como publicar um livro, construir e publicar são atos separados. Você rascunha e revisa livremente no canvas. Quando clica em Deploy, o Zoen imprime uma edição fixa. Os leitores recebem aquela edição, não o seu rascunho mais recente, até você publicar uma nova. Você sempre pode voltar a uma impressão anterior.

O modelo de deployment

Snapshot

Um snapshot é uma cópia imutável do seu workflow tirada no momento em que você publica. Fica congelado: editar o canvas depois muda o rascunho, não o snapshot. Toda chamada ao seu deployment roda contra o snapshot, então uma edição pela metade no canvas nunca chega a um caller ao vivo. Publicar de novo tira um snapshot fresco do rascunho atual.

Versão

Cada snapshot é registrado como uma versão numerada (v1, v2, e assim por diante) na tabela Versions, marcada com quem publicou e quando. As versões são independentes: uma fica ao vivo por vez, marcada com um ponto verde, e as demais permanecem disponíveis para renomear, descrever, carregar de volta no canvas ou promover. Você publica a v1 com Deploy e cada Update seguinte adiciona a próxima versão.

Versão ao vivo

A versão ao vivo é o snapshot atualmente exposto em todas as superfícies. A aba General a mostra como Live Workflow, um minimapa somente leitura do que os callers executam. Só uma versão fica ao vivo por vez. Promover uma versão diferente, ou atualizar para uma nova, troca qual snapshot está ao vivo sem afetar os outros.

Update

Depois que você altera o canvas de um workflow publicado, um badge Update deployment aparece na barra de ferramentas para sinalizar que a versão ao vivo está atrás do rascunho. Clicar em Update tira um novo snapshot, registra como a próxima versão e a torna ao vivo, tudo sem reabrir o modal de deploy.

Promote to live

Promote to live faz uma versão anterior voltar a ser a ao vivo. É o caminho rápido para rollback: se um deployment novo se comporta mal, promova a última versão boa conhecida para restaurá-la na hora. Promover reutiliza um snapshot existente, então não cria uma versão nova.

As superfícies

Toda superfície roda o mesmo snapshot ao vivo. Você as gerencia nas abas do modal de deploy.

A superfície mais comum é a API. Depois de publicado, seu workflow responde em:

POST https://app.zoen.space/api/workflows/{workflow-id}/execute

Envie um objeto no corpo da requisição correspondente ao Input Format do workflow. A resposta é um objeto com as saídas dos blocos e metadados de execução.

curl -X POST https://app.zoen.space/api/workflows/{workflow-id}/execute \
  -H "X-API-Key: $ZOEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": "Refund request from customer #4821" }'

Versionamento na prática

Trate a versão ao vivo como produção e o canvas como staging. Rode o workflow no canvas até se comportar bem, depois Deploy ou Update para publicar. Os callers continuam batendo no snapshot anterior até a nova versão ir ao vivo, então não há estado pela metade. Se uma versão nova der problema, Promote to live a anterior para fazer rollback na hora, depois corrija o rascunho e atualize de novo quando estiver pronto. Os logs registram toda execução contra toda versão, então você pode confirmar qual snapshot uma execução usou.

Próximos passos