Agent state/persistence/approval
Você vai simular um reembolso interrompido para revisão humana e retomado sem duplicação. Salve o código da resolução em estado.cjs e execute com Node.js. Os valores e recibos são fictícios; nenhuma transação externa será feita. A entrega inclui a proposta serializada, a decisão de aprovação e o registro observado em duas execuções da mesma operação.
A dificuldade deste laboratório está em posicionar as falhas. Parar antes de executar é simples; parar depois do efeito e antes do checkpoint cria uma situação ambígua. Vamos usar a simulação para identificar essa janela e documentar qual mecanismo real deverá fechá-la. Você também verificará que alterar o valor ou a revisão remove a validade da aprovação antiga.
AgentesAo terminar esta aula
- A evidência de idempotência é um único efeito para a mesma operação.
- Uma retomada deve validar novamente a decisão vinculada à proposta.
- Persistência local e execução remota exigem uma estratégia de reconciliação.
Antes de continuar: Leitura: Agent state/persistence/approval
Desenhe a proposta que o humano verá
FundamentosRegistre uma solicitação R7 com revisão 1, pedido P7 e valor de 120 reais. Descreva em uma frase a consequência: emitir um reembolso, e não somente preparar um rascunho. O exemplo verifica revisão e decisão, mas você deve acrescentar ao contrato quem tem direito de aprovar e como o executor autentica essa pessoa. Coloque o valor e o destinatário na tela de aprovação. Um resumo genérico como “continuar tarefa” não permite avaliar o efeito que está prestes a acontecer.
Execute a proposta sem a decisão. O programa deve recusar antes de registrar um recibo. Agora crie a decisão aprovada para a revisão atual e execute. Capture a chave e o recibo retornados. Repita o comando e compare os valores. A igualdade do recibo indica que o segundo comando consultou o resultado existente. Para investigar melhor, acrescente um contador à função que simula o pagamento: ele deve aumentar apenas na primeira execução da chave. O contador é uma evidência mais forte que duas mensagens iguais.
Teste a ligação entre versão e decisão
AvaliaçãoAltere a revisão da proposta para 2 e conserve a aprovação da revisão 1. A execução deve parar por aprovação inválida. Justifique o motivo: uma revisão representa uma proposta potencialmente diferente, e o autorizador ainda não viu essa mudança. Em uma aplicação real, modificar apenas um campo decorativo pode seguir outra política, mas alterações de valor, destinatário ou ação exigem uma nova verificação. Escreva essa regra explicitamente para não deixar ao modelo a interpretação de quais diferenças são relevantes.
Serialize a proposta e a decisão com JSON.stringify e reconstrua com JSON.parse. Confirme que a validação continua funcionando sem depender de objetos com comportamento escondido. Isso prepara a persistência, mas não prova durabilidade. Em um teste real, o arquivo ou banco precisa ser escrito antes de encerrar o processo, e o leitor precisa detectar dados incompletos ou versão de esquema incompatível. Registre a versão do esquema no seu desenho, mesmo que o exemplo didático tenha apenas uma estrutura simples.
Investigue a janela de resultado desconhecido
FundamentosSimule um timeout depois de inserir o recibo no registro. Do ponto de vista do chamador, ocorreu um erro; do ponto de vista do sistema de efeitos, a operação foi concluída. Na nova tentativa, consulte pela mesma chave. Se você gerar uma chave nova a cada retry, a simulação emitirá outro recibo e perderá a defesa contra repetição. Essa experiência explica por que o identificador da tentativa não deve ser confundido com o identificador estável da operação. Os dois podem existir, mas cumprem papéis distintos.
Apague o mapa e repita a chamada para representar a perda de memória após reinício. A defesa local desaparece. Documente então a correção necessária: banco com unicidade e executor ou serviço externo que aceite a chave de idempotência. Se não existe tal suporte, o workflow deve consultar e reconciliar antes de repetir efeitos incertos. Não descreva o mapa como uma solução pronta de produção. O aprendizado é reconhecer a garantia mínima e perceber exatamente onde ela deixa de valer.
Prepare uma retomada observável
FundamentosMonte uma tabela de eventos com proposta criada, decisão registrada, efeito confirmado e resultado entregue. Guarde identificadores e status, evitando conteúdo financeiro desnecessário em logs comuns. Para background, acrescente um identificador de trabalho que permita consultar se ele está aguardando humano, executando ou concluído. Descreva cancelamento antes do efeito e compensação depois dele como operações diferentes. Sua conclusão deve citar quais cenários foram executados localmente e quais dependem de testar o armazenamento e o serviço real.
Exercício aplicado
Uma solicitação R7 de reembolso aguarda revisão humana. O processo poderá ser reiniciado e o comando de execução poderá chegar duas vezes. A proposta alterada não pode reutilizar uma decisão antiga.
- Execute sem aprovação e verifique a ausência de efeito.
- Aprove a revisão 1, execute duas vezes e compare recibo e tamanho do registro.
- Mude a revisão para 2 conservando a decisão antiga e confirme o bloqueio.
- Simule timeout depois do efeito e explique como consultar a mesma chave antes de repetir.
Abrir resolução comentada
A solução usa a revisão para bloquear decisões antigas e a chave R7:1 para reconhecer repetição. Os dois retornos nominais devem conter o mesmo recibo e o mapa deve conter uma única entrada. O caso sem aprovação termina antes da criação de qualquer entrada. Assim, os sinais de segurança são contagem de efeitos e posição da interrupção, não somente o texto do erro.
Ao simular uma queda que destrói o mapa, você demonstra uma limitação real do protótipo. A resolução de produção precisa transferir esse registro a um componente durável e atômico. Para o relatório, desenhe a sequência de consulta, execução e confirmação, destacando o ponto em que um timeout gera resultado desconhecido.
const efeitos = new Map();
function executar(proposta, decisao) {
if (!decisao || !decisao.aprovado || decisao.revisao !== proposta.revisao) throw new Error('aprovacao invalida');
const chave = proposta.id + ':' + proposta.revisao;
if (efeitos.has(chave)) return efeitos.get(chave);
const recibo = {chave,valor:proposta.valor,status:'simulado'};
efeitos.set(chave,recibo);
return recibo;
}
const proposta={id:'R7',revisao:1,pedido:'P7',valor:120};
const decisao={revisao:1,aprovado:true};
console.log(executar(proposta,decisao),executar(proposta,decisao));
console.log('efeitos',efeitos.size);
try { executar({...proposta,revisao:2},decisao); } catch(e) { console.log(e.message); }Como conferir seu resultado
- A rejeição ou ausência de aprovação não cria recibo.
- Duas execuções da mesma operação possuem um único recibo.
- A revisão alterada invalida a aprovação anterior.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Vincular aprovação à proposta.
- Separar efeito e resultado confirmado.
Proposta Q3 revisão 2 quantidade 1 tem decisão correspondente. Chegam recusa, proposta alterada para quantidade 2 e duas execuções nominais. Defina resultados e requisito para reinício.
Conferir raciocínio e critérios de domínio
Recusa retorna recusado; quantidade 2 viola o snapshot e não produz efeito antes de nova aprovação.
As duas execuções legítimas retornam o mesmo recibo Q3:2 e mantêm um efeito.
Map só demonstra processo único. Um reinício exige ledger durável e consulta do efeito; sem isso a recuperação fica não comprovada.
Evidências para autoavaliação ou revisão por pares
- Recusa e proposta alterada: Recusa retorna recusado; quantidade 2 viola o snapshot e não produz efeito antes de nova aprovação.
- Replay nominal: As duas execuções legítimas retornam o mesmo recibo Q3:2 e mantêm um efeito.
- Durabilidade: Map só demonstra processo único. Um reinício exige ledger durável e consulta do efeito; sem isso a recuperação fica não comprovada.
Um erro frequente
Background dispensa supervisão.
Trabalho em background continua limitado, observável e supervisionado.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Checkpoint garante efeito remoto exatamente uma vez?
Não. A operação externa precisa de idempotência ou reconciliação.
Uma queda pode acontecer entre o efeito e o salvamento do checkpoint.
2. O que a aprovação deve identificar?
A ação concreta, seus argumentos relevantes e a revisão.
Uma decisão genérica não autoriza mudanças posteriores de valor ou destinatário.
3. Timeout prova que o reembolso falhou?
Não. O efeito pode ter acontecido sem a resposta chegar.
Consulte o resultado pela identidade estável antes de repetir.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Results and state
OpenAI • consulta: 2026-10-06
OpenAIResultados, estado retomável e continuidade de conversas.
Limites: Serializar estado de execução e persistir sessões são escolhas diferentes; armazenamento é responsabilidade da aplicação.
- Graph API overview
LangChain • consulta: 2026-10-06
APIsStateGraph, nós, arestas, condicionais e reducers para combinar atualizações.
Limites: Reducers resolvem combinação de dados; conflitos semânticos de agentes precisam de regra editorial/negocial explícita.
- Guardrails and human review
OpenAI • consulta: 2026-10-06
OpenAISegurançaGuardrails de entrada, saída e ferramentas; interrupções de aprovação e retomada.
Limites: Guardrails de entrada só no primeiro agente e de saída no agente final; validação não substitui autorização.
- Persistence
LangChain • consulta: 2026-10-06
FundamentosCheckpointer de estado por thread versus store de memória entre threads.
Limites: InMemorySaver é demonstrativo; usar backend durável para sobreviver a reinícios.
- Checkpointers
LangChain • consulta: 2026-10-06
FundamentosCheckpoints, threads, retomada e tolerância a falhas.
Limites: Checkpoint de estado não torna ações externas exatamente uma vez; planejar idempotência.
- Background mode
OpenAI • consulta: 2026-10-06
OpenAIExecução assíncrona de uma resposta, consulta de status e cancelamento.
Limites: Background mode da Responses API não é uma fila durável de jobs nem persistência completa de workflows.
- Agent Runtime
Google ADK • consulta: 2026-10-06
Google ADKAgentesadk web, run e api_server; referências de event loop, retomada e execução assíncrona.
Limites: Página organiza formas de execução; não é garantia de durabilidade de uma implantação.