Protokollierung für KI-Agenten

IRC-Mania Die Seite rund um Sicherheit und Programmierung

Internet, Sicherheit , Internet Relay Chat

Gesponsert

Was dieser Artikel über Protokollierung für KI-Agenten behandelt

• Wie Du Protokollierung für KI-Agenten einrichtest.
• Welche Ereignisse protokolliert werden sollten: Tool-Aufrufe, Modell-Antworten, Fehler, Entscheidungen.
• Wie Du strukturiertes Logging, Audit Trails und Compliance umsetzt.
• Praxisbeispiele für Logging mit Python, JSON-Logs und Log-Analyse.
• Best Practices für Sicherheit, Performance und Aufbewahrung.

Einleitung: Protokollierung für KI-Agenten verständlich erklärt

KI-Agenten treffen Entscheidungen, rufen Tools auf, verarbeiten Daten. Wenn etwas schiefgeht, musst Du nachvollziehen können, was passiert ist. Protokollierung ist die Aufzeichnung aller Agenten-Aktionen, damit Du Fehler analysieren, Compliance nachweisen und die Qualität verbessern kannst.

Dieser Artikel richtet sich an Entwicklerinnen und Entwickler, die KI-Agenten bauen und Protokollierung einrichten wollen. Du solltest verstehen, was KI-Agenten sind und wie man sie lokal mit Ollama betreibt. Grundlagen der Python-Programmierung findest Du auf IRC-Coding.de.

Warum brauche ich Protokollierung für KI-Agenten?

Stell Dir vor, Dein Agent hat eine E-Mail gelöscht, die er nicht löschen sollte. Warum hat er das getan? Welche Tools hat er aufgerufen? Welches Modell hat welche Entscheidung getroffen? Ohne Protokollierung kannst Du das nicht nachvollziehen. Mit Protokollierung siehst Du jeden Schritt, jede Entscheidung, jeden Tool-Aufruf.

Protokollierung ist besonders wichtig, wenn Agenten kritische Aktionen ausführen, wenn Compliance-Nachweise nötig sind (DSGVO, ISO 27001) oder wenn Du Agenten-Verhalten systematisch verbessern willst.

Protokollierung für KI-Agenten kurz erklärt

Protokollierung ist die Aufzeichnung aller Agenten-Aktionen in strukturierten Logs. Jeder Tool-Aufruf, jede Modell-Antwort, jede Entscheidung, jeder Fehler wird mit Zeitstempel, Kontext und Ergebnis protokolliert. Die Logs können später analysiert werden, um Fehler zu finden, Compliance nachzuweisen und Qualität zu verbessern.

Der Kerngedanke lautet: Ohne Logs keine Nachvollziehbarkeit, ohne Nachvollziehbarkeit kein Vertrauen.

Für wen ist dieser Artikel gedacht?

• Entwicklerinnen und Entwickler, die KI-Agenten bauen und Protokollierung einrichten.
• Systemadministratoren, die Agenten betreuen und Fehler analysieren.
• Compliance-Verantwortliche, die Audit-Trails brauchen.
• Teams, die Agenten-Qualität systematisch verbessern wollen.

Vorkenntnisse in Python, KI-Agenten und Ollama sind erforderlich.

Wichtige Begriffe rund um Protokollierung

• Protokollierung - Aufzeichnung von Ereignissen. Wann nützlich: für Nachvollziehbarkeit.
• Audit Log - Protokoll aller sicherheitsrelevanten Aktionen. Wann nützlich: für Compliance.
• Strukturiertes Logging - Logs im JSON-Format. Wann nützlich: für maschinelle Auswertung.
• Log-Level - Priorität von Logs (DEBUG, INFO, WARNING, ERROR). Wann nützlich: für Filterung.
• Tool-Aufruf - Agent ruft ein Tool auf. Wann nützlich: kritisch für Audit.
• KI-Agenten - Programme, die eigenständig Aufgaben lösen. Wann nützlich: was protokolliert wird.
• Ollama - Lokaler Modellserver. Wann nützlich: Backend, dessen Aufrufe protokolliert werden.
• Function Calling - Strukturierte KI-Antworten. Wann nützlich: was protokolliert wird.
• Compliance - Einhaltung von Regeln. Wann nützlich: Grund für Audit Logs.

Was sollte protokolliert werden?

Modell-Aufrufe

Jeder Aufruf des Sprachmodells sollte protokolliert werden:

import logging
import json
from datetime import datetime

logger = logging.getLogger("agent")
logger.setLevel(logging.INFO)

def log_model_call(model, messages, response, duration_ms):
    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "type": "model_call",
        "model": model,
        "input_messages": len(messages),
        "input_tokens": count_tokens(messages),
        "output_tokens": count_tokens(response),
        "duration_ms": duration_ms,
        "status": "success"
    }
    logger.info(json.dumps(log_entry))

