0Pricing
AI Agents · Lezione

Tecniche di debugging passo passo

Aggiunta di breakpoint e stampe intermedie e utilizzo del debugger nel codice degli agenti

Tecniche di debugging passo passo è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 4 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.

Il debugging degli agenti è diverso dal debugging delle funzioni

Una funzione ha un input e un output chiari. Un agente ha un ciclo con chiamate all'LLM, esecuzioni di strumenti e modifiche alla cronologia: tutti elementi che possono generare errori in modi sottili.

Il debugging passo passo consente di mettere in pausa ogni passaggio, esaminare lo stato dell'agente e capire esattamente che cosa è andato storto.

Il debugger integrato di Python: pdb

Il debugger di Python pdb consente di mettere in pausa l'esecuzione, esaminare le variabili e seguire il codice riga per riga. Inserisca import pdb; pdb.set_trace() in qualsiasi punto del ciclo dell'agente per avviare una sessione di debug interattiva.

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+: la funzione breakpoint()

Python 3.7+ include la funzione integrata breakpoint(), più pulita rispetto a import pdb; pdb.set_trace(). Inoltre rispetta la variabile d'ambiente PYTHONBREAKPOINT, che consente di sostituire il debugger con un altro.

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

Riferimento ai comandi pdb

I comandi pdb più importanti per il debugging dei cicli dell'agente:

  • n — riga successiva (esegue un passo oltre)
  • s — entra nella chiamata di funzione
  • c — continua fino al breakpoint successivo
  • p expr — stampa il valore dell'espressione
  • pp expr — stampa in formato leggibile (per dizionari/liste)
  • l — elenca il codice sorgente attorno alla riga corrente
  • q — esce dal debugger
# 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')

Breakpoint condizionali

Si interrompa l'esecuzione solo quando una condizione specifica è vera, ad esempio solo quando viene selezionato uno strumento specifico o quando il numero di passi è elevato. In questo modo si evita di interrompere l'esecuzione a ogni iterazione di un ciclo lungo.

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

Debugger di VS Code per il codice dell'agente

Il debugger Python di VS Code offre un'esperienza visiva di esecuzione passo passo, con pannelli per l'ispezione delle variabili, stack delle chiamate ed espressioni da osservare. Configuri un launch.json per eseguire l'agente in modalità debug.

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

Aggiungere un flag --debug alla CLI

Aggiunga un flag --debug alla CLI dell'agente. Quando è impostato, abilita la registrazione dettagliata, stampa ogni passo e, facoltativamente, avvia pdb in caso di errore. In questo modo è possibile eseguire il debug senza modificare il codice sorgente.

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

Esecuzione passo passo in modalità verbose

Una modalità verbose stampa informazioni dettagliate su ogni passo su stdout, consentendo di tracciare l'esecuzione dell'agente senza un debugger. Aggiunga un flag verbose=True al ciclo dell'agente.

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}

Debug post-mortem con pdb.post_mortem()

Quando un agente si arresta a causa di un'eccezione, pdb.post_mortem() apre il debugger esattamente nel punto dell'errore, mantenendo lo stack delle chiamate. È estremamente utile per comprendere gli arresti anomali senza doverli riprodurre.

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

Ispezionare la cronologia dei messaggi nel debugger

Durante il debugging di un agente, la cosa più utile da ispezionare è la cronologia della conversazione. Utilizzi il comando pp di pdb per stamparla in un formato leggibile oppure la scorra per capire che cosa ha visto l'agente fino a quel momento.

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

Simulazione passo passo senza chiamate LLM

Per iterare rapidamente, crei una modalità di simulazione in cui specificare manualmente quale azione deve eseguire l'agente a ogni passo. In questo modo è possibile testare l'esecuzione degli strumenti e la gestione della cronologia senza effettuare chiamate alle API 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.'}
# ])

Verifica delle conoscenze: debugging passo passo

Verifichi la comprensione delle tecniche di debugging per il codice degli agenti.

Riepilogo: tecniche di debugging passo passo

Ora dispone di un set completo di strumenti per il debugging dei cicli dell'agente:

  • Utilizzi breakpoint() (Python 3.7+) oppure import pdb; pdb.set_trace() per il debugging interattivo
  • Utilizzi breakpoint condizionali per interrompere l'esecuzione solo quando si verifica qualcosa di sospetto
  • Configuri launch.json di VS Code per eseguire il debugging con un'interfaccia grafica
  • Aggiunga i flag CLI --debug e --pdb-on-error per eseguire il debugging su richiesta
  • Utilizzi pdb.post_mortem() per ispezionare gli arresti anomali dopo che si sono verificati
  • Crei una modalità di simulazione per testare la logica degli strumenti senza chiamate LLM
  • Utilizzi la modalità verbose per tracciare l'esecuzione senza metterla in pausa

Domande Frequenti

La lezione «Tecniche di debugging passo passo» è gratuita?

Sì — il testo completo di «Tecniche di debugging passo passo» è 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 «Tecniche di debugging passo passo»?

Aggiunta di breakpoint e stampe intermedie e utilizzo del debugger nel codice degli agenti 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 4 di 4.

Quanto tempo richiede la lezione «Tecniche di debugging passo passo»?

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

  1. Errori comuni nei cicli degli agenti
  2. Trace logging per i passaggi degli agenti
  3. Rilevamento e interruzione dei cicli infiniti
  4. Tecniche di debugging passo passo
← Torna a AI Agents