PricingLoginStart free
AI Agents · Урок

Методы пошаговой отладки

Добавление точек останова и промежуточного вывода, а также использование отладчика в коде агента.

Урок 4 из 413 шагов

«Методы пошаговой отладки» — бесплатный урок AI Agents на CoddyKit. Это урок 4 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Agents, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Agents содержит 4 уроков всего.

Отладка агентов отличается от отладки функций

У функции есть чёткие входные и выходные данные. У агента есть цикл с вызовами LLM, выполнением инструментов и изменениями истории — всё это может приводить к незаметным сбоям.

Пошаговая отладка позволяет приостановиться на каждом шаге, проверить состояние агента и точно понять, что пошло не так.

Встроенный отладчик Python: pdb

Отладчик Python pdb позволяет приостанавливать выполнение, проверять переменные и пошагово просматривать код. Вставьте import pdb; pdb.set_trace() в любом месте цикла агента, чтобы перейти в интерактивный сеанс отладки.

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

Функция breakpoint() в Python 3.7 и более поздних версиях

В Python 3.7 и более поздних версиях появилась встроенная функция breakpoint() — более удобная, чем import pdb; pdb.set_trace(). Она также учитывает переменную окружения PYTHONBREAKPOINT, которая позволяет заменить отладчик на другой.

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

Наиболее важные команды pdb для отладки циклов агента:

  • n — следующая строка (переход через)
  • s — переход внутрь вызова функции
  • c — продолжение до следующей точки останова
  • p expr — вывод значения выражения
  • pp expr — вывод в удобном формате (для словарей и списков)
  • l — вывод исходного кода вокруг текущей строки
  • q — выход из отладчика
# 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')

Условные точки останова

Останавливайте выполнение только при истинности определенного условия — например, когда выбран конкретный инструмент или количество шагов стало большим. Это позволяет не останавливаться на каждой итерации длинного цикла.

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 для кода агента

Отладчик Python в VS Code обеспечивает визуальную пошаговую отладку с панелями просмотра переменных, стеками вызовов и выражениями для наблюдения. Настройте launch.json, чтобы запускать агента в режиме отладки.

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

Добавление флага --debug в CLI

Добавьте флаг --debug в CLI агента. Если этот флаг установлен, он включает подробное журналирование, выводит каждый шаг и при необходимости открывает pdb при возникновении ошибок. Это позволяет выполнять отладку без изменения исходного кода.

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

Пошаговое выполнение в подробном режиме

Подробный режим выводит подробную информацию о каждом шаге в стандартный вывод, позволяя отслеживать выполнение агента без отладчика. Добавьте флаг verbose=True в цикл агента.

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}

Посмертная отладка с помощью pdb.post_mortem()

Если агент завершается с исключением, pdb.post_mortem() открывает отладчик в точной точке сбоя, сохраняя стек вызовов. Это незаменимо для понимания причин сбоев без необходимости воспроизводить их.

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

Просмотр истории сообщений в отладчике

Во время отладки агента полезнее всего просматривать историю беседы. Используйте команду pp в pdb, чтобы вывести ее в удобном формате, или переберите ее, чтобы понять, что агент уже успел увидеть.

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

Пошаговая симуляция без вызовов LLM

Для быстрой итерации создайте режим симуляции, в котором Вы вручную задаете действие агента на каждом шаге. Это позволяет проверять выполнение инструментов и управление историей без вызовов 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.'}
# ])

Проверка знаний: пошаговая отладка

Проверьте, насколько хорошо Вы понимаете методы отладки кода агента.

Ответь в интерактивном уроке

Итоги: методы пошаговой отладки

Теперь у Вас есть полный набор средств для отладки циклов агента:

  • Используйте breakpoint() (Python 3.7+) или import pdb; pdb.set_trace() для интерактивной отладки
  • Используйте условные точки останова, чтобы останавливать выполнение только при возникновении подозрительной ситуации
  • Настройте VS Code launch.json для отладки с графическим интерфейсом
  • Добавьте флаги CLI --debug и --pdb-on-error для отладки по требованию
  • Используйте pdb.post_mortem(), чтобы просматривать сбои после их возникновения
  • Создайте режим симуляции для проверки логики инструментов без вызовов LLM
  • Используйте подробный режим для отслеживания выполнения без приостановки
Можно начать бесплатно

Изучай AI Agents с ИИ-репетитором — бесплатно

Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.

Курсы
60
Уроки
239
Начать учиться бесплатноПосмотреть полный курс

Часто задаваемые вопросы

Урок «Методы пошаговой отладки» бесплатный?

Да — полный текст урока «Методы пошаговой отладки» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Agents, подпишись на CoddyKit PRO. Курс AI Agents содержит 4 уроков всего.

Чему я научусь в уроке «Методы пошаговой отладки»?

Добавление точек останова и промежуточного вывода, а также использование отладчика в коде агента. Ты практикуешь AI Agents с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать AI Agents?

Предыдущий опыт не требуется. AI Agents на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 4 из 4.

Сколько времени занимает урок «Методы пошаговой отладки»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке AI Agents?

Да. Каждый урок AI Agents включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Распространённые сбои цикла агента
  2. Журналы трассировки шагов агента
  3. Обнаружение и остановка бесконечных циклов
  4. Методы пошаговой отладки
← Назад к AI Agents