0Pricing
AI Agents · Lección

Técnicas de depuración paso a paso

Añada puntos de interrupción, impresiones intermedias y use el depurador en el código del agente.

Técnicas de depuración paso a paso es una lección gratuita de AI Agents en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Agents, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Agents incluye 4 lecciones en total.

Depurar agentes es diferente de depurar funciones

Una función tiene una entrada y una salida claras. Un agente tiene un bucle con llamadas al LLM, ejecuciones de herramientas y modificaciones del historial, y cualquiera de estos elementos puede fallar de maneras sutiles.

La depuración paso a paso permite pausar cada paso, inspeccionar el estado del agente y comprender exactamente qué salió mal.

El depurador integrado de Python: pdb

El depurador de Python pdb permite pausar la ejecución, inspeccionar variables y recorrer el código línea por línea. Inserte import pdb; pdb.set_trace() en cualquier punto del bucle del agente para acceder a una sesión de depuración interactiva.

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 función breakpoint()

Python 3.7+ incluye la función integrada breakpoint(), más limpia que import pdb; pdb.set_trace(). También respeta la variable de entorno PYTHONBREAKPOINT, que permite cambiar a otro depurador.

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

Referencia de comandos de pdb

Los comandos de pdb más importantes para depurar bucles de agentes:

  • n — siguiente línea (pasar por encima)
  • s — entrar en la llamada a la función
  • c — continuar hasta el siguiente punto de interrupción
  • p expr — imprimir el valor de la expresión
  • pp expr — mostrar con formato legible (para diccionarios/listas)
  • l — listar el código fuente alrededor de la línea actual
  • q — salir del depurador
# 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')

Puntos de interrupción condicionales

Deténgase solo cuando se cumpla una condición específica; por ejemplo, cuando se seleccione una herramienta concreta o cuando el contador de pasos sea alto. Esto evita detenerse en cada iteración de un bucle largo.

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

Depurador de VS Code para código de agentes

El depurador de Python de VS Code ofrece una experiencia visual de ejecución paso a paso, con paneles de inspección de variables, pilas de llamadas y expresiones de inspección. Configure un launch.json para ejecutar su agente en modo de depuración.

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

Añadir una opción --debug a su CLI

Añada una opción --debug a la CLI de su agente. Cuando está activada, habilita un registro detallado, muestra cada paso y, opcionalmente, abre pdb cuando se producen errores. Esto le permite depurar sin modificar el código fuente.

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

Ejecución paso a paso con un modo detallado

Un modo detallado muestra información pormenorizada sobre cada paso en stdout, lo que le permite seguir la ejecución del agente sin utilizar un depurador. Añada una opción verbose=True al bucle de su 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}

Depuración post mortem con pdb.post_mortem()

Cuando un agente se bloquea debido a una excepción, pdb.post_mortem() abre el depurador exactamente en el punto del fallo, con la pila de llamadas conservada. Esto resulta muy útil para comprender los bloqueos sin tener que reproducirlos.

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

Inspección del historial de mensajes en el depurador

Lo más útil que puede inspeccionar durante la depuración de un agente es el historial de la conversación. Use el comando pp de pdb para mostrarlo con un formato legible o recórralo para comprender lo que el agente ha visto hasta el 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')

Simulación paso a paso sin llamadas al LLM

Para iterar rápidamente, cree un modo de simulación en el que especifique manualmente qué acción realiza el agente en cada paso. Esto le permite probar la ejecución de herramientas y la gestión del historial sin realizar llamadas a ninguna API de 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.'}
# ])

Comprobación de conocimientos: depuración paso a paso

Compruebe sus conocimientos sobre las técnicas de depuración de código de agentes.

Repaso: técnicas de depuración paso a paso

Ahora dispone de un conjunto completo de herramientas para depurar bucles de agentes:

  • Use breakpoint() (Python 3.7+) o import pdb; pdb.set_trace() para la depuración interactiva
  • Use puntos de interrupción condicionales para detenerse solo cuando ocurra algo sospechoso
  • Configure launch.json de VS Code para depurar mediante una interfaz gráfica
  • Añada las opciones --debug y --pdb-on-error a la CLI para depurar cuando sea necesario
  • Use pdb.post_mortem() para inspeccionar los bloqueos después de que ocurran
  • Cree un modo de simulación para probar la lógica de las herramientas sin realizar llamadas al LLM
  • Use el modo detallado para seguir la ejecución sin pausarla

Preguntas frecuentes

¿La lección «Técnicas de depuración paso a paso» es gratis?

Sí — el texto completo de «Técnicas de depuración paso a paso» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Agents, actualiza a CoddyKit PRO. El curso de AI Agents incluye 4 lecciones en total.

¿Qué aprenderé en «Técnicas de depuración paso a paso»?

Añada puntos de interrupción, impresiones intermedias y use el depurador en el código del agente. Practicas AI Agents con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar AI Agents?

No se requiere experiencia previa. AI Agents en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.

¿Cuánto tiempo toma la lección «Técnicas de depuración paso a paso»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de AI Agents?

Sí. Cada lección de AI Agents incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Fallos habituales en los bucles de agentes
  2. Registro de trazas para los pasos del agente
  3. Detección y ruptura de bucles infinitos
  4. Técnicas de depuración paso a paso
← Volver a AI Agents