Migrating to the Workflow SDK: migre sem perder retomada e idempotência

ANÁLISE EDITORIAL

Trocar um orquestrador de tarefas não é apenas traduzir nomes de funções. Um fluxo que espera um sinal externo, tenta novamente após uma falha e cobra um cartão precisa preservar as mesmas garantias ao mudar de plataforma. A Skill Migrating to the Workflow SDK, mantida no repositório da Vercel, ajuda a mapear essa migração a partir de Temporal, Inngest, Trigger.dev ou AWS Step Functions.

O ponto mais útil do material é pedir um plano antes do código. Ele separa orquestração, efeitos externos e mecanismo de retomada. Isso reduz uma falha comum: produzir uma conversão que parece plausível em TypeScript, mas perde idempotência, cria um endpoint de callback desnecessário ou executa uma chamada de rede dentro de uma função que deveria ser determinística. A Skill não migra um sistema sozinha e não comprova que o comportamento em produção foi preservado.

O que esta Skill faz

O arquivo principal pergunta qual é o sistema de origem, onde o novo fluxo será executado e quais mecanismos o fluxo antigo usa. Em seguida, direciona o agente para uma das quatro referências de origem e para referências compartilhadas sobre retomada, tentativas, padrões comuns e execução gerenciada ou própria. O pacote local preserva esses oito arquivos Markdown, não somente a primeira página do manual.

O resultado proposto tem seis partes: plano de migração, mapa entre conceitos antigos e novos, código migrado, fronteiras da aplicação e endpoints de retomada, checklist de verificação e questões ainda abertas. A estrutura força a explicitação de decisões como “callback com URL gerada” versus “retomada interna por token de negócio”.

Para quem serve e quando não usar

Serve a desenvolvedores TypeScript e equipes de plataforma que já mantêm workflows com Temporal, Inngest, Trigger.dev ou Step Functions e estão avaliando ou executando uma migração para o Workflow SDK. Também ajuda revisores a conferir se uma proposta preserva espera, retry, fan-out, callbacks e efeitos externos.

Não é uma Skill genérica para criar a primeira automação, nem um instalador do SDK. Se a dúvida ainda é escolher entre modelos de execução, o comparativo Temporal ou Inngest aborda a decisão anterior. Para um exemplo introdutório em outra plataforma, há o guia de AWS Step Functions. Aqui o foco é traduzir um fluxo existente e verificar o que poderia se perder na transição.

Origem, adoção e versão

A origem canônica é vercel/workflow, pasta skills/migrating-to-workflow-sdk, no commit fc130d44a845eee25123fcd2891335a38db88867. O manifesto declara a versão 0.3.0 da Skill e atribui a autoria a Vercel Inc. A API do GitHub mostrou 2.429 estrelas em 22 de setembro de 2026; esse é um retrato da adoção do repositório, não uma avaliação da qualidade desta migração específica.

O repositório declara licença Apache-2.0. A release workflow@4.8.9, publicada em 15 de setembro de 2026, identifica uma versão do software, não a versão 0.3.0 da Skill. A documentação do SDK evolui: verifique a versão realmente instalada no projeto e as páginas oficiais atuais antes de aceitar assinaturas de API ou comandos.

Compatibilidade e limites

A Skill é um conjunto de instruções Markdown para agentes que leem o formato SKILL.md. Seu conteúdo trata de workflows em TypeScript e de quatro sistemas de origem específicos. Ela pode orientar uma revisão sem rodar código, mas a implementação exige um projeto JavaScript ou TypeScript, o pacote Workflow SDK e um runtime suportado. A trilha gerenciada e a trilha de hospedagem própria não são equivalentes na operação: a própria referência de runtime informa que a segunda exige uma implementação de World e inicialização correspondente.

