Ciao a tutti, Leo qui da agntdev.com. Spero che stiate tutti passando una settimana produttiva!
Oggi voglio esplorare qualcosa di cui ho riflettuto molto ultimamente, specialmente mentre lavoravo su alcuni progetti personali che coinvolgono flussi di lavoro agentici più complessi e multi-step. Parliamo molto di come costruire agenti, degli LLM stessi e delle cose interessanti che possono fare. Ma che dire dell’aspetto meno glamour, ma assolutamente cruciale, di garantire che i nostri agenti funzionino effettivamente in modo affidabile ed efficiente nel tempo?
In particolare, sto parlando di osservabilità degli agenti. Non si tratta solo di registrazione; si tratta di comprendere veramente cosa sta facendo il tuo agente, perché lo sta facendo e di individuare i problemi prima che si amplifichino. In un mondo in cui gli agenti interagiscono con API esterne, prendono decisioni basate su input dinamici e potrebbero funzionare per lunghi periodi, procedere alla cieca è una ricetta per il disastro. L’ho imparato a mie spese, come spiegherò.
Il “Bug Misterioso” Che Mi Ha Insegnato Tutto
Qualche mese fa, stavo sviluppando un agente assistente personale. Chiamiamolo “Progetto Chronos.” Il suo compito era monitorare il mio calendario, i feed di notizie e specifici canali Slack, quindi suggerire proattivamente orari per le riunioni, riassumere aggiornamenti chiave o addirittura redigere risposte iniziali a domande comuni. Roba piuttosto standard in superficie.
Lo ho costruito, testato con alcuni scenari e sembrava funzionare bene. L’ho impostato per funzionare durante la notte, pensando di svegliarmi con un riassunto perfettamente curato. Invece, mi sono svegliato… nulla. O meglio, un riassunto parziale che si fermava bruscamente, seguito da un messaggio di errore criptico nei log di sistema che diceva essenzialmente “qualcosa è andato storto.”
Il debug di questo è stato un incubo. Chronos doveva fare diverse cose: recuperare eventi del calendario, interrogare un’API di notizie, interagire con un’API di Slack, elaborare i dati e poi generare un riassunto. Quale passaggio è fallito? Perché? Ha anche provato tutti i passaggi? Era un limite di richiesta dell’API? Un prompt malformato? Un timeout? Non ne avevo idea.
I miei log iniziali erano basilari: “Iniziato passaggio X,” “Completato passaggio Y,” e poi l’output finale o un errore. Questo non era sufficiente. Era come provare a diagnosticare un problema dell’auto sapendo solo che era partita e poi si era fermata, senza alcuna informazione sulla temperatura del motore, sulla pressione del carburante o sui guasti elettrici.
Quella esperienza ha sottolineato il punto: se sei serio riguardo allo sviluppo di agenti, hai bisogno di una solida osservabilità sin dal primo giorno. Non è un pensiero secondario; è un componente fondamentale.
Oltre la Registrazione di Base: Cosa Significa “Osservabilità” per gli Agenti?
Per me, l’osservabilità degli agenti si suddivide in alcune aree chiave, ognuna delle quali fornisce una diversa prospettiva sul funzionamento del tuo agente:
1. Tracciamento dell’Esecuzione Passo-Passo
Questo è il punto più critico. Devi sapere esattamente cosa sta facendo il tuo agente in ciascuna fase della sua esecuzione. Pensa a questo come a una dettagliata traccia breadcrumb. Per il Progetto Chronos, avevo bisogno di vedere:
- Quando ha iniziato a recuperare eventi dal calendario.
- I parametri utilizzati per la chiamata API del calendario (ad es., intervallo di date).
- La risposta grezza dall’API del calendario.
- Come ha elaborato quella risposta.
- Il prompt esatto inviato all’LLM per riassumere le informazioni del calendario.
- La risposta dell’LLM.
- Qualsiasi strumento chiamato, con i suoi input e output.
- Messaggi di errore, non solo “qualcosa è fallito,” ma un errore specifico con contesto (ad es., “L’API del calendario ha restituito 401 Unauthorized per l’utente X”).
Questo livello di dettaglio è prezioso per ricreare problemi e comprendere i punti decisionali. I miei log iniziali dicevano solo “Recuperando dati del calendario…” e poi “Riassumendo i dati del calendario…” senza nulla nel mezzo. Non è stato utile quando il recupero dei dati stesso è fallito silenziosamente.
2. Tracciamento di Prompt e Risposte
L’LLM è il cervello del tuo agente. Se non sai quali prompt sta ricevendo e quali risposte sta dando, stai procedendo a tentoni. Questo include:
- Il prompt completo inviato all’LLM (sistema, utente e qualsiasi descrizione della chiamata di funzione).
- La temperatura, top_p e altri parametri di generazione.
- La risposta grezza dall’LLM, comprese eventuali chiamate a strumenti che ha deciso di fare.
- Utilizzo dei token (input, output, totale) per tracciare i costi e analizzare le prestazioni.
Questo è cruciale per l’ingegneria dei prompt. Se un agente fornisce risposte prive di senso, vedere il prompt esatto che ha ricevuto ti aiuta a capire se il contesto di input era sbagliato o se il prompt stesso era mal strutturato.
3. Monitoraggio delle Chiamate agli Strumenti
Gli agenti interagiscono spesso con strumenti esterni o API. Ogni interazione è un potenziale punto di fallimento o comportamento inaspettato. Devi registrare:
- Quale strumento è stato chiamato.
- Gli argomenti esatti passati allo strumento.
- L’output grezzo dallo strumento.
- Eventuali errori restituiti dallo strumento o durante la sua esecuzione.
Per Chronos, se ha provato a chiamare l’API di Slack per postare un riassunto, avevo bisogno di sapere il canale che ha mirato, il contenuto del messaggio e se l’API ha restituito, ad esempio, un errore 403 Forbidden. La mia configurazione precedente mi diceva solo “Provato a postare su Slack.”
4. Snapshot dello Stato
Moltissimi agenti mantengono uno stato interno – un foglio di lavoro, una memoria, un elenco di fatti che hanno raccolto. Catturare periodicamente questo stato può essere incredibilmente utile per il debug. Se un agente rimane bloccato in un ciclo o prende una brutta decisione, vedere i suoi “pensieri” interni in vari momenti può rivelare dove la sua comprensione è andata fuori strada.
Questo riguarda meno la registrazione di ogni singola variazione di variabile e più la cattura degli stati chiave per la presa di decisioni. Per Chronos, questo potrebbe essere “Comprensione attuale del programma dell’utente,” o “Punti chiave dai feed di notizie finora.”
Approcci Pratici: Costruire L’Osservabilità
Okay, quindi come implementiamo effettivamente questo senza affogare nei log? Ecco alcune strategie pratiche e frammenti di codice.
Strategia 1: Registrazione Strutturata con Contesto
Dimentica le istruzioni `print()`. Usa una libreria di registrazione adeguata (come il modulo `logging` di Python). Fondamentale, arricchisci i tuoi messaggi di log con dati strutturati (JSON, dizionari) piuttosto che solo stringhe semplici. Questo rende i log analizzabili, ricercabili e molto più utili.
Ecco un esempio semplificato in Python:
import logging
import json
import uuid
from datetime import datetime
# Configurazione base del logger (in un'app reale, lo configureresti in modo più solido)
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)
handler = logging.StreamHandler()
formatter = logging.Formatter('%(levelname)s: %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)
def log_agent_step(agent_id: str, step_name: str, status: str, details: dict = None):
log_data = {
"timestamp": datetime.now().isoformat(),
"agent_id": agent_id,
"step_name": step_name,
"status": status, # ad esempio, "iniziato", "completato", "fallito"
"details": details if details is not None else {}
}
logger.info(json.dumps(log_data))
class MyAgent:
def __init__(self, agent_id: str = None):
self.agent_id = agent_id if agent_id else str(uuid.uuid4())
self.memory = [] # Memoria interna semplice
def _fetch_calendar_events(self, user_id: str, date_range: str):
log_agent_step(self.agent_id, "fetch_calendar_events", "iniziato",
{"user_id": user_id, "date_range": date_range})
try:
# Simula una chiamata API
if "error" in date_range:
raise ValueError("Errore simulato nell'API del calendario")
events = [
{"title": "Team Sync", "time": "10:00 AM"},
{"title": "Client Meeting", "time": "02:00 PM"}
]
log_agent_step(self.agent_id, "fetch_calendar_events", "completato",
{"num_events": len(events), "data_preview": events[0]})
self.memory.append(f"Eventi del calendario: {events}")
return events
except Exception as e:
log_agent_step(self.agent_id, "fetch_calendar_events", "fallito",
{"error": str(e), "traceback": "..."}) # Nella vita reale, cattura traceback
raise
def _summarize_with_llm(self, prompt_text: str):
log_agent_step(self.agent_id, "summarize_with_llm", "iniziato",
{"prompt_length": len(prompt_text), "prompt_preview": prompt_text[:100]})
try:
# Simula una chiamata LLM
if "fail_llm" in prompt_text:
raise RuntimeError("Errore simulato nell'API LLM")
response = f"Riepilogo LLM di: {prompt_text[:50]}..."
token_usage = {"input": len(prompt_text) // 4, "output": len(response) // 4}
log_agent_step(self.agent_id, "summarize_with_llm", "completato",
{"response_length": len(response), "token_usage": token_usage,
"llm_response_preview": response[:100]})
self.memory.append(f"Riepilogo prodotto dal LLM: {response}")
return response
except Exception as e:
log_agent_step(self.agent_id, "summarize_with_llm", "fallito",
{"error": str(e), "traceback": "..."})
raise
def run_daily_briefing(self, user_id: str):
log_agent_step(self.agent_id, "run_daily_briefing", "iniziato", {"user_id": user_id})
try:
calendar_data = self._fetch_calendar_events(user_id, "oggi")
news_summary = self._summarize_with_llm("Riepiloga le top news di oggi...")
final_briefing_prompt = (
f"Crea un briefing giornaliero basato su:\n"
f"Calendario: {json.dumps(calendar_data)}\n"
f"News: {news_summary}"
)
final_briefing = self._summarize_with_llm(final_briefing_prompt)
log_agent_step(self.agent_id, "run_daily_briefing", "completato",
{"final_briefing_length": len(final_briefing)})
return final_briefing
except Exception as e:
log_agent_step(self.agent_id, "run_daily_briefing", "fallito",
{"error": str(e), "current_memory": self.memory}) # Cattura memoria in caso di fallimento
raise
# Esempio di utilizzo
if __name__ == "__main__":
agent = MyAgent()
print(f"\n--- Esecuzione dell'Agente {agent.agent_id} (Caso di Successo) ---")
try:
briefing = agent.run_daily_briefing("leo_g")
print(f"Briefing: {briefing[:100]}...")
except Exception as e:
print(f"Esecuzione dell'agente fallita: {e}")
agent_fail = MyAgent()
print(f"\n--- Esecuzione dell'Agente {agent_fail.agent_id} (Caso di Fallimento del Calendario) ---")
try:
# Simula un fallimento del calendario passando "error" in date_range
agent_fail._fetch_calendar_events("leo_g", "error_today")
except Exception as e:
print(f"Esecuzione dell'agente fallita come previsto: {e}")
agent_llm_fail = MyAgent()
print(f"\n--- Esecuzione dell'Agente {agent_llm_fail.agent_id} (Caso di Fallimento LLM) ---")
try:
# Simula un fallimento LLM
agent_llm_fail._summarize_with_llm("fail_llm_please")
except Exception as e:
print(f"Esecuzione dell'agente fallita come previsto: {e}")
Nota come `log_agent_step` cattura l’ID dell’agente, il nome del passo, lo stato e un dizionario di dettagli pertinenti. Questo rende facile filtrare i log per ID dell’agente, tracciare un’esecuzione singola o cercare tutti i passi “falliti”.
Strategia 2: Osservabilità Centralizzata con una Libreria/Servizio Dedicato
Per agenti più complessi o ambienti di produzione, crescerai rapidamente oltre la semplice registrazione su file. Qui è dove gli strumenti specializzati brillano. Librerie come `LangSmith` di LangChain (o simili per altri framework) offrono tracciamento incorporato, visualizzazione e debugging per applicazioni LLM.
Anche se non stai usando LangChain, il concetto è trasferibile. Puoi costruire il tuo wrapper attorno all’esecuzione del tuo agente che invia eventi strutturati a un servizio di registrazione (Datadog, Splunk, ELK stack o anche un semplice bucket S3 con elaborazione Lambda). La chiave è standardizzare lo schema degli eventi.
Il mio progetto Chronos migliorato ora utilizza una classe personalizzata `TraceManager` che avvolge operazioni critiche. Questo manager invia eventi strutturati a un database locale per lo sviluppo e a un servizio di registrazione cloud in produzione. Questo mi consente di vedere un’intera “traccia” di ogni esecuzione dell’agente, con passi annidati e tutti i dati associati (prompt, risposte, input/output degli strumenti, errori).
Strategia 3: Catturare le Chiamate LLM e Strumenti
Molti SDK LLM consentono di impostare callback o intercettori per le chiamate API. Usali! Invece di registrare manualmente prima e dopo ogni prompt LLM, puoi avere un singolo intercettore che registra automaticamente:
- Il preciso endpoint API colpito.
- Intestazioni e corpo della richiesta (specialmente il prompt).
- Intestazioni e corpo della risposta (la completazione).
- Latente.
- Eventuali eccezioni.
Allo stesso modo, avvolgi le chiamate ai tuoi strumenti. Se hai uno strumento `search_web`, il wrapper dovrebbe registrare la query di ricerca, il motore di ricerca utilizzato e i primi N risultati restituiti, insieme a eventuali errori.
Raccomandazioni Pratiche per il Tuo Prossimo Progetto di Agente
- Progetta per l’Osservabilità Innanzitutto: Non trattarlo come una questione secondaria. Pensa a cosa ti servirebbe per il debug prima di scrivere il tuo primo passo dell’agente.
- Abbraccia la Registrazione Strutturata: Dimentica `print()` e `console.log()` per il codice di produzione. Usa una libreria di registrazione appropriata e restituisci dati strutturati (JSON) per ogni evento significativo.
- Traccia Tutto ci’è di Importante: Registra l’inizio e la fine di ciascun passo importante, tutti i prompt e le risposte LLM (inclusi parametri e conteggi token), e ogni chiamata agli strumenti con i suoi input e output.
- Cattura lo Stato in Caso di Fallimento: Quando un agente fallisce, registra il suo stato interno o memoria in quel momento. Questo fornisce un contesto cruciale per capire perché è fallito.
- Usa ID Specifici per gli Agenti: Assegna un ID unico a ciascuna esecuzione dell’agente (ad es., un UUID). Questo ti consente di filtrare e tracciare facilmente un singolo percorso di esecuzione nei tuoi log.
- Visualizza le Tue Tracce: Se possibile, utilizza o costruisci uno strumento che possa visualizzare questi log strutturati come una sequenza di eventi. Vedere il flusso rende il debug infinitamente più facile rispetto a setacciare il testo grezzo. LangSmith lo fa splendidamente, ma anche uno script personalizzato può renderizzare una semplice timeline HTML.
- Monitora i Costi: L’uso dei token LLM è un costo diretto. Registra. Questo ti aiuta a capire dove stanno andando i tuoi soldi e ottimizzare i tuoi prompt.
Costruire agenti è emozionante, ma costruire agenti affidabili è dove si trova il vero lavoro (e il vero valore). E l’affidabilità inizia con la conoscenza di ciò che sta accadendo sotto il cofano. La mia dolorosa esperienza con il Progetto Chronos mi ha insegnato bene questa lezione. Non aspettare il tuo “bug misterioso” per convincerti. Inizia a registrare in modo intelligente oggi.
Quali sono le tue strategie di osservabilità preferite per gli agenti? Contattami nei commenti o sui social media. Sono sempre interessato a sentire come altri affrontano queste sfide!
🕒 Published: