Migrar o estado de agentes de IA sem quebrar tarefas

A versão nova pode abrir um estado que ela já não entende

Um agente comercial grava uma tarefa enquanto aguarda aprovação. O estado contém oportunidade, ação proposta, fontes consultadas e o identificador da pessoa que deve decidir. Na versão seguinte, a equipe divide acao_proposta em tipo_acao, destinatario e parametros. O deploy termina sem erro. Horas depois, uma tarefa antiga é retomada e o novo código recebe o formato anterior.

O problema pode aparecer como campo ausente, aprovação órfã, ferramenta chamada com parâmetros incompletos ou tarefa reiniciada desde o começo. Trocar código foi fácil. Preservar o trabalho em andamento exigia uma migração de estado.

Migrar o estado de agentes de IA significa alterar a estrutura usada por sessões, checkpoints, filas e execuções persistidas sem perder identidade, decisão, evidência ou controle sobre consequências externas.

O foco deste guia é o schema do estado persistido. O artigo sobre blue-green ou canário para agentes de IA ajuda a escolher a estratégia de exposição da versão. Aqui, a pergunta é mais estreita: como a versão nova lê, transforma, retoma e encerra unidades criadas pela versão anterior?

O que entra no estado de uma execução

Histórico de conversa é apenas uma parte. Uma tarefa durável pode guardar:

identificador da unidade de trabalho;
organização, cliente e usuário;
versão do agente e do schema;
objetivo confirmado;
etapa atual;
entradas e fontes usadas;
resultado parcial;
ferramentas já chamadas;
efeitos confirmados em sistemas externos;
chave de idempotência;
tentativas e erros;
aprovação pendente ou concluída;
permissões temporárias;
prazo e validade;
próxima ação;
condição de encerramento.

Esse conjunto permite pausar, investigar, retomar ou transferir trabalho. Quando a estrutura muda, cada campo pode afetar uma decisão posterior.

A documentação de sessões do OpenAI Agents SDK, consultada em 22 de setembro de 2026, descreve sessões que persistem itens entre execuções e oferece implementações para bancos e serviços diferentes. A referência de RunState, verificada na mesma data, registra que snapshots serializados podem preservar respostas, itens gerados e estado de aprovação para retomada. A própria referência alerta que contexto personalizado pode exigir serializador e desserializador próprios.

A escolha do framework resolve parte da persistência. A aplicação continua responsável pelo significado empresarial do estado e pela compatibilidade entre versões.

Schema, versão do agente e versão do processo são objetos separados

Use identificadores distintos.

Versão do agente

Representa a composição executável: código, modelo, instruções, ferramentas, políticas e configurações.

Versão do schema

Representa a estrutura do estado persistido. Uma versão pode adicionar, renomear, dividir ou retirar campos, além de mudar tipos e valores permitidos.

Versão do processo

Representa regras do negócio. Um status que antes permitia contato pode ter deixado de permitir. Uma aprovação pode precisar de outra alçada. O JSON continua válido, mas a decisão mudou.

Guardar apenas versao: 4 mistura essas dimensões. Prefira algo legível:

{
  "agent_version": "followup-2026.09.22.1",
  "state_schema_version": 3,
  "process_policy_version": "comercial-2026-09",
  "work_item_id": "OP-2481:followup:2026-09-22"
}

Assim, a equipe sabe se precisa adaptar estrutura, revalidar política ou manter a unidade na composição anterior.

Comece com um inventário dos estados vivos

Antes da mudança, conte e classifique as unidades persistidas. Não trate o banco como uma coleção homogênea.

Separe pelo menos:

schema atual;
versão do agente de origem;
etapa do fluxo;
idade;
aprovação pendente;
efeito externo já realizado;
credencial ou delegação ainda válida;
possibilidade de concluir na versão antiga;
necessidade de intervenção humana;
prazo de utilidade da tarefa.

Uma tarefa recebida e ainda não processada pode ser recriada com baixo risco. Uma tarefa que já enviou mensagem e aguarda confirmação precisa preservar o efeito. Uma aprovação concedida sobre parâmetros antigos talvez não possa acompanhar a transformação.

O inventário produz quatro destinos úteis:

drenar na versão antiga: deixa a unidade terminar no código que a criou;
migrar automaticamente: transforma estado quando a equivalência é determinística;
migrar com revisão: prepara a conversão e pede decisão para campos ambíguos;
encerrar ou reiniciar: cancela a unidade vencida e cria outra somente quando ainda existe finalidade.

Classifique cada mudança de schema

Nem toda alteração possui o mesmo risco.

Adição compatível

Um campo opcional novo recebe valor padrão ou pode ser calculado a partir de fonte oficial. Estados antigos continuam válidos.

Exemplo: adicionar motivo_bloqueio como opcional.

Renomeação

O significado permanece, mas a chave muda. Durante a transição, leitores podem aceitar as duas formas e gravar a nova.

Exemplo: responsavel vira responsavel_id.

Divisão ou combinação

