GBR: ADR-0001 Ciclo Cognitivo de Agentes Autônomos via Máquina de Estados Finita (ReAct FSM)

• *Status:* Aceito
• *Data:* 2026-05-01

*Contexto:*

Implementações tradicionais de agentes LLM em Python (como o framework base claw-code) gerenciam o ciclo de "Raciocínio e Ação" (ReAct) utilizando loops imperativos (while True) e callbacks assíncronos mutáveis. Essa "entropia cognitiva" gera estados inconsistentes se a API do modelo atirar um erro de timeout ou se a rede oscilar, corrompendo o fluxo lógico da IA.

*Decisão:*

1. *Transmutação Funcional (Sistemas Lúcidos):* A orquestração do Agente (agent_loop.gleam) foi reescrita no Gleam como uma Máquina de Estados Finita (FSM) rigorosa encapsulada num Ator OTP.
2. *Tipagem Estrita de Estágios Cognitivos:* O estado de raciocínio da IA foi cristalizado no tipo CognitiveState com transições explícitas: Idle $\rightarrow$ Thinking $\rightarrow$ UsingTool $\rightarrow$ Answering.
3. *Isolamento I/O Bound:* Chamadas à API HTTP dos LLMs ou execuções pesadas no DuckDB são disparadas como mensagens assíncronas (process.send). O Ator transiciona de estado e libera o scheduler da BEAM para processar a UI do terminal de forma reativa.

*Consequências:*

• *Positivas:* Falhas de rede ou alucinações de formato JSON nas Tool Calls do LLM não derrubam a aplicação. O Ator intercepta o erro na caixa de correio, sinaliza a anomalia e retorna ao estado Thinking instruindo a IA a corrigir seu comportamento, tudo de forma matematicamente verificável no tempo de compilação.
• *Negativas/Riscos:* A estruturação estrita da FSM torna a injeção de fluxos arbitrariamente assíncronos de IA ligeiramente mais verbosa, requerendo o mapeamento exaustivo de todos os Pattern Matchings para novas ferramentas inseridas no sistema.