Versionamento de workers para agentes de IA

O deploy terminou, mas milhares de execuções continuam abertas

Um agente coordena onboarding de clientes. Algumas execuções terminam em minutos. Outras aguardam documento, aprovação ou resposta por vários dias. A equipe publica uma nova versão do worker e direciona as tarefas para o código atualizado.

Os novos casos funcionam. Uma execução antiga acorda depois de uma aprovação e encontra outra sequência de etapas, outro schema e uma atividade que não existia quando começou. O histórico já registrado e o código atual deixam de contar a mesma história.

Versionamento de workers define qual código pode retomar cada execução durável. A decisão inclui tarefas novas, trabalho em andamento, execuções adormecidas, atividades independentes, filas, compatibilidade de replay e prazo para retirar versões antigas.

O guia sobre blue-green ou canário compara estratégias de exposição entre ambientes. Este artigo resolve uma pergunta mais estreita: quando uma execução antiga volta a trabalhar, qual versão possui contrato compatível para continuar?

Por que um workflow durável muda o deploy

Uma aplicação comum recebe uma requisição, executa código e termina. Um workflow durável pode persistir estado, dormir, esperar um evento externo e retomar muito depois.

Durante esse intervalo, a equipe pode alterar:

ordem das etapas;
nomes e parâmetros de atividades;
regras de decisão;
schema do estado;
formato de eventos;
políticas de retentativa;
timers;
ferramentas;
permissões;
modelo ou instruções;
comportamento de tarefas filhas.

Quando a execução retoma, o orquestrador pode reconstruir seu estado a partir do histórico. O código precisa interpretar os eventos já registrados de forma compatível. Uma alteração válida para novas execuções pode quebrar o replay das antigas.

Por isso, publicar o container novo e encerrar o anterior imediatamente pode remover a única versão capaz de concluir parte do trabalho aberto.

Separe a versão da implantação e a versão da execução

Os termos parecem próximos, mas controlam objetos diferentes.

Versão da implantação

Identifica um conjunto de workers que executa a mesma composição de código. Pode combinar nome do deployment e build ID.

Versão da execução

Registra qual comportamento a execução usa para receber tarefas ao longo da vida. Ela pode permanecer fixada ou acompanhar versões promovidas, conforme o contrato escolhido.

Versão dos dados

Identifica schemas de estado, payload, eventos e artefatos. Duas versões de worker podem ler o mesmo schema ou exigir migração explícita.

Versão operacional do agente

Inclui código, modelo, instruções, ferramentas, fontes, permissões e políticas. O controle de mudanças trata essa composição completa.

Um build ID sozinho não prova qual prompt, modelo ou configuração produziu a decisão. O registro operacional deve ligar a execução à composição inteira.

Escolha entre execução fixada e atualização automática

A documentação atual do Temporal apresenta dois comportamentos principais para workflows versionados: Pinned e Auto-Upgrade. Os nomes são do produto, mas a decisão arquitetural aparece em outras plataformas duráveis.

Execução fixada

A execução permanece na mesma versão de worker durante a vida. Ela acorda, recebe eventos e conclui com o código compatível com seu início.

Esse comportamento ajuda quando:

o workflow possui vida limitada;
manter versões antigas durante esse período cabe na operação;
a sequência mudou de forma difícil de compatibilizar;
o estado interno depende fortemente do código;
a equipe quer evitar patching dentro do workflow;
a consequência exige reproduzir exatamente o contrato inicial.

O custo aparece na quantidade de versões simultâneas. Execuções longas podem manter builds antigos ativos por semanas ou meses.

Atualização automática

A execução pode avançar para a versão atual ou para uma versão em ramp-up. O código novo precisa continuar seguro para históricos criados pelas versões anteriores.

Esse comportamento ajuda quando:

workflows podem durar mais que a vida aceitável de um deployment;
correções precisam alcançar execuções abertas;
a equipe consegue manter replay compatível;
mudanças usam patching ou ramificações controladas;
o estado e os eventos possuem evolução bem definida.

O custo migra para engenharia de compatibilidade. Remover uma etapa, mudar a ordem de comandos ou reinterpretar um evento pode quebrar execuções que atravessam versões.

A escolha deve ocorrer por tipo de workflow. Um processo curto de classificação pode ficar fixado. Um relacionamento que permanece aberto por um ano pode precisar atualizar com segurança.

Classifique cada tipo de execução

Antes do deploy, inventarie os workflows e registre:

duração comum e extrema;
estados em que podem dormir;
eventos capazes de acordá-los;
quantidade aberta por versão;
efeitos externos possíveis;
schema persistido;
atividades e filas usadas;
tarefas filhas;
política de fixação ou atualização;
versão mínima compatível;
prazo para retirar o build;
dono da migração.

