Trace-Logging für Agentenschritte
Jeden Denkschritt, Tool-Aufruf und jedes Ergebnis zur nachträglichen Analyse protokollieren.
Trace-Logging für Agentenschritte ist eine kostenlose AI Agents-Lektion auf CoddyKit. Dies ist Lektion 2 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des AI Agents-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der AI Agents-Kurs umfasst insgesamt 4 Lektionen.
Warum Trace-Logging für Agenten unverzichtbar ist
Standardmäßige Anwendungsprotokolle erfassen Fehler und Ereignisse. Trace-Logs von Agenten erfassen Überlegungen: Was hat der Agent bei jedem Schritt gedacht, welches Werkzeug hat er ausgewählt, welche Argumente hat er verwendet und was hat das Werkzeug zurückgegeben?
Ohne Trace-Logging gleicht das Debugging eines Agentenfehlers der Diagnose eines Autoproblems ohne Armaturenbrett — Sie können nur raten.
Das Python-Logging-Modul einrichten
Das integrierte Python-Modul logging ist das Standardwerkzeug. Konfigurieren Sie es am Anfang Ihres Agenten mit einem Format, das Zeitstempel, Ebene und Nachricht enthält. Verwenden Sie die Ebene DEBUG für Trace-Daten — sie kann im Produktivbetrieb deaktiviert werden.
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 stepsJeden Überlegungsschritt protokollieren
Protokollieren Sie zu Beginn jedes Schritts die wichtigsten Fakten: die Schrittnummer, die vom LLM erzeugten Überlegungen, das ausgewählte Werkzeug und die übergebenen Argumente. So entsteht eine vollständige Aufzeichnung des Entscheidungsprozesses des Agenten.
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'}
)
Werkzeugergebnisse protokollieren
Protokollieren Sie nach jedem Werkzeugaufruf, ob er erfolgreich war, sowie eine Vorschau des Ergebnisses. Das vollständige Ergebnis zu protokollieren, kann zu ausführlich sein — kürzen Sie es zur besseren Lesbarkeit auf die ersten 200 Zeichen.
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)
Strukturiertes Logging im JSON-Format
Textprotokolle sind leicht zu lesen, aber schwer abzufragen. Strukturierte JSON-Logs können von Systemen zur Protokollaggregation (Datadog, Splunk, CloudWatch) eingelesen werden, um Filter, Dashboards und Warnmeldungen zu ermöglichen.
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'})
Logging mit zusätzlichen Feldern
Übergeben Sie extra={} an einen Logging-Aufruf, um strukturierte Felder anzuhängen, die von JSON-Formatierern oder Log-Aggregatoren zum Filtern und Analysieren verwendet werden können.
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'})
In eine Datei loggen
Protokollieren Sie bei Agenten im Produktivbetrieb in eine Datei, um die Daten später analysieren zu können. Verwenden Sie RotatingFileHandler, um die Größe der Protokolldatei zu begrenzen und ein Volllaufen des Datenträgers zu verhindern.
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')
Sitzungs-IDs für Agenten mit mehreren Benutzern protokollieren
Wenn mehrere Benutzer oder Aufgaben gleichzeitig ausgeführt werden, können sich die Protokolle vermischen. Hängen Sie an jede Protokollnachricht eine Sitzungs-ID oder Aufgaben-ID an, damit Sie die Protokolle eines bestimmten Durchlaufs filtern können.
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')
Die Dauer jedes Schritts messen
Fügen Sie jedem Schrittprotokoll Zeitmessungsdaten hinzu, um Engpässe zu erkennen. Welches Werkzeug ist am langsamsten? Wie lange braucht das LLM zum Überlegen? Diese Daten helfen bei der Optimierung.
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)
Das vollständige Muster für Schritt-Trace-Logging
Hier ist das vollständige, für den Produktivbetrieb geeignete Muster für Trace-Logging eines Agentenschritts. Jeder Schritt protokolliert seine Nummer, die Überlegungen, die Werkzeugauswahl, die Argumente, eine Vorschau des Ergebnisses und die Dauer — so erhalten Sie vollständige Transparenz über die Ausführung des Agenten.
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)
Logs im Produktivbetrieb deaktivieren
Debug-Trace-Logs enthalten vertrauliche Daten (Abfragen, API-Antworten) und können sehr ausführlich sein. Setzen Sie im Produktivbetrieb die Protokollebene auf INFO oder WARNING, um Debug-Traces zu unterdrücken. Verwenden Sie eine Umgebungsvariable, um die Ebene zu steuern.
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')Wissenscheck: Trace-Logging
Testen Sie Ihr Verständnis von Trace-Logging für Agentenschritte.
Zusammenfassung: Trace-Logging für Agentenschritte
Sie verfügen jetzt über eine vollständige Strategie für Trace-Logging bei Agenten:
logging.basicConfig(level=DEBUG)verwenden, um Logs auf Trace-Ebene zu aktivieren- Bei jedem Schritt Schrittnummer, Überlegungen, Werkzeugnamen und Argumente protokollieren
- Werkzeugergebnisse mit einer Vorschau sowie einem Erfolgs-/Fehlerstatus protokollieren
- JSON-Formatierung für strukturierte und abfragbare Logs verwenden
- Sitzungs-IDs für Agenten mit mehreren Benutzern oder parallele Agenten anhängen
- Zeitmessungen hinzufügen, um langsame Schritte zu erkennen
- Die Ausführlichkeit der Logs mit der Umgebungsvariable
LOG_LEVELsteuern
Lerne AI Agents mit einem KI-Tutor — kostenlos
Schreibe und führe echten Code in deinem Browser aus, bekomme sofortige Hilfe von einem 24/7 KI-Tutor und setze dein Lernen im Web oder in der App fort.
- Kurse
- 60
- Lektionen
- 239
Häufig gestellte Fragen
Ist die Lektion „Trace-Logging für Agentenschritte“ kostenlos?
Ja — der vollständige Text von „Trace-Logging für Agentenschritte“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des AI Agents-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der AI Agents-Kurs umfasst insgesamt 4 Lektionen.
Was lerne ich in „Trace-Logging für Agentenschritte“?
Jeden Denkschritt, Tool-Aufruf und jedes Ergebnis zur nachträglichen Analyse protokollieren. Du übst AI Agents mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.
Brauche ich Erfahrung, um AI Agents zu starten?
Keine Vorkenntnisse erforderlich. AI Agents auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 2 von 4.
Wie lange dauert die Lektion „Trace-Logging für Agentenschritte“?
Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.
Kann ich in dieser AI Agents-Lektion Code schreiben und ausführen?
Ja. Jede AI Agents-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.
Alle Lektionen in diesem Kurs
- Häufige Fehler in Agentenschleifen
- Trace-Logging für Agentenschritte
- Endlosschleifen erkennen und unterbrechen
- Techniken zum schrittweisen Debuggen