AI-agenter · Lektion

Teknikker til trinvis debugging

Tilføj breakpoints og mellemliggende udskrifter, og brug debuggeren i agentkode.

Lektion 4 af 413 trin

Teknikker til trinvis debugging er en gratis AI-agenter-lektion på CoddyKit. Dette er lektion 4 af 4. Du kan læse hele lektionen gratis nedenfor — og derefter øve dig praktisk i browseren med en indbygget kodeeditor og en AI-vejleder, der er tilgængelig døgnet rundt. Den er en del af læringsforløbet i AI-agenter, og dine fremskridt synkroniseres på tværs af nettet og CoddyKit-appen. AI-agenter-kurset indeholder 4 lektioner i alt.

Fejlfinding af agenter er anderledes end fejlfinding af funktioner

En funktion har tydelige inddata og uddata. En agent har en løkke med LLM-kald, værktøjsudførelser og ændringer i historikken — og alt dette kan gå galt på subtile måder.

Trinvis fejlfinding giver dig mulighed for at sætte udførelsen på pause ved hvert trin, undersøge agentens tilstand og forstå præcis, hvad der gik galt.

Pythons indbyggede fejlsøger: pdb

Python-fejlsøgeren pdb lader dig sætte udførelsen på pause, undersøge variabler og gennemgå kode linje for linje. Indsæt import pdb; pdb.set_trace() et hvilket som helst sted i agentløkken for at åbne en interaktiv fejlfindingssession.

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

Python 3.7+ indeholder den indbyggede funktion breakpoint() — den er renere end import pdb; pdb.set_trace(). Den respekterer også miljøvariablen PYTHONBREAKPOINT, som lader dig skifte til en anden fejlsøger.

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

Reference over pdb-kommandoer

De vigtigste pdb-kommandoer til fejlsøgning af agentløkker:

n — næste linje (spring over)
s — gå ind i funktionskaldet
c — fortsæt indtil næste breakpoint
p expr — udskriv udtrykkets værdi
pp expr — udskriv i et læsevenligt format (for dicts/lister)
l — vis kildekoden omkring den aktuelle linje
q — afslut fejlsøgeren

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

Betingede breakpoints

Stop kun, når en bestemt betingelse er sand — for eksempel kun når et bestemt værktøj er valgt, eller når antallet af trin er højt. Så undgår du at stoppe ved hver gennemløb af en lang løkke.

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-fejlsøger til agentkode

VS Code Python-fejlsøgeren giver dig mulighed for visuelt at gennemgå koden trin for trin med paneler til inspektion af variabler, kaldestakke og overvågningsudtryk. Konfigurer en launch.json for at køre din agent i fejlsøgningstilstand.

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

Tilføj et --debug-flag til din CLI

Tilføj et --debug-flag til din agent-CLI. Når flaget er sat, aktiverer det detaljeret logning, udskriver hvert trin og åbner valgfrit pdb ved fejl. På den måde kan du fejlsøge uden at ændre kildekoden.

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

Gennemgå koden trin for trin i detaljeret tilstand

En detaljeret tilstand udskriver udførlige oplysninger om hvert trin til stdout, så du kan følge agentens kørsel uden en fejlsøger. Tilføj et verbose=True-flag til din agentløkke.

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}

Efterfølgende fejlsøgning med pdb.post_mortem()

Når en agent går ned med en undtagelse, åbner pdb.post_mortem() fejlsøgeren på det præcise fejlsted, mens kaldestakken er bevaret. Det er uvurderligt, når du skal forstå nedbrud uden først at skulle genskabe dem.

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

Undersøg meddelelseshistorikken i fejlsøgeren

Det mest nyttige at undersøge under fejlsøgning af en agent er samtalehistorikken. Brug pdb's pp-kommando til at udskrive den i et læsevenligt format, eller gennemgå den for at forstå, hvad agenten har set indtil videre.

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

Gennemgangssimulering uden LLM-kald

Hvis du vil kunne iterere hurtigt, kan du opbygge en simuleringstilstand, hvor du manuelt angiver, hvilken handling agenten udfører ved hvert trin. Så kan du afprøve udførelsen af dine værktøjer og håndteringen af historikken uden at foretage LLM API-kald.

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

Videnstest: Fejlsøgning trin for trin

Afprøv din forståelse af fejlsøgningsteknikker til agentkode.

Besvar den i den interaktive lektion

Opsummering: Fejlsøgningsteknikker trin for trin

Du har nu et komplet fejlsøgningsværktøjssæt til agentløkker:

Brug breakpoint() (Python 3.7+) eller import pdb; pdb.set_trace() til interaktiv fejlsøgning
Brug betingede breakpoints til kun at stoppe, når der sker noget mistænkeligt
Konfigurer VS Code launch.json til fejlsøgning med en grafisk brugerflade
Tilføj CLI-flaggene --debug og --pdb-on-error til fejlsøgning efter behov
Brug pdb.post_mortem() til at undersøge nedbrud, efter at de er sket
Opbyg en simuleringstilstand, så du kan afprøve værktøjslogik uden LLM-kald
Brug detaljeret tilstand til at følge kørsel uden at sætte den på pause

Gratis at komme i gang

Lær AI-agenter med en AI-underviser — gratis

Skriv og kør rigtig kode i din browser, få øjeblikkelig hjælp fra en AI-underviser døgnet rundt, og fortsæt, hvor du slap, på web eller i appen.

Kurser: 60
Lektioner: 239

Start gratis Se hele kurset

Ofte stillede spørgsmål

Er lektionen “Teknikker til trinvis debugging” gratis?

Ja — hele teksten til “Teknikker til trinvis debugging” kan læses gratis her på nettet. Hvis du vil øve dig interaktivt med en indbygget kodeeditor og en AI-vejleder døgnet rundt og få adgang til resten af AI-agenter-kurset, skal du opgradere til CoddyKit PRO. AI-agenter-kurset indeholder 4 lektioner i alt.

Hvad lærer jeg i “Teknikker til trinvis debugging”?

Tilføj breakpoints og mellemliggende udskrifter, og brug debuggeren i agentkode. Du øver dig i AI-agenter med praktisk kode, som du kører direkte i browseren, og en AI-vejleder døgnet rundt besvarer dine spørgsmål, mens du arbejder dig gennem lektionen.

Skal jeg have erfaring for at begynde på AI-agenter?

Der kræves ingen tidligere erfaring. AI-agenter på CoddyKit er tilrettelagt for både begyndere og øvede, så du kan starte her eller fra begyndelsen og lære i dit eget tempo. Dette er lektion 4 af 4.

Hvor lang tid tager lektionen “Teknikker til trinvis debugging”?

De fleste CoddyKit-lektioner tager cirka 5–10 minutter. Hver lektion er kort og interaktiv, så du gør løbende fremskridt og kan fortsætte, hvor du slap – på både web og app.

Kan jeg skrive og køre kode i denne AI-agenter-lektion?

Ja. Alle AI-agenter-lektioner har en indbygget kodeeditor, så du kan skrive og køre rigtig kode direkte i din browser og få øjeblikkelig feedback fra AI – uden lokal opsætning.

Alle lektioner i dette kursus

Almindelige fejl i agentloops
Trace-logging af agenttrin
Registrering og afbrydelse af uendelige loops
Teknikker til trinvis debugging

← Tilbage til AI-agenter