0Pricing
AI Agents · Aula

Técnicas de depuração passo a passo

Adição de pontos de interrupção, impressões intermediárias e uso do depurador no código do agente.

Técnicas de depuração passo a passo é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.

Depurar Agentes é Diferente de Depurar Funções

Uma função tem uma entrada e uma saída claras. Um agente tem um ciclo com chamadas ao LLM, execuções de ferramentas e alterações no histórico — tudo isso pode dar errado de maneiras sutis.

A depuração passo a passo permite pausar em cada etapa, inspecionar o estado do agente e entender exatamente o que deu errado.

O Depurador Integrado do Python: pdb

O depurador do Python, pdb, permite pausar a execução, inspecionar variáveis e percorrer o código linha a linha. Insira import pdb; pdb.set_trace() em qualquer ponto do ciclo do agente para entrar em uma sessão interativa de depuração.

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+: A Função breakpoint()

O Python 3.7+ inclui a função integrada breakpoint() — mais simples que import pdb; pdb.set_trace(). Ela também respeita a variável de ambiente PYTHONBREAKPOINT, que permite substituir o depurador por outro.

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

Referência dos comandos do pdb

Os comandos mais importantes do pdb para depurar laços de agentes:

  • n — próxima linha (avançar sem entrar na chamada)
  • s — entrar na chamada de função
  • c — continuar até o próximo ponto de interrupção
  • p expr — imprimir o valor da expressão
  • pp expr — exibir de forma legível (para dicionários/listas)
  • l — listar o código-fonte ao redor da linha atual
  • q — sair do 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')

Pontos de interrupção condicionais

Interrompa somente quando uma condição específica for verdadeira — por exemplo, apenas quando uma determinada ferramenta for selecionada ou quando a contagem de etapas estiver alta. Isso evita interromper a execução a cada iteração de um laço longo.

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 do VS Code para código de agentes

O depurador de Python do VS Code oferece uma experiência visual de execução passo a passo, com painéis de inspeção de variáveis, pilhas de chamadas e expressões monitoradas. Configure um launch.json para executar seu agente no modo de depuração.

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

Adicionando um sinalizador --debug à sua CLI

Adicione um sinalizador --debug à CLI do seu agente. Quando ativado, ele habilita o registro detalhado, imprime cada etapa e, opcionalmente, entra no pdb quando ocorrem erros. Isso permite depurar sem modificar o código-fonte.

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

Executando passo a passo com um modo detalhado

Um modo detalhado imprime informações completas sobre cada etapa na saída padrão, permitindo rastrear a execução do agente sem um depurador. Adicione um sinalizador verbose=True ao laço do seu 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}

Depuração post-mortem com pdb.post_mortem()

Quando um agente falha com uma exceção, pdb.post_mortem() abre o depurador exatamente no ponto da falha, mantendo a pilha de chamadas preservada. Isso é extremamente útil para entender falhas sem precisar reproduzi-las.

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

Inspecionando o histórico de mensagens no depurador

O elemento mais útil para inspecionar durante a depuração de um agente é o histórico da conversa. Use o comando pp do pdb para exibi-lo de forma legível ou percorra o histórico para entender o que o agente viu até o 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')

Simulação passo a passo sem chamadas de LLM

Para iterar rapidamente, crie um modo de simulação no qual você especifique manualmente qual ação o agente executa em cada etapa. Isso permite testar a execução das suas ferramentas e o gerenciamento do histórico sem fazer chamadas à 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.'}
# ])

Verificação de conhecimento: depuração passo a passo

Teste sua compreensão das técnicas de depuração para código de agentes.

Recapitulação: técnicas de depuração passo a passo

Agora você dispõe de um conjunto completo de ferramentas de depuração para laços de agentes:

  • Use breakpoint() (Python 3.7+) ou import pdb; pdb.set_trace() para depuração interativa
  • Use pontos de interrupção condicionais para interromper somente quando algo suspeito acontecer
  • Configure o launch.json do VS Code para depurar com uma interface gráfica
  • Adicione os sinalizadores de CLI --debug e --pdb-on-error para depuração sob demanda
  • Use pdb.post_mortem() para inspecionar falhas depois que ocorrerem
  • Crie um modo de simulação para testar a lógica das ferramentas sem chamadas de LLM
  • Use o modo detalhado para rastrear a execução sem pausá-la

Perguntas Frequentes

A aula “Técnicas de depuração passo a passo” é grátis?

Sim — o texto completo de “Técnicas de depuração passo a passo” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.

O que vou aprender em “Técnicas de depuração passo a passo”?

Adição de pontos de interrupção, impressões intermediárias e uso do depurador no código do agente. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Agents?

Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Técnicas de depuração passo a passo”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Agents?

Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Falhas comuns em ciclos de agentes
  2. Registro de rastreamento das etapas do agente
  3. Detectando e interrompendo ciclos infinitos
  4. Técnicas de depuração passo a passo
← Voltar para AI Agents