Um campo antigo vira vários, ou vários viram um. A transformação pode exigir regra de negócio.

Exemplo: acao_proposta vira tipo, destinatário, canal e parâmetros.

Restrição de domínio

O campo mantém o nome, mas aceita menos valores. Um estado antigo pode conter opção removida.

Exemplo: status = aguardando passa a exigir aguardando_cliente ou aguardando_aprovacao.

Mudança semântica

A estrutura parece igual, porém o significado mudou. É a classe mais fácil de ignorar.

Exemplo: aprovado = true antes liberava qualquer atualização interna. A política nova limita a aprovação a um objeto, uma versão e uma ação.

Remoção

Um campo deixa de existir. Antes de apagar, confirme que nenhuma tarefa, relatório, auditoria ou rotina de rollback depende dele.

A documentação de compatibilidade retroativa do LangGraph, consultada em 22 de setembro de 2026, recomenda adicionar campos novos como opcionais, tratar remoções como deprecações e manter leitura ou escrita dupla durante uma janela quando necessário. O documento destaca que checkpoints antigos podem voltar pela versão mais recente do grafo, o que transforma mudanças de estado em contrato de compatibilidade.

Use a sequência expandir, migrar e contrair

Uma troca direta obriga todos os registros e todos os workers a mudar ao mesmo tempo. Uma sequência em três fases reduz essa dependência.

1. Expandir

Publique leitores capazes de entender o formato antigo e o novo. Adicione campos sem tornar sua presença obrigatória para checkpoints antigos. Registre qual caminho foi usado.

Durante essa fase:

aceite schema_version anterior;
normalize a leitura para um modelo interno atual;
continue preservando o valor antigo quando necessário;
bloqueie estados desconhecidos;
monitore quantas unidades ainda usam cada versão.

2. Migrar

Transforme estados elegíveis com uma função versionada e idempotente. A mesma unidade não pode perder informação se a migração for repetida.

Uma migração deve registrar:

work_item_id
schema_origem
schema_destino
transformacao
campos_preservados
campos_calculados
campos_ambiguos
resultado
horario
versao_do_migrador

Faça backup ou preserve o estado original em trilha controlada. Não copie segredos e dados excessivos para logs.

3. Contrair

Retire leitura e escrita do formato antigo somente depois que:

nenhuma unidade ativa depende dele;
filas atrasadas foram verificadas;
sessões pausadas foram tratadas;
rollback não exige o leitor antigo;
relatórios e rotinas de suporte foram atualizados;
a migração passou por reconciliação;
o dono do processo aprovou o encerramento.

O prazo deve seguir o ciclo real da tarefa. Uma rotina mensal pode manter estado antigo por mais tempo que um atendimento concluído em horas.

Escreva transformações explícitas

Não peça ao modelo para “interpretar o estado antigo”. Migração estrutural precisa ser determinística sempre que os dados permitirem.

Considere o estado antigo:

{
  "schema_version": 1,
  "status": "aguardando",
  "acao_proposta": "Enviar resumo para Ana",
  "aprovado": true
}

A versão nova exige:

{
  "schema_version": 2,
  "status": "aguardando_execucao",
  "action": {
    "type": "send_summary",
    "recipient_id": "CONTATO-104",
    "channel": "email"
  },
  "approval": {
    "decision": "approved",
    "approved_action_hash": "...",
    "expires_at": "2026-09-22T18:00:00Z"
  }
}

O texto “Ana” não contém identificador nem canal confirmado. A migração pode reconhecer o tipo provável, mas não deveria inventar recipient_id, escolher e-mail ou fabricar validade. O destino correto é exige_revisao, com o texto original e a lacuna visíveis.

Uma transformação segura separa:

cópia literal;
conversão determinística;
consulta a fonte oficial;
valor padrão aprovado;
campo desconhecido;
decisão que exige pessoa.

Aprovações não acompanham qualquer transformação

Uma pessoa aprovou o que viu. Se destinatário, valor, canal, documento, versão ou efeito mudaram, a autorização pode ter perdido validade.

Para cada aprovação migrada, confirme:

objeto examinado;
parâmetros apresentados;
versão do estado;
política aplicada;
identidade do aprovador;
horário e expiração;
alteração ocorrida durante a migração;
efeito ainda não executado.

Mudanças meramente estruturais podem preservar a decisão quando existe equivalência demonstrável. Mudança semântica pede nova aprovação. O guia sobre controle de concorrência em agentes de IA mostra por que o estado também precisa ser revalidado antes da consequência.

Escolha entre drenagem, migração preguiçosa e migração em lote

Drenagem

A versão antiga conclui unidades já iniciadas. A nova recebe somente tarefas novas.

Funciona quando a duração é curta, a versão anterior pode permanecer segura e os dois caminhos não disputam o mesmo objeto.

Migração preguiçosa

O estado é transformado quando volta a ser usado. Reduz trabalho sobre unidades que talvez nunca sejam retomadas.

