root-cause-tracing

# O que acontece?
# - Qual o erro exato?
# - Quando acontece?
# - E consistente ou intermitente?

# Coletar logs
docker compose logs backend 2>&1 | tail -100

Listar possiveis causas por probabilidade:
1. [Mais provavel] Timeout de conexao com API externa
2. [Provavel] Dados invalidos na entrada
3. [Menos provavel] Race condition no async

# Criar script de teste isolado
# backend/scripts/debug_issue.py

import asyncio
from app.services.suspeito import funcao_suspeita

async def main():
    # Testar com dados conhecidos
    resultado = await funcao_suspeita("entrada_teste")
    print(f"Resultado: {resultado}")

asyncio.run(main())

Fluxo tipico no Ta na Mao:

Request HTTP
    |
Router (app/routers/)
    |
Agent (app/agent/agent.py)
    |
Tool (app/agent/tools/)
    |
Service (app/services/)
    |
Database/API Externa

# Reproduzir com fix aplicado
pytest backend/tests/test_bug_fix.py -v

# Verificar que nao quebrou outras coisas
pytest backend/tests/ -v

import logging
logger = logging.getLogger(__name__)

async def funcao_suspeita(entrada):
    logger.debug(f"Entrada: {entrada}")
    # ... processamento
    logger.debug(f"Saida: {resultado}")
    return resultado

import pdb; pdb.set_trace()
# ou em async:
import asyncio
# breakpoint() funciona em Python 3.7+

import traceback
try:
    resultado = await funcao_suspeita()
except Exception as e:
    traceback.print_exc()
    raise