0Pricing
AI Agents · Leçon

Techniques de débogage pas à pas

Ajoutez des points d’arrêt, des affichages intermédiaires et utilisez le débogueur dans le code de l’agent.

Techniques de débogage pas à pas est une leçon AI Agents gratuite sur CoddyKit. Ceci est la leçon 4 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage AI Agents, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours AI Agents comprend 4 leçons au total.

Le débogage des agents diffère de celui des fonctions

Une fonction possède une entrée et une sortie claires. Un agent possède une boucle avec des appels au LLM, des exécutions d’outils et des modifications de l’historique, autant d’éléments qui peuvent mal fonctionner de manière subtile.

Le débogage pas à pas vous permet de faire une pause à chaque étape, d’examiner l’état de l’agent et de comprendre exactement ce qui s’est mal passé.

Le débogueur intégré de Python : pdb

Le débogueur Python pdb vous permet de mettre l’exécution en pause, d’examiner les variables et de parcourir le code ligne par ligne. Insérez import pdb; pdb.set_trace() à n’importe quel endroit de la boucle de l’agent pour ouvrir une session de débogage interactive.

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 et versions ultérieures : la fonction breakpoint()

Python 3.7 et les versions ultérieures intègrent la fonction breakpoint() : elle est plus claire que import pdb; pdb.set_trace(). Elle respecte également la variable d’environnement PYTHONBREAKPOINT, qui vous permet de remplacer le débogueur par un autre.

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

Référence des commandes de pdb

Les commandes pdb les plus importantes pour déboguer les boucles d’agent :

  • n — ligne suivante (sans entrer dans la fonction)
  • s — entrer dans l’appel de fonction
  • c — continuer jusqu’au prochain point d’arrêt
  • p expr — afficher la valeur de l’expression
  • pp expr — afficher avec une mise en forme lisible (pour les dictionnaires et les listes)
  • l — afficher le code source autour de la ligne actuelle
  • q — quitter le débogueur
# 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')

Points d’arrêt conditionnels

Arrêtez l’exécution uniquement lorsqu’une condition précise est vraie — par exemple, uniquement lorsqu’un outil particulier est sélectionné ou lorsque le nombre d’étapes est élevé. Cela évite de s’arrêter à chaque itération d’une longue boucle.

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})

Débogueur de VS Code pour le code d’agent

Le débogueur Python de VS Code offre une expérience visuelle de parcours pas à pas avec des panneaux d’inspection des variables, des piles d’appels et des expressions surveillées. Configurez un launch.json pour exécuter votre agent en mode débogage.

# .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')

Ajouter une option --debug à votre CLI

Ajoutez une option --debug à la CLI de votre agent. Lorsqu’elle est activée, elle permet une journalisation détaillée, affiche chaque étape et ouvre éventuellement pdb en cas d’erreur. Vous pouvez ainsi déboguer sans modifier le code source.

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

Parcours pas à pas en mode détaillé

Un mode détaillé affiche des informations précises sur chaque étape dans la sortie standard, ce qui vous permet de suivre l’exécution de l’agent sans débogueur. Ajoutez une option verbose=True à votre boucle d’agent.

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}

Débogage post-mortem avec pdb.post_mortem()

Lorsqu’un agent s’arrête brutalement à cause d’une exception, pdb.post_mortem() ouvre le débogueur exactement à l’endroit de l’échec, tout en conservant la pile d’appels. Cette fonctionnalité est extrêmement utile pour comprendre les plantages sans devoir les reproduire.

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

Inspecter l’historique des messages dans le débogueur

L’élément le plus utile à inspecter lors du débogage d’un agent est l’historique de la conversation. Utilisez la commande pp de pdb pour l’afficher avec une mise en forme lisible, ou parcourez-le pour comprendre ce que l’agent a vu jusqu’à présent.

# 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')

Simulation pas à pas sans appels au LLM

Pour itérer rapidement, créez un mode de simulation dans lequel vous indiquez manuellement l’action effectuée par l’agent à chaque étape. Cela vous permet de tester l’exécution de vos outils et la gestion de l’historique sans effectuer d’appels à l’API du LLM.

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.'}
# ])

Vérification des connaissances : débogage pas à pas

Testez votre compréhension des techniques de débogage du code d’agent.

Récapitulatif : techniques de débogage pas à pas

Vous disposez désormais d’une boîte à outils complète pour déboguer les boucles d’agent :

  • Utilisez breakpoint() (Python 3.7+) ou import pdb; pdb.set_trace() pour le débogage interactif
  • Utilisez des points d’arrêt conditionnels pour vous arrêter uniquement lorsqu’un comportement suspect se produit
  • Configurez VS Code launch.json pour déboguer avec une interface graphique
  • Ajoutez les options --debug et --pdb-on-error à la CLI pour déboguer à la demande
  • Utilisez pdb.post_mortem() pour inspecter les plantages après leur apparition
  • Créez un mode de simulation pour tester la logique des outils sans appels au LLM
  • Utilisez le mode détaillé pour suivre l’exécution sans la mettre en pause

Questions Fréquemment Posées

La leçon « Techniques de débogage pas à pas » est-elle gratuite ?

Oui — le texte complet de « Techniques de débogage pas à pas » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours AI Agents, passe à CoddyKit PRO. Le cours AI Agents comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Techniques de débogage pas à pas » ?

Ajoutez des points d’arrêt, des affichages intermédiaires et utilisez le débogueur dans le code de l’agent. Tu pratiques AI Agents avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer AI Agents ?

Aucune expérience préalable n'est requise. AI Agents sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 4 sur 4.

Combien de temps prend la leçon « Techniques de débogage pas à pas » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon AI Agents ?

Oui. Chaque leçon AI Agents inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

  1. Échecs courants des boucles d’agents
  2. Journalisation des traces des étapes d’un agent
  3. Détecter et interrompre les boucles infinies
  4. Techniques de débogage pas à pas
← Retour à AI Agents