Não tratamos os exemplos do pacote como teste de compatibilidade com todas as versões de Temporal, Inngest, Trigger.dev, AWS Step Functions, Next.js ou outros frameworks. Também não testamos uma migração completa em produção. Os nomes de APIs e o comportamento de retry devem ser confrontados com o código e a documentação da versão usada pela equipe.

Pré-requisitos

• O código e a configuração do workflow atual, com autorização para examiná-los.
• Inventário de entradas, saídas, timers, sinais, callbacks, efeitos externos, tentativas e compensações.
• Ambiente isolado para a versão do Workflow SDK escolhida e acesso à documentação oficial.
• Dados de teste sem credenciais reais e uma forma de comparar eventos e resultados do fluxo antigo e do novo.
• Plano de reversão e decisão explícita para execuções antigas que continuam em andamento.

Antes de copiar um workflow para um agente, remova tokens, segredos, dados pessoais e detalhes de clientes que não sejam necessários à análise. Uma chave de API nunca precisa estar no SKILL.md, no ZIP, em um prompt público ou em GitHub. Use o gerenciador de segredos do ambiente de execução e permissões mínimas.

Instalação segura do pacote

O download local auditado contém SKILL.md, oito arquivos em references/, LICENSE.md e ORIGEM.md. Todos os documentos da origem foram copiados com os bytes do commit fixado; a nota de origem registra o SHA-256 de cada um. O ZIP não carrega binários, executáveis, dependências, testes de avaliação, código de aplicação, credenciais ou dados de workflows.

Descompacte em uma pasta de Skill do cliente de IA que você usa, mantendo o diretório migrating-to-workflow-sdk e as referências no mesmo nível relativo indicado pelo manifesto. Reinicie ou recarregue o cliente se ele não detectar novas Skills automaticamente. Depois confirme que o agente consegue abrir references/resume-routing.md e a referência do sistema de origem escolhido. Sem esses arquivos, a rota principal fica incompleta.

Para instalar a versão oficial mais recente, o repositório oficial e sua documentação são a referência. Uma atualização posterior pode divergir do ZIP fixado, por isso compare o diff e a licença antes de substituir a cópia. O download deste catálogo não instala o Workflow SDK no projeto.

Configuração antes da análise

Delimite uma migração pequena e representativa. Registre sistema de origem, framework de destino, runtime gerenciado ou próprio, versão dos pacotes, topologia de callbacks e política de retries. Separe a lógica pura de orquestração das chamadas que alteram o mundo: banco, cobrança, email, API externa, fila e gravação em storage. Os efeitos externos precisam de tratamento idempotente porque uma tentativa pode ser repetida.

O manifesto propõe três caminhos de retomada: resume/internal para uma ação do próprio servidor com token de negócio determinístico; resume/url/default para um serviço externo que usa a URL gerada e aceita a resposta padrão; e resume/url/manual apenas quando a resposta HTTP personalizada é realmente necessária. A referência resume-routing.md deve ser lida antes de gerar código. Escolher o caminho errado pode deixar um processo parado ou duplicar uma ação.

Primeiro uso, passo a passo

1. Escolha um workflow de teste sem dados ou transações reais. Descreva sua entrada, saída e um caso de falha conhecido.
2. Peça ao agente para ler o SKILL.md e a referência da origem, como references/temporal.md ou references/inngest.md. Se houver sinais ou callbacks, acrescente references/resume-routing.md.
3. Exija o plano e o mapeamento de conceitos antes do código. Confirme a rota de retomada, o destino de cada efeito externo e a chave de idempotência prevista.
4. Revise o diff proposto por uma pessoa que conhece o fluxo antigo. Confira contratos de entrada e saída, prazos, retries, tratamento de erro e compensações.
5. Execute testes em ambiente isolado: sucesso, timeout, callback duplicado, erro antes e depois de um efeito externo, reinício do processo e repetição de etapa.
6. Compare eventos e resultados com o comportamento esperado. Só então planeje a migração de tráfego e a convivência com execuções antigas.

