0Pricing
AI Agents · Lekcja

Techniki debugowania krok po kroku

Dodawanie breakpointów, wyświetlanie wyników pośrednich i używanie debuggera w kodzie agenta.

Techniki debugowania krok po kroku to bezpłatna lekcja AI Agents na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej AI Agents, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs AI Agents zawiera 4 lekcji w sumie.

Debugowanie agentów różni się od debugowania funkcji

Funkcja ma jasno określone dane wejściowe i wyjściowe. Agent ma pętlę obejmującą wywołania LLM, wykonywanie narzędzi i modyfikacje historii — a wszystkie te elementy mogą subtelnie działać nieprawidłowo.

Debugowanie krokowe pozwala wstrzymać działanie na każdym kroku, sprawdzić stan agenta i dokładnie zrozumieć, co poszło nie tak.

Wbudowany debugger Pythona: pdb

Debugger Pythona pdb pozwala wstrzymywać wykonywanie, sprawdzać zmienne i przechodzić przez kod wiersz po wierszu. W dowolnym miejscu pętli agenta należy wstawić import pdb; pdb.set_trace(), aby przejść do interaktywnej sesji debugowania.

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

Python 3.7+ zawiera wbudowaną funkcję breakpoint() — jest ona bardziej przejrzysta niż import pdb; pdb.set_trace(). Uwzględnia również zmienną środowiskową PYTHONBREAKPOINT, która pozwala zastąpić ją innym debuggerem.

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

Dokumentacja poleceń pdb

Najważniejsze polecenia pdb do debugowania pętli agentów:

  • n — następny wiersz (krok bez wchodzenia do funkcji)
  • s — wejście do wywołania funkcji
  • c — kontynuowanie do następnego punktu przerwania
  • p expr — wyświetlenie wartości wyrażenia
  • pp expr — estetyczne wyświetlenie (słowników/list)
  • l — wyświetlenie kodu źródłowego wokół bieżącego wiersza
  • q — zakończenie debugera
# 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')

Warunkowe punkty przerwania

Przerywanie działania tylko wtedy, gdy określony warunek jest spełniony — na przykład tylko wtedy, gdy wybrane zostanie konkretne narzędzie lub liczba kroków będzie wysoka. Pozwala to uniknąć zatrzymywania programu przy każdej iteracji długiej pętli.

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

Debuger VS Code dla kodu agentów

Debuger języka Python w VS Code zapewnia wizualne wykonywanie kodu krok po kroku wraz z panelami inspekcji zmiennych, stosami wywołań i obserwowanymi wyrażeniami. Należy skonfigurować plik launch.json, aby uruchamiać agenta w trybie debugowania.

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

Dodawanie flagi --debug do interfejsu CLI

Należy dodać flagę --debug do interfejsu CLI agenta. Po jej ustawieniu włączane jest szczegółowe logowanie, wyświetlany jest każdy krok, a w razie błędów można opcjonalnie uruchomić pdb. Dzięki temu można debugować kod bez jego modyfikowania.

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

Wykonywanie krok po kroku w trybie szczegółowym

Tryb szczegółowy wyświetla na stdout dokładne informacje o każdym kroku, dzięki czemu można śledzić wykonanie agenta bez debugera. Należy dodać flagę verbose=True do pętli agenta.

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}

Debugowanie post-mortem za pomocą pdb.post_mortem()

Gdy agent zakończy działanie z powodu wyjątku, pdb.post_mortem() otwiera debuger dokładnie w miejscu wystąpienia błędu, z zachowanym stosem wywołań. Jest to niezwykle pomocne przy analizowaniu awarii bez konieczności ich odtwarzania.

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

Inspekcja historii wiadomości w debugerze

Najbardziej przydatną rzeczą do sprawdzenia podczas debugowania agenta jest historia konwersacji. Można użyć polecenia pp debugera pdb, aby ją estetycznie wyświetlić, albo iterować po niej, by zrozumieć, co agent dotychczas zobaczył.

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

Symulacja krok po kroku bez wywołań LLM

Aby szybko iterować, należy utworzyć tryb symulacji, w którym ręcznie określa się działanie agenta na każdym kroku. Pozwala to testować wykonywanie narzędzi i zarządzanie historią bez wykonywania wywołań 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.'}
# ])

Sprawdzenie wiedzy: debugowanie krok po kroku

Sprawdź swoją znajomość technik debugowania kodu agentów.

Podsumowanie: techniki debugowania krok po kroku

Masz już kompletny zestaw narzędzi do debugowania pętli agentów:

  • Używaj breakpoint() (Python 3.7+) lub import pdb; pdb.set_trace() do interaktywnego debugowania
  • Używaj warunkowych punktów przerwania, aby zatrzymywać program tylko wtedy, gdy wydarzy się coś podejrzanego
  • Skonfiguruj VS Code launch.json, aby debugować za pomocą interfejsu graficznego
  • Dodaj flagi CLI --debug i --pdb-on-error do debugowania na żądanie
  • Używaj pdb.post_mortem(), aby analizować awarie po ich wystąpieniu
  • Utwórz tryb symulacji do testowania logiki narzędzi bez wywołań LLM
  • Używaj trybu szczegółowego do śledzenia wykonania bez wstrzymywania programu

Często zadawane pytania

Czy lekcja „Techniki debugowania krok po kroku” jest bezpłatna?

Tak — pełny tekst „Techniki debugowania krok po kroku” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu AI Agents, przejdź na CoddyKit PRO. Kurs AI Agents zawiera 4 lekcji w sumie.

Co nauczysz się w „Techniki debugowania krok po kroku”?

Dodawanie breakpointów, wyświetlanie wyników pośrednich i używanie debuggera w kodzie agenta. Ćwiczysz AI Agents z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć AI Agents?

Nie wymagamy żadnego doświadczenia. AI Agents w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Techniki debugowania krok po kroku”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji AI Agents?

Tak. Każda lekcja AI Agents zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Typowe awarie pętli agenta
  2. Logowanie śledzenia kroków agenta
  3. Wykrywanie i przerywanie nieskończonych pętli
  4. Techniki debugowania krok po kroku
← Powrót do AI Agents