Tool-Aufrufe

Jeder Tool-Aufruf ist kritisch für Audit:

def log_tool_call(tool_name, parameters, result, duration_ms, status):
    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "type": "tool_call",
        "tool": tool_name,
        "parameters": parameters,
        "result_summary": str(result)[:200],
        "duration_ms": duration_ms,
        "status": status
    }
    logger.info(json.dumps(log_entry))

Entscheidungen

Jede Entscheidung des Agenten:

def log_decision(decision_type, reasoning, action):
    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "type": "decision",
        "decision_type": decision_type,
        "reasoning": reasoning,
        "action": action
    }
    logger.info(json.dumps(log_entry))

Fehler

Jeder Fehler mit Kontext:

def log_error(error_type, message, context):
    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "type": "error",
        "error_type": error_type,
        "message": message,
        "context": context
    }
    logger.error(json.dumps(log_entry))

Strukturiertes Logging mit Python

Setup

import logging
import json
from datetime import datetime

class JSONFormatter(logging.Formatter):
    def format(self, record):
        log_entry = {
            "timestamp": datetime.now().isoformat(),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage()
        }
        if hasattr(record, "extra"):
            log_entry.update(record.extra)
        return json.dumps(log_entry)

# Logger konfigurieren
logger = logging.getLogger("agent")
logger.setLevel(logging.DEBUG)

# File Handler
file_handler = logging.FileHandler("/var/log/agent.log")
file_handler.setFormatter(JSONFormatter())
logger.addHandler(file_handler)

# Console Handler
console_handler = logging.StreamHandler()
console_handler.setFormatter(JSONFormatter())
logger.addHandler(console_handler)

Verwendung

# Modell-Aufruf protokollieren
logger.info("Modell aufgerufen", extra={
    "type": "model_call",
    "model": "llama3.1",
    "duration_ms": 1234
})

# Tool-Aufruf protokollieren
logger.info("Tool aufgerufen", extra={
    "type": "tool_call",
    "tool": "send_email",
    "parameters": {"to": "user@example.com"}
})

# Fehler protokollieren
logger.error("Tool fehlgeschlagen", extra={
    "type": "error",
    "tool": "send_email",
    "error": "SMTP timeout"
})

Audit-Trail-Implementierung

Ein Audit-Trail ist eine spezielle Form der Protokollierung, die alle sicherheitsrelevanten Aktionen aufzeichnet.

class AuditLogger:
    def __init__(self, log_file="/var/log/agent_audit.log"):
        self.logger = logging.getLogger("audit")
        self.logger.setLevel(logging.INFO)
        handler = logging.FileHandler(log_file)
        handler.setFormatter(JSONFormatter())
        self.logger.addHandler(handler)

    def log_action(self, agent_id, action, target, parameters, result, user_id=None):
        entry = {
            "timestamp": datetime.now().isoformat(),
            "agent_id": agent_id,
            "user_id": user_id,
            "action": action,
            "target": target,
            "parameters": parameters,
            "result": result,
            "status": "success" if result.get("success") else "failed"
        }
        self.logger.info(json.dumps(entry))

# Verwendung
audit = AuditLogger()
audit.log_action(
    agent_id="email_agent_1",
    action="send_email",
    target="user@example.com",
    parameters={"subject": "Re: Support-Anfrage"},
    result={"success": True, "message_id": "abc123"},
    user_id="user_42"
)

Praxisbeispiel: Vollständiger Agent mit Logging

class LoggedAgent:
    def __init__(self, model="llama3.1"):
        self.model = model
        self.logger = logging.getLogger("agent")
        self.audit = AuditLogger()

    def call_model(self, messages):
        start = time.time()
        try:
            response = requests.post(
                "http://localhost:11434/api/chat",
                json={"model": self.model, "messages": messages, "stream": False}
            ).json()
            duration = (time.time() - start) * 1000

            self.logger.info("Modell aufgerufen", extra={
                "type": "model_call",
                "model": self.model,
                "duration_ms": duration,
                "input_messages": len(messages),
                "status": "success"
            })
            return response
        except Exception as e:
            duration = (time.time() - start) * 1000
            self.logger.error("Modell-Aufruf fehlgeschlagen", extra={
                "type": "error",
                "model": self.model,
                "duration_ms": duration,
                "error": str(e)
            })
            raise

    def call_tool(self, tool_name, parameters):
        start = time.time()
        try:
            result = execute_tool(tool_name, parameters)
            duration = (time.time() - start) * 1000

            self.logger.info("Tool aufgerufen", extra={
                "type": "tool_call",
                "tool": tool_name,
                "duration_ms": duration,
                "status": "success"
            })

            self.audit.log_action(
                agent_id=self.agent_id,
                action=tool_name,
                target=parameters.get("target", "unknown"),
                parameters=parameters,
                result={"success": True, "data": str(result)[:200]}
            )
            return result
        except Exception as e:
            duration = (time.time() - start) * 1000
            self.logger.error("Tool fehlgeschlagen", extra={
                "type": "error",
                "tool": tool_name,
                "duration_ms": duration,
                "error": str(e)
            })
            self.audit.log_action(
                agent_id=self.agent_id,
                action=tool_name,
                target=parameters.get("target", "unknown"),
                parameters=parameters,
                result={"success": False, "error": str(e)}
            )
            raise

