Trace logging per i passaggi degli agenti
Registrazione di ogni passaggio di ragionamento, chiamata a uno strumento e risultato per l’analisi post-mortem
Trace logging per i passaggi degli agenti è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.
Perché il trace logging è essenziale per gli agenti
I log standard delle applicazioni registrano errori ed eventi. I trace log degli agenti registrano il ragionamento: che cosa ha pensato l'agente a ogni passaggio, quale strumento ha scelto, quali argomenti ha utilizzato e che cosa ha restituito lo strumento?
Senza il trace logging, eseguire il debugging di un errore dell'agente è come diagnosticare un problema dell'auto senza alcun cruscotto: si può solo tirare a indovinare.
Configurare il modulo di logging di Python
Il modulo integrato logging di Python è lo strumento standard. Lo configuri all'inizio dell'agente con un formato che includa data e ora, livello e messaggio. Utilizzi il livello DEBUG per i dati di trace: può essere disattivato in produzione.
import logging
import sys
logging.basicConfig(
level=logging.DEBUG,
format='%(asctime)s [%(levelname)s] %(name)s: %(message)s',
datefmt='%H:%M:%S',
stream=sys.stdout
)
logger = logging.getLogger('myagent')
# Usage:
logger.debug('Step 1: reasoning started')
logger.info('Agent task completed in 5 steps')
logger.warning('Tool returned empty result')
logger.error('Failed to parse tool arguments')
# Output:
# 14:32:01 [DEBUG] myagent: Step 1: reasoning started
# 14:32:03 [INFO] myagent: Agent task completed in 5 stepsRegistrare ogni passaggio del ragionamento
Registri i dati essenziali all'inizio di ogni passaggio: il numero del passaggio, il ragionamento prodotto dall'LLM, lo strumento selezionato e gli argomenti passati. In questo modo crea un resoconto completo del processo decisionale dell'agente.
import logging
import json
logger = logging.getLogger('myagent')
def log_step(step: int, thought: str, tool_name: str, tool_args: dict):
logger.debug(
f'Step {step}: '
f'reasoning="{thought[:100]}" '
f'tool={tool_name} '
f'args={json.dumps(tool_args, ensure_ascii=False)[:200]}'
)
# Example usage in the agent loop:
# log_step(
# step=1,
# thought='I need to find the current weather in Tokyo',
# tool_name='get_weather',
# tool_args={'city': 'Tokyo', 'unit': 'celsius'}
# )
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
log_step(
step=1,
thought='I need to find the current weather in Tokyo',
tool_name='get_weather',
tool_args={'city': 'Tokyo', 'unit': 'celsius'}
)
Registrare i risultati degli strumenti
Dopo ogni chiamata allo strumento, registri se ha avuto successo e un'anteprima del risultato. Registrare il risultato completo potrebbe generare un output eccessivamente dettagliato: per una maggiore leggibilità, lo tronchi ai primi 200 caratteri.
import logging
logger = logging.getLogger('myagent')
def log_tool_result(step: int, tool_name: str, result: str, success: bool):
status = 'OK' if success else 'ERROR'
preview = str(result)[:200].replace('\n', ' ')
logger.debug(
f'Step {step} result [{status}]: tool={tool_name} '
f'result_preview="{preview}"'
)
if not success:
logger.warning(f'Tool {tool_name} failed at step {step}')
# Log at the start of the step:
# log_step(step, thought, tool_name, tool_args)
# result = execute_tool(tool_name, tool_args)
# log_tool_result(step, tool_name, result, success=True)
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
log_tool_result(1, 'get_weather', '{"temp_c": 18, "condition": "cloudy"}', success=True)
log_tool_result(2, 'get_weather', 'Connection timed out', success=False)
Logging strutturato in formato JSON
I log in testo semplice sono facili da leggere, ma difficili da interrogare. I log JSON strutturati possono essere acquisiti dai sistemi di aggregazione dei log (Datadog, Splunk, CloudWatch) per applicare filtri e creare dashboard e avvisi.
import logging
import json
import sys
class JSONFormatter(logging.Formatter):
def format(self, record: logging.LogRecord) -> str:
log_obj = {
'timestamp': self.formatTime(record),
'level': record.levelname,
'logger': record.name,
'message': record.getMessage()
}
# Add any extra fields attached to the log record
if hasattr(record, 'step'):
log_obj['step'] = record.step
if hasattr(record, 'tool'):
log_obj['tool'] = record.tool
return json.dumps(log_obj)
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(JSONFormatter())
logger = logging.getLogger('agent_trace')
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)
logger.setLevel(logging.DEBUG)
logger.debug('Step 3: tool=search_web', extra={'step': 3, 'tool': 'search_web'})
Registrare campi aggiuntivi
Passi extra={} a una chiamata di log per allegare campi strutturati che i formattatori JSON o gli aggregatori di log possono utilizzare per filtrare e analizzare i dati.
import logging
logger = logging.getLogger('agent_trace')
def log_step_structured(step: int, tool: str, thought: str, args: dict):
logger.debug(
f'Step {step}: tool={tool}',
extra={
'step': step,
'tool': tool,
'thought': thought[:200],
'tool_args': args
}
)
# If using a JSON formatter, this produces:
# {
# 'timestamp': '14:32:01',
# 'level': 'DEBUG',
# 'message': 'Step 3: tool=search_web',
# 'step': 3,
# 'tool': 'search_web',
# 'thought': 'I need to find recent news about...',
# 'args': {'query': 'AI news 2025'}
# }
if __name__ == '__main__':
import sys
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(logging.Formatter('%(message)s | step=%(step)s tool=%(tool)s'))
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)
log_step_structured(3, 'search_web', 'I need to find recent news about...', {'query': 'AI news 2025'})
Registrare in un file
Per gli agenti in produzione, registri i dati in un file per poterli analizzare in seguito. Utilizzi RotatingFileHandler per limitare le dimensioni del file di log ed evitare di esaurire lo spazio su disco.
import logging
from logging.handlers import RotatingFileHandler
import sys
logger = logging.getLogger('myagent')
logger.setLevel(logging.DEBUG)
# Console handler — INFO and above
console = logging.StreamHandler(sys.stdout)
console.setLevel(logging.INFO)
console.setFormatter(logging.Formatter('%(message)s'))
# File handler — DEBUG and above, rotates at 10MB
file_handler = RotatingFileHandler(
'agent_trace.log',
maxBytes=10 * 1024 * 1024, # 10 MB
backupCount=3
)
file_handler.setLevel(logging.DEBUG)
file_handler.setFormatter(logging.Formatter(
'%(asctime)s [%(levelname)s] %(message)s'
))
logger.addHandler(console)
logger.addHandler(file_handler)
logger.info('Agent task completed in 5 steps')
logger.debug('Step 1: reasoning started')
Registrare gli ID di sessione per gli agenti multiutente
Quando più utenti o attività vengono eseguiti contemporaneamente, i log possono mescolarsi. Alleghi un ID di sessione o un ID attività a ogni messaggio di log, così potrà filtrare i log relativi a un'esecuzione specifica.
import logging
import uuid
class SessionLogger:
def __init__(self, name: str):
self.logger = logging.getLogger(name)
self.session_id = str(uuid.uuid4())[:8]
def debug(self, msg: str, **kwargs):
self.logger.debug(f'[session={self.session_id}] {msg}', **kwargs)
def info(self, msg: str, **kwargs):
self.logger.info(f'[session={self.session_id}] {msg}', **kwargs)
def error(self, msg: str, **kwargs):
self.logger.error(f'[session={self.session_id}] {msg}', **kwargs)
# Each agent run gets its own logger with a unique session ID
# log = SessionLogger('myagent')
# log.info(f'Starting task: {query}') # [session=a3f1b290] Starting task: ...
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.INFO, format='%(message)s', stream=sys.stdout)
log = SessionLogger('myagent')
log.info(f'Starting task: summarize the quarterly report')
Cronometrare ogni passaggio
Aggiunga informazioni sulla durata al log di ogni passaggio per identificare i colli di bottiglia. Quale strumento è il più lento? Quanto tempo impiega l'LLM per ragionare? Questi dati guidano l'ottimizzazione.
import time
import logging
logger = logging.getLogger('myagent')
def timed_tool_call(tool_name: str, tool_fn, args: dict) -> str:
start = time.perf_counter()
try:
result = tool_fn(**args)
elapsed = time.perf_counter() - start
logger.debug(f'Tool {tool_name} completed in {elapsed:.2f}s')
return result
except Exception as e:
elapsed = time.perf_counter() - start
logger.error(f'Tool {tool_name} failed in {elapsed:.2f}s: {e}')
raise
# In the agent loop:
# result = timed_tool_call('search_web', search_web, {'query': 'Python'})
# Logs: Tool search_web completed in 1.34s
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
def search_web(query):
return f'3 results for {query}'
result = timed_tool_call('search_web', search_web, {'query': 'Python'})
print('Tool result:', result)
Il modello completo di trace dei passaggi
Ecco il modello completo e pronto per la produzione per registrare il trace di un passaggio dell'agente. Ogni passaggio registra il proprio numero, il ragionamento, lo strumento scelto, gli argomenti, un'anteprima del risultato e la durata, offrendo una visibilità completa sull'esecuzione dell'agente.
import time
import logging
import json
logger = logging.getLogger('myagent')
def trace_step(step_num: int, thought: str, tool: str, args: dict, execute_fn):
# Log decision
logger.debug(
f'Step {step_num}: thought="{thought[:80]}" tool={tool} '
f'args={json.dumps(args)[:100]}'
)
# Execute with timing
t0 = time.perf_counter()
try:
result = execute_fn(tool, args)
elapsed = time.perf_counter() - t0
preview = str(result)[:100].replace('\n', ' ')
logger.debug(f'Step {step_num} done in {elapsed:.2f}s: "{preview}"')
return result
except Exception as e:
elapsed = time.perf_counter() - t0
logger.error(f'Step {step_num} failed in {elapsed:.2f}s: {e}')
return f'ERROR: {e}'
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
def execute_fn(tool, args):
return f'42 (from {tool})'
trace_step(1, 'I should compute the answer', 'calculator', {'expr': '6*7'}, execute_fn)
Disattivare i log in produzione
I trace log di debug contengono dati sensibili (query, risposte API) e possono essere molto dettagliati. In produzione, imposti il livello di log su INFO o WARNING per sopprimere i trace di debug. Utilizzi una variabile d'ambiente per controllare il livello.
import os
import logging
import sys
# Read log level from environment variable
log_level_str = os.environ.get('LOG_LEVEL', 'INFO').upper()
log_level = getattr(logging, log_level_str, logging.INFO)
logging.basicConfig(level=log_level, stream=sys.stdout)
logger = logging.getLogger('myagent')
# Development: LOG_LEVEL=DEBUG python agent.py -> full traces
# Production: LOG_LEVEL=WARNING python agent.py -> only warnings/errors
# Default: LOG_LEVEL not set -> INFO level
logger.debug('This only appears in DEBUG mode')
logger.info('This appears in INFO and DEBUG modes')
logger.warning('This always appears')Verifica delle conoscenze: trace logging
Verifichi la Sua comprensione del trace logging per i passaggi degli agenti.
Riepilogo: trace logging per i passaggi degli agenti
Ora dispone di una strategia completa di trace logging per gli agenti:
- Utilizzi
logging.basicConfig(level=DEBUG)per abilitare i log a livello di trace - Registri il numero del passaggio, il ragionamento, il nome dello strumento e gli argomenti a ogni passaggio
- Registri i risultati degli strumenti con un'anteprima e lo stato di successo o di errore
- Utilizzi la formattazione JSON per ottenere log strutturati e interrogabili
- Alleghi gli ID di sessione per gli agenti multiutente o concorrenti
- Aggiunga la durata per identificare i passaggi lenti
- Controlli il livello di dettaglio dei log con la variabile d'ambiente
LOG_LEVEL
Domande Frequenti
La lezione «Trace logging per i passaggi degli agenti» è gratuita?
Sì — il testo completo di «Trace logging per i passaggi degli agenti» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.
Cosa imparerò in «Trace logging per i passaggi degli agenti»?
Registrazione di ogni passaggio di ragionamento, chiamata a uno strumento e risultato per l’analisi post-mortem Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare AI Agents?
Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.
Quanto tempo richiede la lezione «Trace logging per i passaggi degli agenti»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione AI Agents?
Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Errori comuni nei cicli degli agenti
- Trace logging per i passaggi degli agenti
- Rilevamento e interruzione dei cicli infiniti
- Tecniche di debugging passo passo