0Pricing
AI Agents · Lektion

Techniken zum schrittweisen Debuggen

Breakpoints und Ausgaben von Zwischenergebnissen hinzufügen und den Debugger im Agentencode verwenden.

Techniken zum schrittweisen Debuggen ist eine kostenlose AI Agents-Lektion auf CoddyKit. Dies ist Lektion 4 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.

Agenten zu debuggen unterscheidet sich vom Debuggen von Funktionen

Eine Funktion hat eine klare Eingabe und Ausgabe. Ein Agent hat eine Schleife mit LLM-Aufrufen, Werkzeugausführungen und Änderungen am Verlauf — all das kann auf subtile Weise fehlschlagen.

Mit schrittweisem Debugging können Sie bei jedem Schritt pausieren, den Zustand des Agenten untersuchen und genau verstehen, was schiefgelaufen ist.

Der integrierte Python-Debugger: pdb

Mit dem Python-Debugger pdb können Sie die Ausführung anhalten, Variablen untersuchen und den Code Zeile für Zeile durchgehen. Fügen Sie an einer beliebigen Stelle in der Agentenschleife import pdb; pdb.set_trace() ein, um eine interaktive Debugsitzung zu starten.

import pdb

def run_agent_loop(query: str):
    history = []
    for step in range(1, 21):
        action = decide_action(query, history)

        # Drop into debugger at step 3 to inspect state
        if step == 3:
            import pdb; pdb.set_trace()
            # At this point you can:
            # (Pdb) print(action)       -- inspect current action
            # (Pdb) print(history)      -- inspect full history
            # (Pdb) n                   -- next line
            # (Pdb) c                   -- continue execution
            # (Pdb) q                   -- quit

        result = execute_tool(action['tool'], action['args'])
        history.append({'tool': action['tool'], 'result': result})

Python 3.7+: Die Funktion breakpoint()

Python 3.7+ enthält die integrierte Funktion breakpoint() — sie ist übersichtlicher als import pdb; pdb.set_trace(). Sie berücksichtigt außerdem die Umgebungsvariable PYTHONBREAKPOINT, mit der Sie einen anderen Debugger einsetzen können.

def run_agent_loop(query: str):
    history = []
    for step in range(1, 21):
        action = decide_action(query, history)

        breakpoint()  # cleaner than pdb.set_trace()

        result = execute_tool(action['tool'], action['args'])
        history.append({'tool': action['tool'], 'result': result})

# Disable all breakpoints without changing code:
# PYTHONBREAKPOINT=0 python agent.py

# Use ipdb (better UI) instead:
# PYTHONBREAKPOINT=ipdb.set_trace python agent.py
# pip install ipdb

pdb-Befehlsreferenz

Die wichtigsten pdb-Befehle zum Debuggen von Agentenschleifen:

  • n — nächste Zeile (Step-over)
  • s — in den Funktionsaufruf hineinspringen
  • c — bis zum nächsten Haltepunkt fortfahren
  • p expr — Wert des Ausdrucks ausgeben
  • pp expr — formatiert ausgeben (für Dictionaries/Listen)
  • l — Quellcode rund um die aktuelle Zeile auflisten
  • q — den Debugger beenden
# Typical pdb debugging session for an agent loop:
# (Pdb) p step           -- print current step number: 3
# (Pdb) pp action        -- pretty-print the action dict
# {'type': 'tool', 'tool': 'search_web', 'args': {'query': 'Python docs'}}
# (Pdb) pp history       -- see full conversation so far
# (Pdb) p len(history)   -- count messages: 6
# (Pdb) n                -- execute next line
# (Pdb) p result         -- see tool result
# (Pdb) c                -- continue to next breakpoint
print('pdb lets you inspect agent state at any point in the loop')

Bedingte Haltepunkte

Halten Sie nur an, wenn eine bestimmte Bedingung wahr ist — beispielsweise nur dann, wenn ein bestimmtes Tool ausgewählt wurde oder die Schrittanzahl hoch ist. So vermeiden Sie, bei jeder Iteration einer langen Schleife anzuhalten.