Um pedido inicial útil é: “Analise este fluxo de teste em Temporal para o Workflow SDK, leia as referências da origem e de retomada, entregue primeiro o plano e o mapa de conceitos; não execute código nem acesse serviços externos”. A formulação mantém a primeira rodada como revisão, não como implantação.

Resultado esperado e como validar

O resultado esperado é uma proposta verificável, não um arquivo que “parece compilar”. A função marcada com "use workflow" deve coordenar; funções marcadas com "use step" devem concentrar efeitos externos. A documentação de workflows e steps explica esse limite. A saída deve mostrar qual mecanismo retoma a execução, como o webhook é exposto, o que acontece se uma etapa falha e como um write externo evita duplicação.

Valide especialmente os casos negativos do próprio manifesto: nenhuma chamada de rede ou banco dentro da função de orquestração, nenhuma mistura entre createWebhook() e resumeHook(), nenhuma URL de callback inventada quando a API já a gera, nenhum sleep() dentro de step e nenhuma escrita externa sem chave de idempotência. Uma suite de testes ou uma simulação controlada deve demonstrar cada contrato relevante do fluxo real.

Permissões, segurança e riscos

Ler o ZIP não concede acesso a uma conta Vercel, Temporal, AWS ou banco. O risco surge quando o agente recebe código privado, credenciais ou autorização para executar comandos e implantar alterações. Use uma cópia do projeto com dados sintéticos, credenciais de teste restritas e revisão do diff. Não cole segredo em chat, arquivo de exemplo, commit ou issue. Arquivos .env e similares devem permanecer fora do repositório, mas o .gitignore não substitui um gerenciador de segredos nem remove um segredo já publicado.

Callbacks exigem validação de origem, autenticação ou assinatura conforme o serviço emissor. Para pagamentos e notificações, planeje idempotência antes de repetir tentativas. Para fluxos longos, verifique a orientação de versionamento: uma implantação nova não deve ser presumida como substituta automática das execuções já iniciadas. O plano de corte precisa dizer o que permanece no sistema antigo, o que migra e como reverter.

Erros comuns e como corrigir

• O agente encontra o manifesto, mas não consegue abrir a referência: preserve a pasta references/ junto do SKILL.md; não copie apenas o arquivo principal.
• O código tenta acessar banco dentro do workflow: mova a operação para um step e valide o comportamento em caso de retry.
• O fluxo fica aguardando um evento externo: confira a rota de retomada selecionada, o token de correlação e a URL efetivamente entregue ao emissor.
• Um callback produz duas cobranças ou mensagens: teste duplicação e reenvio; use chave de idempotência estável e controle do lado do serviço afetado.
• A saída mistura assinatura de APIs de versões diferentes: compare a versão instalada com a documentação atual e o commit auditado; não copie um exemplo de outra versão sem revisão.
• O exemplo funciona localmente, mas não em hospedagem própria: releia runtime-targets.md e confirme o World e o bootstrap necessários ao runtime escolhido.

Versão, licença e download auditado

Este espelho documental foi fixado no commit fc130d44a845eee25123fcd2891335a38db88867, sob Apache-2.0. O ZIP hospedado pelo Bastidores da IA tem SHA-256 a1762d8924b4572b21e814fdfea4e5c0fb8e37b0f918e6d7cadde422e5f6e4ed. Verifique o hash após baixar, descompacte em ambiente de teste e leia ORIGEM.md antes de instalar.

O pacote não inclui o SDK nem declara que uma migração foi executada. O repositório oficial da Skill fica disponível separadamente para conferência do código-fonte e de atualizações. O botão de download local e o botão de repositório no card do catálogo têm funções diferentes.

Fontes primárias consultadas

• Skill e oito referências no commit auditado.
• Licença Apache-2.0 do repositório.
• Documentação oficial do Workflow SDK.
• Explicação técnica da Vercel sobre execução durável.