Log-Analyse

Logs durchsuchen

# Alle Fehler
jq 'select(.level == "ERROR")' /var/log/agent.log

# Alle Tool-Aufrufe
jq 'select(.type == "tool_call")' /var/log/agent.log

# Alle fehlgeschlagenen Tool-Aufrufe
jq 'select(.type == "tool_call" and .status == "failed")' /var/log/agent.log

# Langsame Modell-Aufrufe (>5 Sekunden)
jq 'select(.type == "model_call" and .duration_ms > 5000)' /var/log/agent.log

Mit Python analysieren

import json

def analyze_logs(log_file):
    with open(log_file) as f:
        logs = [json.loads(line) for line in f]

    # Statistiken
    total_calls = len([l for l in logs if l.get("type") == "model_call"])
    failed_tools = len([l for l in logs if l.get("type") == "tool_call" and l.get("status") == "failed"])
    errors = len([l for l in logs if l.get("level") == "ERROR"])

    # Durchschnittliche Modell-Dauer
    model_durations = [l["duration_ms"] for l in logs if l.get("type") == "model_call"]
    avg_duration = sum(model_durations) / len(model_durations) if model_durations else 0

    return {
        "total_model_calls": total_calls,
        "failed_tool_calls": failed_tools,
        "total_errors": errors,
        "avg_model_duration_ms": avg_duration
    }

Log-Rotation

Logs können groß werden. Nutze Log-Rotation:

import logging.handlers

handler = logging.handlers.RotatingFileHandler(
    "/var/log/agent.log",
    maxBytes=100*1024*1024,  # 100 MB
    backupCount=5
)
handler.setFormatter(JSONFormatter())
logger.addHandler(handler)

Sicherheitshinweise

• Keine sensiblen Daten in Logs: Protokolliere keine Passwörter, API-Keys oder sensible Nutzerdaten.
• Log-Schutz: Schütze Logs vor Manipulation (nur anhängen, nicht überschreiben).
• Aufbewahrung: Definiere Aufbewahrungsfristen (z.B. 90 Tage für Audit Logs).
• Zugriffskontrolle: Nur autorisierte Personen dürfen Logs lesen.
• Anonymisierung: Anonymisiere personenbezogene Daten in Logs.
• Siehe: Audit Logging, Datenschutz.

Typische Stolpersteine

• Zu viele Logs: DEBUG-Logs in Produktion erzeugen riesige Dateien. Nutze Log-Level.
• Keine strukturierten Logs: Unstrukturierte Logs sind schwer auszuwerten. Nutze JSON.
• Sensible Daten in Logs: Passwörter oder API-Keys in Logs sind ein Sicherheitsrisiko.
• Keine Log-Rotation: Logs wachsen unbegrenzt. Nutze RotatingFileHandler.
• Keine Fehler-Logs: Wenn nur Success-Logs geschrieben werden, kannst Du Fehler nicht analysieren.
• Keine Zeitstempel: Ohne Zeitstempel kannst Du Ereignisse nicht korrelieren.

Weiterführende Links und Infos zu Protokollierung

• KI-Agenten Grundlagen - Was KI-Agenten sind.
• KI-Agenten mit Ollama - Agenten lokal betreiben.
• Audit Logging - Sicherheit und Nachvollziehbarkeit.
• Datenschutz - DSGVO und KI.
• Menschliche Freigabe - Human-in-the-Loop.
• Guardrails konfigurieren - Guardrails für Agenten.
• E-Mail-Automatisierung - Praxisbeispiel mit Logging.

Key Takeaways:

• Protokollierung ist die Aufzeichnung aller Agenten-Aktionen.
• Protokolliere: Modell-Aufrufe, Tool-Aufrufe, Entscheidungen, Fehler.
• Nutze strukturiertes Logging (JSON) für maschinelle Auswertung.
• Audit-Trails für Compliance und Sicherheit.
• Keine sensiblen Daten in Logs, Log-Rotation nutzen.

FAQ: Protokollierung für KI-Agenten - Typische Fragen

Quellen und weiterführende Literatur

• Python Logging - Offizielle Python-Logging-Docs.
• jq - JSON-Processor für Logs.
• ELK Stack - Log-Analyse-Plattform.
• Grafana Loki - Log-Aggregation.

Premium VPS Hosting

Schnelle und sichere VPS Server

Gesponsert