Registro de rastreamento das etapas do agente
Registre cada etapa de raciocínio, chamada de ferramenta e resultado para análise posterior do incidente.
Registro de rastreamento das etapas do agente é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 2 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.
Por Que o Registro de Rastreamento é Essencial para Agentes
Os registros padrão da aplicação registram erros e eventos. Os registros de rastreamento do agente registram o raciocínio: o que o agente pensou em cada etapa, qual ferramenta escolheu, quais argumentos usou e o que a ferramenta retornou?
Sem o registro de rastreamento, depurar uma falha do agente é como diagnosticar um problema no carro sem nenhum painel — só é possível adivinhar.
Configurando o Módulo de Registro do Python
O módulo integrado de logging do Python é a ferramenta padrão. Configure-o no início do agente com um formato que inclua marca temporal, nível e mensagem. Use o nível DEBUG para dados de rastreamento — ele pode ser desativado em produção.
import logging
import sys
logging.basicConfig(
level=logging.DEBUG,
format='%(asctime)s [%(levelname)s] %(name)s: %(message)s',
datefmt='%H:%M:%S',
stream=sys.stdout
)
logger = logging.getLogger('myagent')
# Usage:
logger.debug('Step 1: reasoning started')
logger.info('Agent task completed in 5 steps')
logger.warning('Tool returned empty result')
logger.error('Failed to parse tool arguments')
# Output:
# 14:32:01 [DEBUG] myagent: Step 1: reasoning started
# 14:32:03 [INFO] myagent: Agent task completed in 5 stepsRegistrando Cada Etapa de Raciocínio
Registre os fatos principais no início de cada etapa: qual é o número da etapa, qual raciocínio o LLM produziu, qual ferramenta selecionou e quais argumentos passou. Isso cria um registro completo do processo de decisão do agente.
import logging
import json
logger = logging.getLogger('myagent')
def log_step(step: int, thought: str, tool_name: str, tool_args: dict):
logger.debug(
f'Step {step}: '
f'reasoning="{thought[:100]}" '
f'tool={tool_name} '
f'args={json.dumps(tool_args, ensure_ascii=False)[:200]}'
)
# Example usage in the agent loop:
# log_step(
# step=1,
# thought='I need to find the current weather in Tokyo',
# tool_name='get_weather',
# tool_args={'city': 'Tokyo', 'unit': 'celsius'}
# )
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
log_step(
step=1,
thought='I need to find the current weather in Tokyo',
tool_name='get_weather',
tool_args={'city': 'Tokyo', 'unit': 'celsius'}
)
Registrando Resultados de Ferramentas
Após cada chamada de ferramenta, registre se ela foi bem-sucedida e uma prévia do resultado. Registrar o resultado completo pode ser detalhado demais — trunque-o nos primeiros 200 caracteres para facilitar a leitura.
import logging
logger = logging.getLogger('myagent')
def log_tool_result(step: int, tool_name: str, result: str, success: bool):
status = 'OK' if success else 'ERROR'
preview = str(result)[:200].replace('\n', ' ')
logger.debug(
f'Step {step} result [{status}]: tool={tool_name} '
f'result_preview="{preview}"'
)
if not success:
logger.warning(f'Tool {tool_name} failed at step {step}')
# Log at the start of the step:
# log_step(step, thought, tool_name, tool_args)
# result = execute_tool(tool_name, tool_args)
# log_tool_result(step, tool_name, result, success=True)
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
log_tool_result(1, 'get_weather', '{"temp_c": 18, "condition": "cloudy"}', success=True)
log_tool_result(2, 'get_weather', 'Connection timed out', success=False)
Registro Estruturado com Formato JSON
Os registros em texto simples são fáceis de ler, mas difíceis de consultar. Os registros estruturados em JSON podem ser ingeridos por sistemas de agregação de registros (Datadog, Splunk, CloudWatch) para filtragem, painéis e alertas.
import logging
import json
import sys
class JSONFormatter(logging.Formatter):
def format(self, record: logging.LogRecord) -> str:
log_obj = {
'timestamp': self.formatTime(record),
'level': record.levelname,
'logger': record.name,
'message': record.getMessage()
}
# Add any extra fields attached to the log record
if hasattr(record, 'step'):
log_obj['step'] = record.step
if hasattr(record, 'tool'):
log_obj['tool'] = record.tool
return json.dumps(log_obj)
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(JSONFormatter())
logger = logging.getLogger('agent_trace')
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)
logger.setLevel(logging.DEBUG)
logger.debug('Step 3: tool=search_web', extra={'step': 3, 'tool': 'search_web'})
Registro com Campos Adicionais
Passe extra={} para uma chamada de registro a fim de anexar campos estruturados que possam ser usados por formatadores JSON ou agregadores de registros para filtragem e análise.
import logging
logger = logging.getLogger('agent_trace')
def log_step_structured(step: int, tool: str, thought: str, args: dict):
logger.debug(
f'Step {step}: tool={tool}',
extra={
'step': step,
'tool': tool,
'thought': thought[:200],
'tool_args': args
}
)
# If using a JSON formatter, this produces:
# {
# 'timestamp': '14:32:01',
# 'level': 'DEBUG',
# 'message': 'Step 3: tool=search_web',
# 'step': 3,
# 'tool': 'search_web',
# 'thought': 'I need to find recent news about...',
# 'args': {'query': 'AI news 2025'}
# }
if __name__ == '__main__':
import sys
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(logging.Formatter('%(message)s | step=%(step)s tool=%(tool)s'))
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)
log_step_structured(3, 'search_web', 'I need to find recent news about...', {'query': 'AI news 2025'})
Registrando em um Arquivo
Para agentes em produção, registre em um arquivo para análise posterior. Use RotatingFileHandler para limitar o tamanho do arquivo de registros e evitar o esgotamento do disco.
import logging
from logging.handlers import RotatingFileHandler
import sys
logger = logging.getLogger('myagent')
logger.setLevel(logging.DEBUG)
# Console handler — INFO and above
console = logging.StreamHandler(sys.stdout)
console.setLevel(logging.INFO)
console.setFormatter(logging.Formatter('%(message)s'))
# File handler — DEBUG and above, rotates at 10MB
file_handler = RotatingFileHandler(
'agent_trace.log',
maxBytes=10 * 1024 * 1024, # 10 MB
backupCount=3
)
file_handler.setLevel(logging.DEBUG)
file_handler.setFormatter(logging.Formatter(
'%(asctime)s [%(levelname)s] %(message)s'
))
logger.addHandler(console)
logger.addHandler(file_handler)
logger.info('Agent task completed in 5 steps')
logger.debug('Step 1: reasoning started')
Registrando IDs de Sessão para Agentes Multiusuário
Quando vários usuários ou tarefas são executados simultaneamente, os registros podem se misturar. Associe um ID de sessão ou ID de tarefa a cada mensagem de registro para que seja possível filtrar os registros de uma execução específica.
import logging
import uuid
class SessionLogger:
def __init__(self, name: str):
self.logger = logging.getLogger(name)
self.session_id = str(uuid.uuid4())[:8]
def debug(self, msg: str, **kwargs):
self.logger.debug(f'[session={self.session_id}] {msg}', **kwargs)
def info(self, msg: str, **kwargs):
self.logger.info(f'[session={self.session_id}] {msg}', **kwargs)
def error(self, msg: str, **kwargs):
self.logger.error(f'[session={self.session_id}] {msg}', **kwargs)
# Each agent run gets its own logger with a unique session ID
# log = SessionLogger('myagent')
# log.info(f'Starting task: {query}') # [session=a3f1b290] Starting task: ...
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.INFO, format='%(message)s', stream=sys.stdout)
log = SessionLogger('myagent')
log.info(f'Starting task: summarize the quarterly report')
Cronometrando Cada Etapa
Adicione informações de duração ao registro de cada etapa para identificar gargalos. Qual ferramenta é mais lenta? Quanto tempo o LLM leva para raciocinar? Esses dados orientam a otimização.
import time
import logging
logger = logging.getLogger('myagent')
def timed_tool_call(tool_name: str, tool_fn, args: dict) -> str:
start = time.perf_counter()
try:
result = tool_fn(**args)
elapsed = time.perf_counter() - start
logger.debug(f'Tool {tool_name} completed in {elapsed:.2f}s')
return result
except Exception as e:
elapsed = time.perf_counter() - start
logger.error(f'Tool {tool_name} failed in {elapsed:.2f}s: {e}')
raise
# In the agent loop:
# result = timed_tool_call('search_web', search_web, {'query': 'Python'})
# Logs: Tool search_web completed in 1.34s
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
def search_web(query):
return f'3 results for {query}'
result = timed_tool_call('search_web', search_web, {'query': 'Python'})
print('Tool result:', result)
O Padrão Completo de Rastreamento de Etapas
Este é o padrão completo de registro de rastreamento, pronto para produção, para uma etapa do agente. Cada etapa registra seu número, raciocínio, escolha da ferramenta, argumentos, prévia do resultado e duração — oferecendo visibilidade total sobre a execução do agente.
import time
import logging
import json
logger = logging.getLogger('myagent')
def trace_step(step_num: int, thought: str, tool: str, args: dict, execute_fn):
# Log decision
logger.debug(
f'Step {step_num}: thought="{thought[:80]}" tool={tool} '
f'args={json.dumps(args)[:100]}'
)
# Execute with timing
t0 = time.perf_counter()
try:
result = execute_fn(tool, args)
elapsed = time.perf_counter() - t0
preview = str(result)[:100].replace('\n', ' ')
logger.debug(f'Step {step_num} done in {elapsed:.2f}s: "{preview}"')
return result
except Exception as e:
elapsed = time.perf_counter() - t0
logger.error(f'Step {step_num} failed in {elapsed:.2f}s: {e}')
return f'ERROR: {e}'
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
def execute_fn(tool, args):
return f'42 (from {tool})'
trace_step(1, 'I should compute the answer', 'calculator', {'expr': '6*7'}, execute_fn)
Desativando Registros em Produção
Os registros de rastreamento de depuração contêm dados sensíveis (consultas, respostas de API) e podem ser muito detalhados. Em produção, defina o nível de registro como INFO ou WARNING para suprimir os rastreamentos de depuração. Use uma variável de ambiente para controlar o nível.
import os
import logging
import sys
# Read log level from environment variable
log_level_str = os.environ.get('LOG_LEVEL', 'INFO').upper()
log_level = getattr(logging, log_level_str, logging.INFO)
logging.basicConfig(level=log_level, stream=sys.stdout)
logger = logging.getLogger('myagent')
# Development: LOG_LEVEL=DEBUG python agent.py -> full traces
# Production: LOG_LEVEL=WARNING python agent.py -> only warnings/errors
# Default: LOG_LEVEL not set -> INFO level
logger.debug('This only appears in DEBUG mode')
logger.info('This appears in INFO and DEBUG modes')
logger.warning('This always appears')Verificação de Conhecimento: Registro de Rastreamento
Teste sua compreensão do registro de rastreamento das etapas do agente.
Recapitulação: Registro de Rastreamento das Etapas do Agente
Agora você tem uma estratégia completa de registro de rastreamento para agentes:
- Use
logging.basicConfig(level=DEBUG)para habilitar registros detalhados de rastreamento - Registre o número da etapa, o raciocínio, o nome da ferramenta e os argumentos em cada etapa
- Registre os resultados das ferramentas com uma prévia e o status de sucesso ou falha
- Use formatação JSON para obter registros estruturados e consultáveis
- Associe IDs de sessão a agentes multiusuário ou simultâneos
- Adicione a duração para identificar etapas lentas
- Controle o nível de detalhamento dos registros com a variável de ambiente
LOG_LEVEL
Perguntas Frequentes
A aula “Registro de rastreamento das etapas do agente” é grátis?
Sim — o texto completo de “Registro de rastreamento das etapas do agente” é 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 “Registro de rastreamento das etapas do agente”?
Registre cada etapa de raciocínio, chamada de ferramenta e resultado para análise posterior do incidente. 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 2 de 4.
Quanto tempo leva a aula “Registro de rastreamento das etapas do agente”?
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
- Falhas comuns em ciclos de agentes
- Registro de rastreamento das etapas do agente
- Detectando e interrompendo ciclos infinitos
- Técnicas de depuração passo a passo