Habr AI explica como construir um agente de produção com estado durável, etapas e eventos

Para que um agente de IA viva bem em produção, não basta manter tudo na memória do processo: após uma reinicialização, ele precisa lembrar o que exatamente o usuário pediu, qual plano já havia sido montado, quais ferramentas já rodaram e onde a execução parou. Na primeira parte de uma nova análise prática no Habr AI, o autor propõe construir esse estado durável em torno de três entidades básicas (um turno, uma etapa e um evento) e mostra por que, sem elas, cenários longos de agentes viram rapidamente um pipeline opaco e frágil.

O ponto de partida é simples: se o agente guarda o estado apenas em memória, qualquer queda do serviço zera a tarefa. Para uma demo isso é tolerável, mas um agente em produção pode analisar documentos, aguardar a confirmação do usuário e executar uma longa cadeia de ações; por isso, após uma falha, ele precisa se recuperar a partir do banco de dados, e não de fragmentos de um prompt. Como conjunto mínimo de entidades persistentes, o autor lista AgentTurn, AgentPlanItem e AgentEvent, e lembra que ApprovalGrant, SessionContext e BackgroundJob quase inevitavelmente aparecem ao lado delas.

A ideia é que o estado durável descreva não só a resposta final, mas todo o caminho até ela: a solicitação original, o comando normalizado, as flags de confirmação, os status de execução e um possível erro.

Nesse esquema, AgentTurn é o registro completo de um turno do usuário. Ele guarda o identificador da sessão e o turn_id, o texto da mensagem, o comando normalizado e um status de processamento como created, planned, awaiting_approval, running, completed ou failed. É importante que o turno registre também o output_text final e o error, caso a execução tenha falhado.

Isso elimina uma dependência crítica da "memória" do modelo: o backend pode entender a qualquer momento o que aconteceu com a solicitação, mesmo que o processo tenha reiniciado. Em tarefas longas isso é especialmente importante, porque uma solicitação raramente se resume a uma única chamada ao modelo; o mais comum é haver por trás uma cadeia de leitura de arquivos, chamadas a ferramentas, verificação e preparação do resultado.

A camada seguinte é o AgentPlanItem, ou seja, uma etapa individual dentro do turno. Se o usuário pede para analisar um projeto e preparar um relatório, o agente pode dividir a tarefa em várias ações: encontrar documentos, ler os arquivos relevantes, verificar os dados e montar a resposta final. Para cada etapa, propõe-se guardar o próprio item_id, o número de ordem, o nome da ferramenta, os argumentos, o modo de confirmação e o status.

O artigo destaca que os modos safe_readonly, confirm_once e mutating não estão ali de enfeite: eles permitem separar de antemão operações de leitura seguras, ações confirmadas uma única vez e mutações potencialmente perigosas. Com isso, o sistema sabe não apenas que "o agente está fazendo alguma coisa", mas qual ferramenta deve começar em seguida, o que já terminou, o que pode ser repetido e em que ponto a execução travou.

A terceira entidade obrigatória é o AgentEvent, uma linha do tempo do que acontece. Os eventos transformam o turno de uma caixa-preta em um sistema observável. Em vez de um único estado difuso, o frontend pode ler turn_started, tool_started, tool_progress, tool_completed, approval_requested, tool_failed e turn_completed, e então exibir um progresso compreensível.

O exemplo do texto é prosaico e, por isso, útil: o agente inicia collect_documents e encontra 12 documentos; depois, na etapa analyze_documents, informa progresso de 40 de 100 e, em caso de falha, registra um timeout do serviço externo e marca o erro como retryable. Para o usuário, isso significa uma UX decente em vez de um eterno "agente pensando"; para a equipe de desenvolvimento, a possibilidade de depurar o pipeline, fazer auditoria, analisar incidentes e restaurar tarefas após uma reinicialização sem reconstruir o histórico manualmente.

A principal conclusão do material do Habr AI é que um agente de produção em 2026 não é um bom prompt com alguma infraestrutura em volta, mas um sistema com estado e um log de execução. Se o agente não tem estado durável no nível de turno, etapa e evento, ele sobrevive mal a falhas, é opaco para a interface e quase não permite manutenção. Ou seja, a próxima etapa da evolução dos aplicativos de agentes está menos em novos modelos e mais na disciplina da arquitetura de backend: em como registramos o estado, controlamos as confirmações e transformamos o trabalho do modelo em um processo operacional reproduzível.