Habr AI Explicou Como Construir um Agente de Produção com Durable State, Passos e Eventos

Para que agentes de IA funcionem adequadamente em produção, não é suficiente manter tudo na memória do processo: após uma reinicialização, o agente deve lembrar o que exatamente o usuário pediu, qual plano já foi construído, quais ferramentas foram executadas e onde a execução parou. Na primeira parte de uma nova análise prática no Habr AI, o autor propõe construir tal estado persistente em torno de três entidades básicas — turno, passo e evento — e explica por que, sem elas, cenários longos de agentes rapidamente se transformam em um pipeline opaco e frágil. O ponto de partida é simples: se um agente armazena estado apenas na memória, qualquer falha de serviço anula a tarefa.

Para uma demonstração isto é aceitável, mas um agente de produção pode analisar documentos, aguardar confirmação do usuário e executar uma longa cadeia de ações, portanto após uma falha ele precisa se recuperar de um banco de dados, não de fragmentos de um prompt. Como conjunto mínimo de entidades persistentes, o autor lista AgentTurn, AgentPlanItem e AgentEvent, e também observa que ApprovalGrant, SessionContext e BackgroundJob aparecem quase inevitavelmente nas proximidades. A ideia é que o estado persistente descreve não apenas a resposta final, mas todo o caminho até ela: a solicitação original, o comando normalizado, sinalizadores de confirmação, status de execução e possíveis erros.

AgentTurn neste esquema é um registro completo de um turno do usuário. Ele armazena um identificador de sessão e turn_id, texto da mensagem, comando normalizado e status de processamento como created, planned, awaiting_approval, running, completed ou failed. É importante que o turno capture tanto o output_text final quanto o erro, caso a execução tenha falhado.

Isto remove dependência crítica da "memória" do modelo: o backend pode determinar a qualquer momento o que exatamente estava acontecendo com a solicitação, mesmo se o processo foi reiniciado. Para tarefas longas isto é especialmente importante porque uma solicitação única raramente se reduz a uma única chamada do modelo — mais frequentemente envolve uma cadeia de leituras de arquivos, invocações de ferramentas, verificação e preparação de resultado. A próxima camada é AgentPlanItem, ou seja, um passo individual dentro de um turno.

Se um usuário pede para analisar um projeto e preparar um relatório, o agente pode decompor a tarefa em várias ações: encontrar documentos, ler arquivos relevantes, verificar dados e montar a resposta final. Para cada passo é proposto armazenar seu próprio item_id, número ordinal, nome da ferramenta, argumentos, modo de confirmação e status. O artigo enfatiza particularmente que os modos safe_readonly, confirm_once e mutating são necessários não por decoração: eles permitem pré-dividir operações de leitura seguras, ações de aprovação única e mutações potencialmente perigosas.

Como resultado, o sistema sabe não apenas "o agente está fazendo algo," mas qual ferramenta exata deve iniciar a seguir, o que já foi concluído, o que pode ser retentado e onde a execução ficou presa. A terceira entidade obrigatória é AgentEvent, ou seja, uma linha do tempo do que está acontecendo. São precisamente os eventos que transformam um turno de uma caixa preta em um sistema observável.

Em vez de um único estado vago, o frontend pode ler turn_started, tool_started, tool_progress, tool_completed, approval_requested, tool_failed e turn_completed, e então exibir progresso claro. O exemplo do texto é fundamentado e, portanto, útil: o agente executa collect_documents, encontra 12 documentos, depois no passo analyze_documents relata progresso 40 de 100, e em caso de falha escreve timeout de serviço externo e marca o erro como retryable. Para o usuário isto significa UX normal em vez de infinito "o agente está pensando," e para o time de desenvolvimento — a capacidade de depurar o pipeline, conduzir auditorias, analisar incidentes e recuperar tarefas após reinicialização sem reconstrução manual do histórico.

A conclusão principal do material do Habr AI é que um agente de produção em 2026 não é um prompt da sorte com um wrapper, mas um sistema stateful com um diário de execução. Se um agente não tem estado persistente no nível de turno, passo e evento, ele sobrevive mal a falhas, é opaco para a interface e é quase impossível de suportar. O que significa que o próximo estágio de evolução de aplicações de agentes está menos em novos modelos do que em disciplina de arquitetura backend: em como capturamos estado, controlamos aprovações e transformamos o trabalho do modelo em um processo operacional reproduzível.