Exige bloqueio por unidade, função idempotente e tratamento claro para falha. Duas retomadas simultâneas não podem migrar o mesmo checkpoint de formas diferentes.

Migração em lote

Uma rotina transforma estados antes da troca. Facilita medir cobertura e resolver pendências antecipadamente.

O risco cresce com volume, dados sensíveis e efeitos indiretos. Rode em cópia ou ambiente controlado, compare contagens e publique por lotes reversíveis.

Combinação

Uma operação pode drenar tarefas perto da conclusão, migrar em lote estados comuns e deixar sessões antigas para conversão na retomada. O destino deve ser decidido por etapa e consequência.

Teste a retomada, não somente a conversão do JSON

Um arquivo validado pelo novo schema ainda pode produzir comportamento incorreto.

Monte casos com:

tarefa criada na versão antiga e retomada na nova;
campo novo ausente;
valor antigo já removido;
aprovação pendente;
aprovação concluída sobre parâmetros alterados;
ferramenta já executada com confirmação perdida;
retentativa depois da migração;
sessão expirada;
estado parcialmente transformado;
migração executada duas vezes;
rollback para a versão anterior;
dois workers tentando migrar a mesma unidade;
dado sensível que não deve aparecer no log;
unidade sem equivalência segura.

Para cada caso, confira:

schema final;
etapa retomada;
ferramenta chamada ou bloqueada;
quantidade de efeitos externos;
validade da aprovação;
identidade e permissão;
estado no sistema oficial;
evidência da transformação;
destino da pendência;
possibilidade de rollback.

A documentação de versionamento de workflows do Temporal, verificada em 22 de setembro de 2026, descreve abordagens para manter execuções antigas em caminhos compatíveis enquanto novas execuções usam código atualizado. O mecanismo específico depende da plataforma. O princípio operacional é estável: trabalho em andamento precisa de uma rota explícita entre versões.

Preserve rollback sem rebaixar o estado às cegas

Voltar o código não garante que a versão anterior consiga ler o estado novo. Transformações podem ser irreversíveis, campos antigos podem ter sido retirados e efeitos externos podem já ter ocorrido.

Antes da mudança, defina:

se o schema anterior consegue ignorar campos novos;
se haverá escrita dupla temporária;
quais campos não permitem conversão reversa;
onde o snapshot original ficará preservado;
como novas entradas serão bloqueadas;
quem decide drenar, migrar ou cancelar;
como efeitos externos serão reconciliados;
quando o rollback técnico se torna inviável.

Em alguns casos, o retorno seguro consiste em parar novas entradas, manter a versão nova apenas para concluir unidades já migradas e devolver o restante à versão anterior. Isso é mais trabalhoso que trocar uma imagem de deploy, porém preserva a história real do processo.

Monitore a transição por estado e resultado

Acompanhe:

unidades por versão de schema;
migrações concluídas, pendentes e recusadas;
campos sem equivalência;
tempo de migração;
retomadas bem-sucedidas;
tarefas reiniciadas;
aprovações invalidadas;
efeitos duplicados evitados ou produzidos;
unidades presas por etapa;
diferenças entre estado persistido e sistema oficial;
rollback acionado;
dados antigos ainda lidos depois da data de retirada.

O alerta precisa dizer o que aconteceu com o trabalho. “Quatro aprovações antigas perderam vínculo com o destinatário; nenhuma mensagem foi enviada; revisão comercial pendente” orienta melhor que “falha de desserialização”.

Checklist para migrar estado de agentes

[ ] Estado, versão do agente e versão da política possuem identificadores próprios?
[ ] Estados vivos foram inventariados por etapa e consequência?
[ ] Cada alteração foi classificada como adição, renomeação, divisão, restrição, mudança semântica ou remoção?
[ ] Leitores aceitam a janela de versões necessária?
[ ] Transformações são versionadas e idempotentes?
[ ] Campos ambíguos geram pendência em vez de valor inventado?
[ ] Aprovações permanecem ligadas ao objeto e aos parâmetros examinados?
[ ] Drenagem, migração preguiçosa e lote foram comparados?
[ ] Testes retomam tarefas e confirmam efeitos externos?
[ ] Concorrência durante a migração está controlada?
[ ] Logs preservam evidência sem copiar segredos?
[ ] Rollback considera compatibilidade e consequências já produzidas?
[ ] A retirada do schema antigo depende da ausência comprovada de unidades ativas?
[ ] Reconciliação com os sistemas oficiais possui dono?

Estado compatível mantém o trabalho atravessando versões

Agentes empresariais acumulam tarefas, aprovações, checkpoints e efeitos. Esse trabalho continua existindo durante um deploy.

Uma migração segura identifica versões, expande compatibilidade, transforma apenas o que possui equivalência, encaminha ambiguidades e testa a retomada até o sistema oficial. A versão nova entra sem obrigar a empresa a esquecer o que a anterior já fez.

Quando o estado recebe o mesmo cuidado dado ao código, evoluir o agente deixa de ser uma aposta sobre tarefas abertas e vira uma mudança operacional governável.