Considere quatro classes.

Curta e sem espera externa

Termina antes da janela normal de deploy. Drenagem pode resolver a transição, desde que novas entradas parem e o prazo seja respeitado.

Longa com estado interno

Mantém checkpoints ou histórico por horas ou dias. Precisa continuar no build original ou provar compatibilidade com o novo.

Adormecida aguardando evento

Pode ficar sem tarefa ativa durante muito tempo. A ausência na fila não significa conclusão. Essas execuções costumam ser esquecidas na retirada de versões.

Recorrente ou sem encerramento próximo

Permanece ativa por ciclos. Fixá-la para sempre cria uma versão imortal. Use evolução compatível, renovação planejada por Continue-As-New ou migração explícita.

Modele o registro da versão

Cada execução deve expor campos suficientes para roteamento e auditoria:

workflow_id
run_id
workflow_type
worker_deployment
worker_build_id
versioning_behavior
current_version
target_version
state_schema_version
input_schema_version
agent_composition_version
started_at
last_task_at
waiting_reason
next_wakeup_at
open_activities
open_children
last_checkpoint
migration_state

O painel precisa responder:

quais versões recebem novas execuções;
quantas execuções continuam fixadas em cada build;
quais estão adormecidas;
quais aguardam atividade independente;
quais podem migrar;
quais bloquearão a retirada;
quais sofreram override manual;
quais falharam por incompatibilidade.

Sem esse inventário, a equipe descobre dependências antigas ao desligar o último worker compatível.

Preserve compatibilidade de replay

Orquestradores duráveis podem reexecutar o código do workflow para reconstruir estado a partir do histórico. O replay espera que o código produza decisões compatíveis com os eventos já registrados.

Alterações sensíveis incluem:

inserir uma atividade antes de uma etapa já registrada;
remover um timer esperado;
mudar a ordem de comandos;
trocar um nome usado no histórico;
ler tempo ou aleatoriedade fora dos mecanismos do runtime;
chamar API ou banco diretamente no código determinístico;
alterar uma condição com base em dado externo atual;
mudar serialização sem compatibilidade.

A documentação dos SDKs do Temporal orienta colocar chamadas não determinísticas, como APIs e consultas de banco, em Activities. Para mudanças no workflow, apresenta versionamento por workers e patching como caminhos principais.

Use patching quando a execução atravessa versões

Uma marca de patch registrada no histórico permite que execuções antigas sigam o caminho anterior e novas usem o novo. A retirada costuma ocorrer em etapas:

adicionar o caminho novo com marcador;
publicar código capaz de executar os dois caminhos;
esperar ou migrar execuções antigas;
marcar o caminho anterior como obsoleto;
confirmar que nenhum histórico ainda depende dele;
remover o código antigo.

Patching acumula complexidade. Cada ramo precisa de teste e data de retirada. Marcadores sem inventário viram dívida permanente dentro do workflow.

Versione estado e eventos separadamente

Worker compatível com replay ainda pode falhar ao ler payload persistido.

Para cada schema, defina:

identificador de versão;
campos obrigatórios e opcionais;
valor padrão para ausências antigas;
transformação de leitura;
regra de escrita;
compatibilidade para trás e para frente;
eventos que exigem migração;
limite depois do qual a versão é recusada.

Evite regravar todo o estado apenas porque um worker novo foi publicado. A transformação deve ocorrer sob versão conhecida, produzir evidência e permitir retomada.

O guia sobre migração de estado em agentes cobre transformação, drenagem, retomada e rollback. O versionamento de workers decide qual código executa antes, durante e depois dessa migração.

Trate atividades e tarefas filhas

Uma execução pode iniciar trabalho em outras filas ou deployments. A versão do workflow principal não governa automaticamente todo componente externo.

A documentação do Temporal distingue atividades que pertencem ao mesmo Worker Deployment e Independent Activities executadas em outra fila ou implantação. Também descreve condições de herança para child workflows e cadeias de Continue-As-New.

Registre por chamada:

fila de destino;
deployment responsável;
versão mínima da atividade;
schema de entrada e saída;
política de retentativa;
idempotência;
prazo;
comportamento quando a versão some;
compatibilidade com o workflow chamador.

Uma execução fixada pode chamar uma atividade independente que avançou de versão. O contrato entre elas precisa permanecer compatível ou ficar explicitamente versionado.

Faça ramp-up com unidade estável

Uma versão candidata pode receber percentual crescente de novas execuções. O Temporal chama essa candidata de Ramping Version e mantém uma Current Version para o deployment.

