Mini React Agent

Mini React Agent: il loop di un agente LLM, scritto piccolo e leggibile

mini-react-agent è un progetto open source firmato Innova: un agente ReAct minimale in Python — think → act → observe → repeat — costruito per essere leggibile in una seduta sola. Circa 200 righe nel core, zero dipendenze runtime, licenza MIT. Si descrive così, in una riga: “A tiny, readable ReAct agent — think → act → observe — with pluggable tools. Runs fully offline, no API key required”.

Nasce dalla stessa esigenza che ha portato a LLM Eval Harness: capire davvero — e far capire — cosa succede sotto il cofano di un sistema LLM, senza il rumore di framework enormi che ne nascondono il funzionamento. Un agente è solo un ciclo. Vale la pena vederlo per quello che è.

Cosa fa mini-react-agent

Implementa il pattern ReAct in modo pulito: il modello pensa (Thought), sceglie un tool da invocare (Action), riceve un’osservazione reale (Observation), e ripete finché non produce una risposta finale o esaurisce il budget di step.

L’output di una run di esempio dice tutto:

Task: Trova la capitale d'Italia, calcola 144 / 12 e conta le parole in 'Creating Digital Experiences'.
────────────────────────────────────────────────────────
1. Thought: Prima cerco la capitale d'Italia.
   Action: search("capitale d'Italia")
   Observation: Roma è la capitale d'Italia.
2. Thought: Ora calcolo 144 diviso 12.
   Action: calculator('144 / 12')
   Observation: 12
3. Thought: Infine conto le parole nella frase.
   Action: word_count('Creating Digital Experiences')
   Observation: 3
4. Thought: Ho tutti e tre i risultati.
────────────────────────────────────────────────────────
Final Answer: La capitale d'Italia è Roma, 144 / 12 = 12, e 'Creating Digital Experiences' ha 3 parole.

I tool e le observation sono eseguiti per davvero: solo il “pensiero” del modello, in modalità demo, viene replayato da uno script registrato, così la run è deterministica e gira anche senza API key.

Tre tool built-in, registry plug-and-play

Il framework arriva con tre tool pronti all’uso:

• calculator — valutatore aritmetico sicuro basato su AST (niente eval() selvaggio)
• search — knowledge base offline per la demo
• word_count — conteggio parole su una stringa

Aggiungerne uno nuovo è una classe da poche righe: si estende Tool, si dichiara name e description (è quella che il modello legge per decidere quando invocare il tool), si implementa run(). Il dispatcher fa il resto.

Backend intercambiabili, demo offline

Una sola interfaccia — complete() — astrae i backend sottostanti. Il pacchetto include tre implementazioni: replay (deterministico, offline, perfetto per CI e per chi vuole vedere il loop senza pagare token), OpenAI e Anthropic. I backend reali usano correttamente la stop sequence su Observation:, così il modello non può mai allucinare la propria osservazione.

È il pezzo che spesso manca nei tutorial: ReAct non è solo “metti tutto nel prompt e iterali” — è anche la disciplina di interrompere il modello al momento giusto, eseguire il tool nel mondo reale, e rifornirlo con l’observation autentica. Mini-React-Agent lo fa nei modi corretti, e lo mostra in chiaro nel codice.

UI web live per vedere il ragionamento

Il comando mini-agent serve avvia un piccolo server Flask che streamma in tempo reale (Server-Sent Events) ogni step Thought → Action → Observation nel browser. Si sceglie il backend (demo offline o un modello reale), si scrive un task, e si guarda l’agente ragionare passo dopo passo — con la grafica del brand Innova.

È lo strumento perfetto per due scenari: onboarding di un nuovo sviluppatore sul pattern ReAct (in 30 secondi capisce cosa fa un agente), e demo a un cliente non tecnico che vuole capire come ragiona un’AI invece di vedere solo la risposta finale.

Perché Innova ha costruito questo strumento

Sempre più progetti che consegniamo includono una forma di agente — un chatbot che decide quale tool chiamare, un workflow di automazione che invoca API esterne sulla base di un prompt, un assistente che orchestra ricerca e calcolo. Avere una baseline minimale, leggibile e nostra ci permette di insegnare il pattern agli sviluppatori junior, di prototipare velocemente sopra un loop di cui conosciamo ogni riga, e di non dipendere da framework opachi quando il debug si fa serio.

Rilasciarlo open source con licenza MIT è coerente con il resto della nostra produzione developer-facing: il codice che usiamo per capire e prototipare è lo stesso che condividiamo con la community.

A chi serve davvero

A chi sta imparando come funziona un agente LLM e vuole vedere il loop in chiaro, senza astrazioni inutili. A chi prototipa un sistema agentico e vuole partire da una base solida invece che da un framework di mille righe. A chi tiene un corso o un workshop sull’AI applicata e cerca un esempio concreto, leggibile e modificabile in classe.

Roadmap aperta

I prossimi passi puntano a estendere lo strumento mantenendone la leggibilità: nuovi tool (HTTP fetch, sandbox Python REPL, ricerca web reale), action multi-tool per step, budgeting di token con cost reporting. Lo sviluppo è pubblico, le pull request benvenute.

L’AI come strumento, non come marketing

L’AI applicata, fatta seriamente, è meno spettacolare e molto più ingegneristica di quanto sembri dai post di LinkedIn. mini-react-agent è una piccola conferma di questo: un loop, tre tool, un parser, e una disciplina chiara su quando interrompere il modello. Tutto qui. Ma è esattamente questo “tutto qui” che permette di costruirci sopra prodotti che funzionano davvero.