Agent state/persistence/approval
Um agente que espera aprovação precisa sobreviver ao intervalo entre propor uma ação e executá-la. Imagine uma solicitação de reembolso preparada na sexta-feira e aprovada na segunda. A conversa pode ter mudado, o processo pode ter reiniciado e o valor autorizado pode já não corresponder ao pedido. Nesta aula, vamos separar estado de conversa, estado operacional e registro de efeitos. Essa separação é o ponto de partida para persistência, retomada e execução em segundo plano que não produzam ações duplicadas.
O exemplo representa uma solicitação como dados serializáveis, com uma revisão e um status. Ele simula a aprovação e um registro de efeitos usando estruturas locais. Você verá o que esse exemplo prova e o que exige infraestrutura adicional: armazenamento durável, transações, concorrência, autorização real e recuperação depois de uma queda. A aprovação é uma decisão sobre uma proposta concreta, com identidade e validade, e não uma licença permanente para tudo que o agente decidir fazer depois.
JavaScriptAgentesAo terminar esta aula
- Conversa, etapa operacional e registro de efeitos têm responsabilidades diferentes.
- Uma aprovação precisa identificar a proposta concreta e a revisão autorizada.
- Retomada exige reconhecer efeitos anteriores e tratar resultados desconhecidos.
Antes de continuar: Laboratório: Agent loop
Três estados que costumam ser confundidos
FundamentosO estado de conversa conserva mensagens úteis para continuar uma interação. O estado operacional registra em que etapa está o trabalho: proposta preparada, aguardando aprovação, execução iniciada ou concluída. O registro de efeitos informa o que já aconteceu fora do processo, como a emissão de um reembolso. Esses estados têm necessidades diferentes. A conversa pode ser resumida; um recibo de reembolso não pode desaparecer no resumo. Uma aplicação que reconstrói o trabalho apenas a partir do texto final perde as evidências necessárias para saber se deve executar ou apenas consultar um efeito existente.
Persistência significa guardar dados além da memória de uma execução. Um checkpoint descreve uma posição recuperável, mas não transforma automaticamente sistemas externos em participantes da mesma transação. Se o pagamento foi emitido e o processo caiu antes de salvar a conclusão, o checkpoint ainda pode dizer “executar pagamento”. É por isso que retomada precisa de uma identidade estável para o efeito e de consulta ao sistema responsável. A documentação de persistência do LangGraph discute checkpoints e recuperação; a aplicação ainda define a semântica dos efeitos e os limites de retenção dos dados.
A aprovação pertence à proposta
FundamentosUma proposta de reembolso contém pedido, valor, moeda, destinatário e revisão. O aprovador deve ver esses campos e a consequência da ação. Se qualquer campo relevante mudar, a aprovação anterior precisa ser invalidada ou reavaliada segundo a política. No exemplo, a revisão funciona como uma ligação simples entre proposta e decisão. Em produção, o registro também precisa da identidade autenticada do aprovador, do horário, da política aplicada e, quando necessário, de expiração. A palavra “aprovado” em uma mensagem não constitui uma autorização verificável.
Guardrails podem validar entradas e saídas ou interromper ações, mas não substituem os controles de acesso dos serviços. Uma sessão não deve escolher livremente qual tenant consultar, e o modelo não deve inventar a identidade que será usada no pagamento. A autorização deriva da aplicação e da credencial adequada. Se o aprovador recusar, a execução deve continuar como rejeitada, sem chamar a ferramenta de efeito. Se a aprovação expirar, o sistema precisa mostrar a proposta novamente ou encerrar. Tratar ausência de resposta como aceite cria uma ação sem decisão correspondente.
Retomar com uma chave estável
FundamentosO código mantém um mapa de efeitos por chave. Ao executar duas vezes a mesma proposta aprovada, a segunda chamada devolve o recibo já existente. Isso demonstra idempotência dentro do processo. A chave combina identidade da solicitação e revisão: uma aprovação de uma revisão não libera automaticamente outra. Ao retomar, o runtime primeiro verifica a proposta e depois consulta o registro. Essa ordem impede tanto o uso de aprovação obsoleta quanto a repetição de um efeito já confirmado. A chave deve nascer antes da primeira tentativa e permanecer igual nas tentativas seguintes.
O mapa em memória não é durável e não é seguro sob múltiplos workers. Dois processos podem observar a ausência da chave simultaneamente e executar o mesmo pagamento. A implementação real requer uma restrição de unicidade e uma operação atômica, ou uma API externa que ofereça idempotência com a mesma chave. Uma transação local não cancela um pagamento remoto que já ocorreu. Depois de um timeout, marque o resultado como desconhecido e consulte o efeito pelo identificador antes de repetir; falha de rede não significa necessariamente falha da operação.
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); }Background não elimina supervisão
FundamentosExecução em segundo plano desacopla a duração do trabalho da conexão do usuário. Ela permite polling ou notificação de conclusão conforme a plataforma, mas não oferece por si só uma fila durável para todo o workflow, uma aprovação externa ou uma política de retry. Na aplicação, você precisa de estados consultáveis, prazo total, cancelamento e proprietário do trabalho. Um usuário que fecha a aba não deveria deixar de saber se a solicitação existe. Um cancelamento também precisa distinguir trabalho ainda não iniciado de efeito já consumado, pois o segundo pode exigir compensação.
Avalie retomadas em quatro pontos: antes da aprovação, após aprovar, após executar o efeito e antes de salvar a conclusão. Inclua duas decisões concorrentes e uma aprovação de revisão antiga. Observe número de efeitos, status final e ligação entre decisão e proposta. O objetivo não é prometer execução exatamente uma vez em qualquer ambiente; é construir uma semântica que reconheça repetições e reconcilie resultados incertos. No documento de arquitetura, declare o armazenamento, a retenção e as garantias que realmente existem, além das dependências necessárias para alcançar outras.
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 proposta inicia aguardando aprovação e não pode ser executada. Depois de uma decisão ligada à revisão atual, a execução usa uma chave estável e consulta o registro de efeitos. O segundo comando de execução retorna o mesmo recibo, de modo que a repetição não emite outro efeito na simulação. Para demonstrar aprovação obsoleta, altere a revisão da proposta sem alterar a decisão; a validação bloqueia a execução antes de acessar o mapa.
O limite importante é o armazenamento em memória. Persistir apenas a proposta em JSON não resolveria a corrida entre workers nem a janela de queda depois do efeito externo. Uma implementação real deve combinar unicidade, autorização no executor e reconciliação com o sistema financeiro. A resolução local prepara essas decisões, sem fingir que as garantias já foram implantadas.
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 de cancelamento Q3 revisão 2 aprovada muda para revisão 3. Serviço pode executar e perder resposta. Defina estados.
Conferir raciocínio e critérios de domínio
A decisão revisão 2 não autoriza revisão 3; a operação alterada permanece aguardando nova aprovação, não executável.
A intenção corresponde à revisão e aos argumentos aprovados; texto do usuário não cria autorização confiável.
Se o serviço executou mas a resposta se perdeu, o estado é desconhecido. A decisão é consultar o recibo da intenção antes de qualquer repetição.
Evidências para autoavaliação ou revisão por pares
- Aprovação: A decisão revisão 2 não autoriza revisão 3; a operação alterada permanece aguardando nova aprovação, não executável.
- Identidade: A intenção corresponde à revisão e aos argumentos aprovados; texto do usuário não cria autorização confiável.
- Recuperação: Se o serviço executou mas a resposta se perdeu, o estado é desconhecido. A decisão é consultar o recibo da intenção antes de qualquer repetição.
Um erro frequente
Aprovação antiga vale para proposta nova.
Aprovação deve coincidir com a proposta vigente.
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.