Context
Il context è l'argomento comune a tutte le callback. Questo parametro funge da accesso a tutte le informazioni utili durante l'esecuzione del Tree Agent. Di seguito è riportata la struttura di questo oggetto:
context
├── session_state
│ ├── get()
│ ├── set()
│ └── clear()
├── input
│ ├── original
│ ├── extended
│ └── attachments
├── explore_strategy
│ ├── direction
│ └── constraints
├── metadata
│ ├── session_id
│ ├── client_metadata
│ └── server_metadata
├── memory_agent
└── file_agent
Session state
L'albero supporta uno stato persistente privato associato a ciascuna sessione avviata tra un utente e l'agente stesso. Questo stato è condiviso tra tutti i nodi, quindi può anche essere usato come canale di comunicazione tra di essi.
La struttura del session_state è di tipo chiave-valore: mentre la chiave deve essere di tipo stringa, il valore può essere anche un oggetto, la cosa importante è che implementi un metodo serialize() che restituisce un oggetto completamente serializzabile.
Se si inserisce un oggetto dentro il session_state il suo metodo serialize() sarà chiamato automaticamente dopo la conclusione dell'interazione. Tuttavia, quando si accede ad un valore dove si era salvato un oggetto in un interazione precedente, al suo posto sarà presente l'oggetto serializzato restituito del metodo serialize()
La classe AiSessionState è definita come:
class AiSessionState:
get(key: str) -> any # metodo che permette di accedere al valore associato ad una chiave;
set(key: str, value: any) -> None # metodo che permette di associare un valore ad una chiave;
clear() -> None # svuota l'intero contenuto di session_state.
Input
L'input dell'utente viene conservato dentro un oggetto di tipo TreeAgentInput. Questo oggetto raggiungibile tramite context.input è definito come:
class TreeAgentInput:
original: str # il messaggio originale inviato dall'utente;
extended: str # il messaggio estedo tramite il Memory Agent sulla base del resto della conversazione
attachments: List[FileMetadata] # la lista di file eventualmente allegata al messaggio
Explore strategy
L'explore strategy è un oggetto di tipo AiExploreStrategy che permette di personalizzare la logica con cui viene individuato il nodo da eseguire durante lo step explore. L'oggetto è definito come:
class AiExploreStrategy:
direction: str # è la stringa dalla quale si ricava l'embedding utilizzato per calcolare la similarity durante l'esplorazione
constraints: AiExploreConstraints # sono dei vincoli che possono andare a limitare i chunk considerati durante l'esplorazione
con
class AiExploreConstraints:
blacklist: AiBlackList = AiBlackList() # permette di specificare l'id di nodi o chunk da ignorare durante l'esplorazione
filter: models.Filter | None = None # sono i filtri qdrant che possono veicolare l'esplorazione
keep: bool = False # se impostato a True, allora al termine di ogni interazione blacklist e filter sono azzerati
con
class AiBlackList:
add: (int | Iterable[int], Literal["chunk", "node"]) => None # permette di aggiungere uno o più id di nodi o chunk nella blacklist
remove: (int | Iterable[int], Literal["chunk", "node"]) => None # permette di rimuovere uno o più id di nodi o chunk nella blacklist
is_empty: () => bool # True se la blacklist è vuota, False altrimenti
La proprietà direction viene impostata all'inizio di ogni interazione con TreeAgentInput.extended
Metadata
I metadati sono delle informazioni extra che possono accompagnare il messaggio in input inviato dall'utente oppure la risposta dell'agente. Ad esempio, tramite questo canale il frontend può inviare dei token di identificazione per personalizzare il comportamento del sistema in base al ruolo dell'utente, oppure si possono inviare dati che servono al frontend per dare dei feedback specifici. Dentro context.metadata è presente un oggetto di tipo AiMetadata strutturato come:
session_id(str | None): l'indentificativo della sessione attuale;client_metadata(Dict[str, str]): un dizionario che contiene tutte le informazioni ricevute dal fronted;server_metadata(Dict[str, str]): un dizionario che contiene tutte le informazioni che saranno inviate al frontend.
Il dizionario server_metadata NON è persistente, quindi se si intende inviare un dato tramite questo canale ad ogni interazione, sarà necessario inserirlo tutte le volte
Quando si sta sviluppando un nuovo flow, spesso si è interessati a conoscere il contenuto effettivo del session_state dopo ogni interazione. Per far ciò in modo semplice è sufficiente inserire nella callback before_run o after_run il seguente comando:
context.metadata.server_metadata['session_state'] = context.session_state.serialize()
a questo punto, nelle informazioni di debug associate alla chat, si potrà accedere alle informazioni desiderate!
Memory agent
Il Memory Agent mette a disposizione tutti gli strumenti utili a gestire la memoria, quindi i messaggi precedenti della conversazione. Per approfondire il suo funzionamento fare riferimento alla documentazione dedicata.
File agent
Il File Agent mette a disposizione tutti gli strumenti utili a gestire i file. Per approfondire il suo funzionamento fare riferimento alla documentazione dedicata.