Guida pratica alla lettura delle tracce

Modifica online

I dettagli di tracciamento forniscono una visione strutturata di come un agente elabora ogni richiesta, aiutandoti a comprendere le fasi principali di una conversazione o di un'attività. Ad alto livello, ogni traccia contiene intervalli che rappresentano diverse attività quali ragionamento dell'agente, esecuzione del flusso di lavoro, utilizzo degli strumenti e chiamate al modello. Questi intervalli aiutano a interpretare il flusso di esecuzione e a identificare dove viene impiegato il tempo.

Cosa mostrano i dettagli delle tracce

I dettagli di tracciamento rappresentano visivamente il modo in cui un agente elabora un messaggio dall'inizio alla fine. Ogni messaggio si espande in una sequenza strutturata di span, ciascuno dei quali corrisponde a un'attività specifica come ragionamento, flusso di strumenti, invocazione di modelli, esecuzione di flussi di lavoro o coinvolgimento umano.

È possibile utilizzare i dettagli di tracciamento per:

Segui il flusso completo dell'esecuzione eseguito dall'agente.
Comprendere in che modo le decisioni, gli strumenti e le chiamate al modello hanno contribuito alla risposta finale.
Verifica quali informazioni sono state trasmesse tra una fase e l'altra.
Identificare guasti, colli di bottiglia o comportamenti imprevisti.

Cosa rappresenta ogni campata

I seguenti span vengono comunemente emessi e rappresentano attività specifiche all'interno di un'esecuzione. Utilizzare la tabella seguente come riferimento durante l'analisi di qualsiasi traccia.


Estensione	Dettagli
`LangGraph.workflow`	L'intero flusso di lavoro eseguito: l'intervallo più esterno e il ciclo di vita completo dell'esecuzione.
`invoke_agent`	Ciclo di vita dell'invocazione dell'agente: quando un agente viene chiamato per la prima volta.
`invoke_agent.task`	Un singolo compito assegnato a un agente.
`agent.task`	Il ragionamento o l'obiettivo dell'agente per un compito specifico.
`agent.plan`	Il piano dell'agente o le fasi del ragionamento interno.
`agent_style_router.task`	Come il sistema sceglie quale agente o competenza chiamare successivamente.
`collaborator.task`	Lavoro delegato a un altro agente.
`ChatPromptTemplate.task`	Costruzione di prompt — modelli utilizzati per creare prompt di modello.
`llm.call`	L'invocazione del modello (LLM) responsabile della generazione del testo.
`tool.invoke`	Azione esterna.
`tools.task`	La decisione dell'agente di utilizzare uno strumento (decisione logica di utilizzo).
`human.task`	Un punto in cui era necessario l'intervento o la verifica umana.

Conserva i dettagli sopra riportati come riferimento ogni volta che leggi una traccia: ogni intervallo che vedi corrisponde a una di queste definizioni.

Riconoscere i diversi tipi di campate

Ogni traccia contiene intervalli che rappresentano attività chiave. Esempi comuni includono:

1. Intervalli di flusso di lavoro

Gli archi del flusso di lavoro rappresentano il ciclo di vita complessivo dell'esecuzione. Mostrano come il flusso di lavoro è stato eseguito dall'inizio alla fine, comprese le ramificazioni, i loop, le chiamate agli strumenti e le interazioni LLM.

Esempio di span: LangGraph.workflow

2. Intervalli degli agenti

Gli intervalli dell'agente indicano come l'agente ha pensato, pianificato e agito. Descrivono gli obiettivi dell'agente, come ha suddiviso i compiti e quali sottoagenti o strumenti ha selezionato.

Esempi di intervalli: invoke_agent, invoke_agent.task, agent.task, agent.plan

3. Campi d'azione degli utensili

Gli archi degli strumenti riflettono le azioni basate sugli strumenti. Utilizzateli per capire come e quando gli strumenti sono stati attivati, in particolare durante il debug dei malfunzionamenti degli strumenti.

Esempi di intervalli: tools.task, tool.invoke

4. Intervalli del modello (LLM)

Gli intervalli del modello catturano il comportamento del modello. Evidenziano quando il modello è stato utilizzato, quanto tempo ha richiesto e forniscono l'accesso al testo di input e output.

Esempio di span: llm.call

5. Le dimensioni dell'interazione umana

Gli intervalli di interazione umana indicano quando il sistema si è interrotto per consentire l'input, l'approvazione o il processo decisionale dell'utente.

Esempio di span: human.task

Utilizza gli span per comprendere le prestazioni complessive

Anche senza effettuare analisi più approfondite, gli intervalli di tracciamento aiutano a stimare le prestazioni:

Durata del flusso di lavoro : l'intervallo più esterno indica la durata complessiva della richiesta. Guarda la LangGraph.workflow campata.
Pensiero e azione dell'agente : gli ambiti relativi all'agente aiutano a capire dove l'agente ha pianificato e dove ha agito. Confronta agent.plan (pianificazione) e invoke_agent.task (esecuzione).
Utilizzo del modello : gli intervalli LLM mostrano dove il sistema si è basato sul modello linguistico, che spesso contribuisce alla latenza. Controlla llm.call per vedere con quale frequenza e per quanto tempo è stato utilizzato il modello.
Overhead degli strumenti : controlla tools.task e tool.invoke per capire quanto tempo passi a chiamare gli strumenti.

Queste visualizzazioni consentono di identificare quali parti del processo contribuiscono maggiormente alla latenza complessiva.

Individua rapidamente errori o problemi

È possibile eseguire la scansione degli intervalli di traccia per identificare dove si è verificato un errore:

Cerca gli span contrassegnati da avvisi o indicatori di errore.
Verifica se uno strumento, un flusso di lavoro o una chiamata al modello ha restituito un errore.
Capire se il problema ha avuto origine da uno strumento, un modello o una fase del flusso di lavoro.

Questa visione d'insieme ti aiuta a identificare rapidamente le aree problematiche prima di approfondire l'analisi.

Comprendere l'utilizzo del modello a colpo d'occhio

llm.call punti salienti:

Quando il modello è stato richiamato
Quante interazioni si sono verificate
Il ruolo generale svolto dal modello nella produzione della risposta

Questi intervalli consentono di comprendere rapidamente il coinvolgimento del modello durante una richiesta.

Migliori pratiche nella revisione delle tracce

Inizia con lo span di LangGraph.workflow livello superiore per comprendere la struttura complessiva.
Espandi la traccia passo dopo passo per vedere come ha proceduto l'agente.
Cerca modelli ripetuti, come chiamate ricorrenti a strumenti (tool.invoke) o invocazioni di modelli (llm.call).
Utilizza gli indicatori di errore per individuare rapidamente i guasti all'interno di tracce lunghe.

Questi modelli consentono di interpretare visivamente il flusso di tracce senza bisogno di conoscenze tecniche approfondite.