def run_agent_loop(query: str):
    history = []
    for step in range(1, 21):
        action = decide_action(query, history)

        # Break only if the agent picks the wrong tool
        if action.get('tool') == 'calculate' and 'weather' in query.lower():
            breakpoint()  # This is suspicious — weather shouldn't use calculator

        # Break only if we're near the step limit
        if step >= 18:
            breakpoint()  # Why hasn't the agent concluded yet?

        result = execute_tool(action['tool'], action['args'])
        history.append({'tool': action['tool'], 'result': result})

VS-Code-Debugger für Agentencode

Der Python-Debugger von VS Code bietet eine visuelle Möglichkeit, den Code schrittweise zu durchlaufen, mit Panels zur Variableninspektion, Aufruf-Stacks und Watch-Ausdrücken. Konfigurieren Sie eine launch.json, um Ihren Agenten im Debug-Modus auszuführen.

# .vscode/launch.json
# {
#   'version': '0.2.0',
#   'configurations': [
#     {
#       'name': 'Debug Agent',
#       'type': 'python',
#       'request': 'launch',
#       'program': 'agent_cli.py',
#       'args': ['--query', 'What is the weather in Paris?'],
#       'env': {
#         'OPENAI_API_KEY': 'your-key',
#         'LOG_LEVEL': 'DEBUG'
#       },
#       'console': 'integratedTerminal'
#     }
#   ]
# }

# Set breakpoints by clicking the left margin in VS Code
# Press F5 to start debugging, F10 to step over, F11 to step into
print('VS Code debugger provides visual debugging with no code changes needed')

Ein <code>--debug</code>-Flag zu Ihrer CLI hinzufügen

Fügen Sie Ihrer Agenten-CLI ein --debug-Flag hinzu. Wenn es gesetzt ist, aktiviert es eine ausführliche Protokollierung, gibt jeden Schritt aus und wechselt bei Fehlern optional in pdb. So können Sie debuggen, ohne den Quellcode zu ändern.

import argparse
import logging

parser = argparse.ArgumentParser()
parser.add_argument('--query', required=True)
parser.add_argument('--debug', action='store_true', help='Enable step-by-step debugging output')
parser.add_argument('--pdb-on-error', action='store_true', help='Drop into pdb on any exception')
args = parser.parse_args()

if args.debug:
    logging.basicConfig(level=logging.DEBUG)
    print('[DEBUG MODE] Step-by-step output enabled')

try:
    result = run_agent(args.query, verbose=args.debug)
    print(result['answer'])
except Exception as e:
    if args.pdb_on_error:
        import pdb; pdb.post_mortem()  # debug the crash
    else:
        raise

Schrittweises Durchlaufen im ausführlichen Modus

Ein ausführlicher Modus gibt detaillierte Informationen zu jedem Schritt auf stdout aus. So können Sie die Ausführung des Agenten ohne Debugger nachvollziehen. Fügen Sie Ihrer Agentenschleife ein verbose=True-Flag hinzu.

import json

def run_agent(query: str, verbose: bool = False) -> dict:
    history = []

    for step in range(1, 21):
        action = decide_action(query, history)

        if verbose:
            print(f'\n--- Step {step} ---')
            print(f'Action type: {action["type"]}')
            if action['type'] == 'tool':
                print(f'Tool: {action["tool"]}')
                print(f'Args: {json.dumps(action["args"], indent=2)}')

        if action['type'] == 'final_answer':
            if verbose:
                print(f'\nFinal answer: {action["answer"]}')
            return {'status': 'ok', 'answer': action['answer']}

        result = execute_tool(action['tool'], action['args'])
        if verbose:
            print(f'Result: {str(result)[:200]}')
        history.append({'tool': action['tool'], 'result': result})

    return {'status': 'max_steps', 'answer': None}

Post-Mortem-Debugging mit pdb.post_mortem()

Wenn ein Agent mit einer Ausnahme abstürzt, öffnet pdb.post_mortem() den Debugger genau an der Fehlerstelle, wobei der Aufruf-Stack erhalten bleibt. Das ist äußerst hilfreich, um Abstürze zu verstehen, ohne sie reproduzieren zu müssen.

import pdb
import sys
import traceback

def run_agent_with_postmortem(query: str, debug: bool = False) -> dict:
    try:
        return run_agent(query)
    except Exception as e:
        if debug:
            print(f'\nAgent crashed: {e}')
            traceback.print_exc()
            print('\nDropping into post-mortem debugger...')
            pdb.post_mortem()  # opens debugger at the crash site
            return {'status': 'crashed', 'error': str(e)}
        else:
            raise

