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 eseguiro 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 utilizzando il metodo python print() dentro le callback dei nodi: in questo caso, il testo dentro il print sarà mostrato come dato associato all'evento DEBUG 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 = {type: OutcomeType.FAILURE}.

Quando si attiva il meccanismo di reach_anchor si sale un nodo genitore alla volta finchè non si incotra 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 immediatamente lanciata la callback fallback. Grazie a questo sistema, insieme ad altri mechanisi, si evitano eventuali loop.

Ogni volta che si attiva il reach_anchor, viene anche aggiornata una lista chiamata black_list che può contenere sia chunk_id che node_id. Nello specifico, quando si verifica il caso 2, tutto il sottoalbero del nodo corrente viene aggiunto alla black_list, mentre se verifica il caso 3 vengono aggiunti solo gli id eventualmente specificati tramite failed_ids. In fase di ricerca, tutti i chunk riportati nella black_list, oppure discendendi 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.

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