O percentual serve somente quando o roteamento preserva uma unidade legível. Sorteio por tarefa pode fazer a mesma execução alternar entre builds de forma incompatível.

Defina:

quais workflows entram no ramp-up;
se o percentual vale apenas para novas execuções;
chave estável de distribuição;
tipos excluídos;
limite de autonomia;
métricas por versão;
erros que pausam o avanço;
janela de observação;
responsável pelo corte.

Uma sequência possível:

publicar a versão sem tráfego;
confirmar que workers consultam as filas esperadas;
executar testes de replay e integração;
enviar pequena parcela de novas execuções;
observar qualidade, erro, latência e efeitos;
ampliar em passos definidos;
promover a candidata a atual;
conservar versões antigas enquanto houver execuções fixadas;
retirar somente depois do gate de drenagem.

A página de implantação canário ajuda a definir coortes e critérios. Worker versioning acrescenta afinidade entre execução durável e código compatível.

Acorde execuções adormecidas com cuidado

Workflows que esperam timers ou eventos podem não receber uma tarefa logo após o deploy. A documentação de migração do Temporal orienta manter workers antigos enquanto execuções em andamento atravessam a transição e descreve o uso de sinais para acordar workflows ociosos quando necessário.

Acordar tudo de uma vez cria riscos:

pico de tarefas;
chamadas simultâneas a dependências;
aumento de custo;
eventos sem validade;
corrida com respostas reais;
milhares de execuções descobrindo a mesma incompatibilidade.

Faça o despertar por classes e lotes:

inventarie estados e datas;
exclua execuções concluídas ou vencidas;
selecione uma amostra representativa;
limite taxa e concorrência;
confirme replay e próximo estado;
monitore dependências e filas humanas;
amplie gradualmente;
pause diante de erro compartilhado.

Um sinal técnico para despertar não autoriza repetir a consequência empresarial. Revalide prazo, objeto e política antes da próxima ação.

Defina overrides como exceção governada

Pode ser necessário fixar uma execução específica em outro build, mover uma classe ou impedir atualização temporariamente.

Cada override deve registrar:

execução ou conjunto afetado;
versão anterior e destino;
motivo;
evidência de compatibilidade;
aprovador;
início e expiração;
monitoramento reforçado;
condição de retorno;
responsável.

Overrides permanentes fragmentam a operação. Um caso especial sem prazo pode manter deployment, schema e política antigos indefinidamente.

Retire uma versão somente depois do gate

“Não recebe novas entradas” ainda deixa trabalho aberto.

Antes de desligar um build, confirme:

nenhuma nova execução é roteada para ele;
não existem workflows fixados ativos;
execuções adormecidas foram localizadas;
timers futuros foram tratados;
atividades abertas possuem destino compatível;
child workflows e Continue-As-New foram verificados;
filas exclusivas estão drenadas;
callbacks e sinais tardios possuem rota;
estado antigo está migrado ou encerrado;
replay de históricos relevantes passa no novo código;
credenciais podem ser revogadas;
logs e evidências permanecem acessíveis;
rollback já não depende daquele build.

Se algumas execuções não podem migrar, mantenha capacidade mínima com prazo e dono. Uma versão esquecida com credenciais amplas vira dívida operacional e superfície de risco.

Desenhe rollback para execuções novas e antigas

Promover uma versão e depois voltar o tráfego resolve apenas novas entradas.

O rollback precisa classificar:

Execuções ainda sem efeito

Podem ser pausadas, reenviadas ou mantidas na versão candidata conforme compatibilidade.

Execuções com estado produzido

Precisam confirmar se a versão anterior entende o schema e os eventos novos.

Execuções com efeito externo

Exigem reconciliação antes de repetir, compensar ou retomar.

Execuções fixadas na candidata

Podem precisar que o worker candidato permaneça ativo mesmo depois de novas entradas voltarem à versão anterior.

Execuções autoatualizáveis

Devem usar patch compatível ou override explícito. Mover para trás pode ser tão incompatível quanto avançar.

Rollback de roteamento e rollback de estado são decisões separadas. O primeiro interrompe exposição. O segundo restaura capacidade operacional com evidência.

Exemplo: onboarding com espera por documentos

Um workflow prepara cadastro, solicita documentos e aguarda resposta do cliente.

Versão 1

Aceita documento único, executa validação e envia o caso para aprovação.

Versão 2

Passa a aceitar pacote de arquivos, cria etapa de integridade e usa novo schema para pendências.

Novas execuções

Entram gradualmente na versão 2. Os primeiros casos ficam em modo de preparação, sem liberar cadastro final.

Execuções abertas na versão 1

