Gestione dei problemi

Per semplificare l'individuazione dei problemi, il Tree Agent offre una serie di strumenti preventivi e correttivi. In fase di progettazione sono effettuati dei controlli come: l'indentazione nelle callback, il completamento di tutti campi required oppure il collegamento corretto tra i nodi. A livello di interfaccia, prima di permettere la compilazione sono mostrati in un elenco tutti gli eventuali avvisi di errori.

A livello di sviluppo invece, l'esecuzione di ogni nodo produrrà degli eventi visualizzabili a fianco della chat in modalità debug, tramite questo strumento sarà quindi possibile seguire passo dopo passo il flusso eseguito per arrivare alla risposta, con tutti i relativi dati come i prompt e le risposte intermedie. Inoltre, nella stessa finestra di debug sarà possibile aggiungere manualmente degli eventi extra di LOGGING utilizzando il metodo log() dentro le callback dei nodi: in questo caso, il contenuto passato come argomento sarà mostrato come dato associato all'evento contestualmente generato.

Reach anchor

Durante lo step explore, a volte può capitare che non venga identificata alcuna informazione utile nei chunk disponibili. Questo non accade esclusivamente quando l'informazione è assente nell'intero albero, ma anche quando non è presente nel solo sottoalbero definito a partire dal nodo attuale. Infatti, la ricerca si concentra sempre sui nodi sottostanti il nodo attuale, e in mancanza di una callback after esplicita, non si sale mai verso la root; l'unica eccezione a questa regola è il meccanismo di reach_anchor che viene avviato in queste circostanze:

1. Quando si finisce durante lo step explore in un nodo senza nodi figli, e quel nodo è stato anche l’ultimo eseguito;
2. Quando si finisce durante lo step explore in un nodo in cui, seppure ci siano dei nodi figli, in nessun chunk al loro interno raggiunge il livello minimo di similarità rispetto alla richiesta dell’utente, e quel nodo è stato anche l’ultimo eseguito;
3. Quando esplicitamente dentro una callback after si restituisce il parametro outcome = Outcome.FAILURE.

Quando si attiva il meccanismo di reach_anchor si sale un nodo genitore alla volta finchè non si incontra un nodo con proprietà is_anchor = True. Una volta raggiunto, viene ripreso lo step di explore a partire da tale nodo;

Quando si attiva il reach_anchor viene anche incrementato il fail_counter di 1. Questo contatore viene controllato ad ogni iterazione che comprende l'esecuzione di uno step qualsiasi, e se raggiunge il valore 3 viene lanciata un eccezione di tipo AttemptsError che innesca l'esecuzione della fallback. Grazie a questo sistema, insieme ad altri mechanisi, si evitano eventuali loop.

informazioni

Se il fail_counter raggiunge il valore 4, allora viene generata un eccezione di tipo AttemptsError che non chiama la fallback e quindi interrompe immediatamente l'esecuzione

Ogni volta che si attiva il reach_anchor nei casi 1 e 2, viene anche aggiornata una lista chiamata black_list che può contenere sia chunk_id che node_id. Nello specifico, quando si verificano questi due casi, tutto il sottoalbero del nodo corrente viene aggiunto alla black_list. In fase di ricerca, tutti i chunk riportati nella black_list, oppure discendenti di uno dei nodi della black_list, sono ignorati in modo da evitare di tornare su di essi per rispondere alla richiesta corrente dell'utente.

informazioni

Sia il failure counter che la black_list, ogni volta che viene prodotta una risposta per l'utente, e quindi si conclude l'interazione, sono resettati.

Identificazione degli loop

Per prevenire il verificarsi di loop durante un'interazione, oltre al fail_counter, il framework adotta altre due strategie complementari.

La prima agisce a livello di trasferimento tra nodi: ogni volta che una callback after esegue un trasferimento esplicito tramite node_target, il framework controlla se lo stesso trasferimento — stesso nodo di partenza, stesso nodo di destinazione, stesso session_state — si è già verificato in precedenza durante la medesima interazione. Se è così, viene generato un LoopError.

La seconda agisce a livello globale, tramite un contatore che si incrementa ad ogni step di esplorazione e ad ogni esecuzione di nodo: al raggiungimento di 200 esecuzioni, viene anch'esso generato un LoopError.

In entrambi i casi, il LoopError viene normalmente intercettato e gestito dalla callback fallback. Esistono però due soglie di sicurezza, tenute separate dai meccanismi precedenti, oltre le quali l'esecuzione viene invece interrotta con un'eccezione: il contatore globale che raggiunge 250 esecuzioni, oppure lo stesso trasferimento tra due nodi (a parità di session_state) che si ripete per la terza volta.

Errori specifici

Init Error

Quando si verifica: Quando viene inizializzato la root o un componente e la funzione init ha un errore. Infatti, prima dell'esecuzione di ciascuna callback, seguendo un approccio lazy, se non già fatto, viene inizializzato il componente che contiene il nodo corrente, oppure la root se il nodo non è contenuto in alcun componente.

Messaggio di errore:

Init della root

"Failed to inizialize root: {error_details}."

Init di un componente

"Failed to inizialize component with ID {component_id}: {error_details}"

Cause comuni:

• Un errore durante l'esecuzione dell'init

Come risolvere:

• Apri l'init del componente indicato, oppure la root

Callback Error

Quando si verifica: Durante l'esecuzione di una callback in un nodo o componente.

Messaggio di errore:

"Error while executing callback {callback_type} in node {node_name} [inside component {component_id}]. Error message: {error_details}"

Cause comuni:

• Errori di sintassi nel codice della callback
• Riferimenti a variabili non definite
• Eccezioni non gestite nel codice personalizzato

Come risolvere:

• Verifica il codice della callback indicata
• Controlla che tutte le variabili utilizzate siano definite
• Aggiungi gestione degli errori nel tuo codice personalizzato

Node Target Error

Quando si verifica: Quando si tenta di spostarsi verso un nodo non valido o inesistente.

Messaggi di errore:

Nodo inesistente

"Invalid node target in {node_name}. You're referencing the id of a non-existent node inside a {callback_type}."

Cause comuni:

• ID del nodo di destinazione inesistente

Come risolvere:

• Assicurati di passare l'id di un nodo tramite links
• Controlla la configurazione di fallback o after del nodo

Nodo target di tipo componente

"Invalid node target in {node_name}. You’re probably trying to refer to a component inside a {callback_type}."

Cause comuni:

• Riferimento a un componente invece che a un nodo

Come risolvere:

• Assicurati di passare l'id di un nodo tramite links e di navigare fino ad un nodo valido: non sono ammessi: componenti, head, tail e root
• Controlla la configurazione di fallback o after del nodo

Nodo target di tipo non valido

"Invalid node target in {node_name}. You’re providing an invalid type inside a {callback_type}."

Cause comuni:

• Tipo di nodo target non valido

Come risolvere:

• Assicurati di passare l'id di un nodo tramite links
• Controlla la configurazione di fallback o after del nodo

Step non valido

"Invalid step returned by after callback in node {node_id}. The after callback must return an object where step is either Step.EXPLORE or Step.BEFORE. If step is omitted, it defaults to Step.EXPLORE. Received: {step}."

Cause comuni:

• Si è specificato uno step nella callback after diverso da BEFORE e EXPLORE

Come risolvere:

• Modifica l'output nella callback after nel nodo specificato

Loop Error

Quando si verifica: Quando viene rilevato un ciclo infinito nell'esecuzione del tree.

Tipi di loop:

Loop per ripetizione

"Error while attempting to reach node {target_node} from node {starting_node} within the same interaction and without modifying the session_state."

Causa: Si tenta di raggiungere lo stesso nodo più volte nella stessa interazione senza modificare lo stato.

Limite operazioni

"Error, the iteration reached an excessively high number of operations and was therefore interrupted."

Causa: Il numero di operazioni ha superato il limite massimo consentito.

Come risolvere:

• Assicurati che il session_state venga modificato prima di ritornare allo stesso nodo
• Rivedi la logica di navigazione tra i nodi per evitare cicli
• Aggiungi condizioni di uscita appropriate

Memory Agent Error

Quando si verifica: Durante l'esecuzione del Memory Agent.

Messaggio di errore:

"Error while executing the Memory Agent. Error: {error_details}"

Cause comuni:

• Configurazione errata del Memory Agent
• Problemi di connessione o autenticazione
• Errori nel processamento della memoria

Come risolvere:

• Verifica la configurazione del Memory Agent
• Controlla le credenziali e le connessioni
• Esamina i log per dettagli specifici sull'errore

Reach Anchor Error

Quando si verifica: Durante il tentativo di raggiungere un nodo anchor quando nessun nodo ascendente valido è disponibile.

Messaggio di errore:

"Error while reaching the anchor."

Nota: Questo errore teoricamente non dovrebbe mai verificarsi in condizioni normali.

Come risolvere:

• Contatta il supporto

Fallback Error

Quando si verifica: Quando un fallback punta a un nodo non valido.

Messaggio di errore:

"Error, fallback targeting on an invalid node. Consider addressing a node with an output."

Causa: Il nodo di fallback specificato non ha un output valido.

Come risolvere:

• Assicurati che il nodo di destinazione del fallback abbia un output configurato
• Verifica che il nodo di destinazione sia del tipo appropriato

Missing Callback Error

Quando si verifica: Quando una callback obbligatoria non è definita in un nodo.

Messaggio di errore:

"Error: The {callback_type} callback is required, but it is not defined in node {node_name}."

Cause comuni:

• Callback richiesta non implementata
• Configurazione incompleta del nodo

Come risolvere:

• Implementa la callback richiesta nel nodo indicato
• Consulta la documentazione per verificare quali callback sono obbligatorie per il tipo di nodo

Callback Output Error

Quando si verifica: Quando una callback restituisce un output che ha un tipo diverso da quello previsto.

Messaggio di errore:

"he output produced by {callback_type} callback in node {node_name} is not valid."

Cause comuni:

• Callback restituisce un output che non corrisponde a quello richiesto nella firma

Come risolvere:

• Consulta la documentazione per verificare tutti i campi richiesti nell'oggetto di output della callback

Session State Serialization Error

Quando si verifica: Durante la serializzazione di un campo del session_state.

Messaggio di errore:

"Error while serializing the field {field_name} inside the session_state. Unable to serialize a value of type {field_type}."

Cause comuni:

• Tipo di dato non serializzabile salvato nel session_state
• Oggetti personalizzati senza metodi di serializzazione
• Riferimenti circolari

Come risolvere:

• Usa solo tipi di dati serializzabili (stringhe, numeri, liste, dizionari, booleani)
• Converti oggetti complessi in dizionari prima di salvarli
• Evita di salvare riferimenti a funzioni o classi nel session_state