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:

1. drenar na versão antiga: deixa a unidade terminar no código que a criou;
2. migrar automaticamente: transforma estado quando a equivalência é determinística;
3. migrar com revisão: prepara a conversão e pede decisão para campos ambíguos;
4. 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.

EXEMPLO SINTÉTICO — FICHA DE CONVERSÃO PARA REVISÃO
Entrada do exemplo: schema_version=1; status=aguardando; acao_proposta="Enviar resumo para Ana"; aprovado=true.
Preservar: texto original, estado de origem e evidência disponível da aprovação.
Não completar por inferência:
- recipient_id: não confirmado; consultar o contato na fonte oficial.
- channel: não confirmado; confirmar o canal autorizado.
- approved_action_hash: sem vínculo demonstrado com os parâmetros novos.
- expires_at: validade não estabelecida; não fabricar data.
Tipo provável: envio de resumo; reconhecer intenção não autoriza executar.
Destino da transformação: exige_revisao. O status antigo não comprova prontidão para execução.
Revisor: confirmar qual Ana, identificador, canal, conteúdo, política e objeto que a pessoa aprovou. Se o efeito ou os parâmetros mudaram, obter nova aprovação.
Antes da retomada: conferir no sistema oficial se já houve efeito; manter chave de idempotência e trilha da transformação.
Saída desta ficha: lacunas explícitas e decisão pendente, sem preencher o JSON novo como se a equivalência estivesse provada.

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:

1. schema final;
2. etapa retomada;
3. ferramenta chamada ou bloqueada;
4. quantidade de efeitos externos;
5. validade da aprovação;
6. identidade e permissão;
7. estado no sistema oficial;
8. evidência da transformação;
9. destino da pendência;
10. 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.