# Usage:
# python agent.py --query 'test' --pdb-on-error

Nachrichtenverlauf im Debugger untersuchen

Das Nützlichste, was Sie beim Debuggen eines Agenten untersuchen können, ist der Gesprächsverlauf. Verwenden Sie den pdb-Befehl pp, um ihn formatiert auszugeben, oder durchlaufen Sie ihn, um zu verstehen, was der Agent bisher gesehen hat.

# Inside a pdb session, common inspection commands:

# Print the full history:
# (Pdb) pp history

# Print only user and assistant messages:
# (Pdb) pp [m for m in history if m['role'] in ('user', 'assistant')]

# Count messages:
# (Pdb) p len(history)

# Find tool calls in history:
# (Pdb) pp [m for m in history if m.get('role') == 'tool']

# Print the last message:
# (Pdb) pp history[-1]

# Print total token estimate (rough):
# (Pdb) p sum(len(str(m)) for m in history)
print('History inspection is the key to understanding agent state')

Schrittweise Simulation ohne LLM-Aufrufe

Erstellen Sie für schnelle Iterationen einen Simulationsmodus, in dem Sie manuell festlegen, welche Aktion der Agent in jedem Schritt ausführt. So können Sie die Tool-Ausführung und die Verwaltung des Verlaufs testen, ohne LLM-API-Aufrufe auszuführen.

def run_agent_simulation(query: str, scripted_actions: list) -> dict:
    'Simulate agent steps without LLM calls, using pre-defined actions'
    history = []

    for step, action in enumerate(scripted_actions, 1):
        print(f'Step {step}: {action}')

        if action['type'] == 'final_answer':
            return {'status': 'ok', 'answer': action['answer'], 'steps': step}

        result = execute_tool(action['tool'], action['args'])
        print(f'  Result: {str(result)[:100]}')
        history.append({'tool': action['tool'], 'result': result})

    return {'status': 'script_exhausted', 'history': history}

# Test tool execution logic without any LLM:
# result = run_agent_simulation('test', [
#     {'type': 'tool', 'tool': 'search_web', 'args': {'query': 'Python'}},
#     {'type': 'final_answer', 'answer': 'Python is a programming language.'}
# ])

Wissenscheck: Schrittweises Debuggen

Testen Sie Ihr Verständnis der Debugging-Techniken für Agentencode.

Zusammenfassung: Techniken zum schrittweisen Debuggen

Sie verfügen nun über ein vollständiges Debugging-Werkzeugset für Agentenschleifen:

  • Verwenden Sie breakpoint() (Python 3.7+) oder import pdb; pdb.set_trace() für interaktives Debugging
  • Verwenden Sie bedingte Haltepunkte, um nur anzuhalten, wenn etwas Verdächtiges passiert
  • Konfigurieren Sie VS Code launch.json, um mit einer grafischen Benutzeroberfläche zu debuggen
  • Fügen Sie die CLI-Flags --debug und --pdb-on-error für Debugging auf Abruf hinzu
  • Verwenden Sie pdb.post_mortem(), um Abstürze nach ihrem Auftreten zu untersuchen
  • Erstellen Sie einen Simulationsmodus, um die Tool-Logik ohne LLM-Aufrufe zu testen
  • Verwenden Sie den ausführlichen Modus, um die Ausführung ohne Pausen nachzuverfolgen

Häufig gestellte Fragen

Ist die Lektion „Techniken zum schrittweisen Debuggen“ kostenlos?

Ja — der vollständige Text von „Techniken zum schrittweisen Debuggen“ 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 „Techniken zum schrittweisen Debuggen“?

Breakpoints und Ausgaben von Zwischenergebnissen hinzufügen und den Debugger im Agentencode verwenden. 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 4 von 4.

Wie lange dauert die Lektion „Techniken zum schrittweisen Debuggen“?

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

  1. Häufige Fehler in Agentenschleifen
  2. Trace-Logging für Agentenschritte
  3. Endlosschleifen erkennen und unterbrechen
  4. Techniken zum schrittweisen Debuggen
← Zurück zu AI Agents