Permanecem fixadas até concluir, porque o evento de resposta e o estado interno seguem o contrato antigo.

Casos de longa duração

A equipe define prazo. Depois dele, o workflow encerra a run atual por Continue-As-New com payload mínimo e schema novo, mediante transformação validada.

Retirada

A versão 1 continua com capacidade mínima até zerar execuções, timers e atividades. Depois, credenciais exclusivas são revogadas e a versão sai do inventário ativo.

Esse desenho evita que um cliente envie documentos para um fluxo iniciado sob um contrato e seja retomado por código que espera outro.

Teste a transição, não apenas a versão nova

Inclua cenários como:

nova execução na versão atual;
nova execução na versão em ramp-up;
workflow fixado que acorda depois do deploy;
workflow autoatualizável atravessando patch;
replay de histórico antigo no código novo;
atividade independente em versão diferente;
child workflow herdando versão;
Continue-As-New preservando ou alterando comportamento;
timer antigo disparando depois da promoção;
sinal tardio para execução adormecida;
schema antigo sem campo novo;
schema novo lido por worker anterior;
rollback com efeito externo confirmado;
rollback com confirmação perdida;
desligamento do último worker antigo;
pico provocado por despertar em lote;
override expirado;
versão candidata sem consumidores saudáveis.

Confira replay, roteamento, estado, quantidade de efeitos, filas, métricas e capacidade de interromper.

Métricas para operar versões de workers

Acompanhe:

workers saudáveis por deployment e build;
tarefas recebidas por versão;
novas execuções por comportamento;
workflows ativos e adormecidos por build;
idade extrema das execuções fixadas;
tarefas sem worker compatível;
falhas de replay ou não determinismo;
erros por schema;
atividades independentes por versão;
overrides ativos e vencidos;
percentual de ramp-up;
qualidade, latência, custo e efeitos por versão;
tempo para drenar builds antigos;
versões mantidas além do prazo;
migrações e Continue-As-New concluídos;
rollback por causa;
execuções bloqueando retirada.

O alerta deve explicar impacto: “42 onboardings continuam fixados no build 1.8; três aguardam documento além do prazo de retirada; o worker permanece ativo e o dono do processo revisará os casos até sexta-feira”.

Checklist de versionamento

[ ] Cada tipo de workflow possui duração e estados de espera conhecidos?
[ ] Deployment, execução, dados e composição do agente têm versões próprias?
[ ] O comportamento fixado ou atualizável foi escolhido por tipo?
[ ] Execuções abertas e adormecidas aparecem no inventário?
[ ] O código novo passa no replay de históricos relevantes?
[ ] Mudanças incompatíveis usam patch, migração ou fixação?
[ ] Schemas possuem regra de compatibilidade?
[ ] Atividades independentes e tarefas filhas têm contrato explícito?
[ ] O ramp-up usa unidade estável e critérios de avanço?
[ ] O despertar ocorre em lotes com revalidação de negócio?
[ ] Overrides possuem motivo, prazo e dono?
[ ] Rollback trata roteamento, estado e efeitos separadamente?
[ ] Existe gate para retirar cada build?
[ ] Credenciais antigas são revogadas depois da drenagem?
[ ] Métricas mostram qual versão ainda possui trabalho?

A versão precisa acompanhar o trabalho

Workflows duráveis atravessam deploys, esperas, aprovações e mudanças de schema. O código que recebe a próxima tarefa precisa entender o histórico e o estado que já existem.

Execuções fixadas reduzem a carga de compatibilidade, mas prolongam versões. Atualização automática reduz a vida dos deployments, mas exige replay seguro, patching e contratos evolutivos. O desenho maduro escolhe por tipo de workflow, amplia tráfego com evidência e retira builds somente quando o trabalho aberto possui destino conhecido.

Fontes oficiais verificadas em 2 de outubro de 2026:

Temporal: Worker Versioning, para Worker Deployment Version, Current e Ramping Version, Pinned e Auto-Upgrade, herança e limites.
Temporal: migração de workers sem versão, para publicação paralela, ramp-up, promoção, manutenção de workers antigos e tratamento de workflows ociosos.
Temporal Python SDK: versionamento de workflows, para compatibilidade de replay, separação de trabalho não determinístico em Activities e ciclo de patching.
Temporal: Worker Deployments, para o uso recomendado de Worker Versioning em novos deployments e alternativas quando a infraestrutura ainda não suporta o recurso.

Os nomes e mecanismos citados pertencem ao Temporal. Em outra plataforma, confirme como o runtime roteia tarefas, reconstrói histórico, trata código antigo e garante compatibilidade antes de aplicar o mesmo desenho.