1 Confundir entrada/saída (input keys) e deixar o contrato “implícito”

Um dos maiores causadores de falhas é tratar o formato de dados como se fosse “óbvio”.
Em LangChain, pequenas diferenças entre input_keys, nomes de variáveis, e o que a cadeia realmente entrega
viram erros silenciosos, resultados vazios ou composição quebrada.

O padrão que eu sigo: contrato explícito.
Defino claramente quais campos entram e quais saem, e garanto validação antes/depois.

2 Esquecer de controlar contexto: prompt longo demais, memória errada e ausência de limites

Quando você não impõe limites, o seu fluxo tende a degradar: respostas inconsistentes,
maior custo, e lentidão.
“Funciona no teste” vira um problema clássico quando as entradas crescem ou quando o histórico
começa a poluir o contexto.

• Prompt inflado: repetir instruções, anexar dados desnecessários e não “compactar” antes de montar o texto final.
• Histórico sem política: deixar o histórico crescer indefinidamente ou misturar conversas de domínios diferentes.
• Ausência de janela: não escolher uma estratégia de recorte (últimos N turnos, sumarização controlada, ou tags).

3 Misturar responsabilidades: usar “prompt + regras” para tudo e ignorar validação e parsing

Outro erro recorrente é depender totalmente do texto para manter consistência.
Você monta uma frase, adiciona “por favor responda em formato JSON”, e assume que isso sempre será respeitado.
Em produção, você precisa de validação e parsing tolerante.

O que costuma dar errado:

• Você não separa “construção de entrada” de “interpretação de saída”.
• Não existe validação do schema esperado (mesmo que seja simples).
• O código falha com mensagens genéricas quando o formato sai do esperado.

import json

def parse_structured_answer(raw: str) -> dict:
    """
    Converte uma resposta textual em um objeto validado.
    Exemplo: esperar campos 'intent' e 'confidence'.
    """
    try:
        data = json.loads(raw)
    except json.JSONDecodeError as e:
        raise ValueError(f"Resposta não é JSON válido: {e}. Conteúdo: {raw[:200]!r}")

    # Validação mínima de schema
    if not isinstance(data, dict):
        raise ValueError("Resposta deve ser um objeto (dict).")

    required = ["intent", "confidence"]
    missing = [k for k in required if k not in data]
    if missing:
        raise ValueError(f"Campos ausentes na resposta: {missing}. Recebido: {list(data.keys())}")

    if not isinstance(data["intent"], str) or not data["intent"].strip():
        raise ValueError("Campo 'intent' inválido.")

    if not isinstance(data["confidence"], (int, float)):
        raise ValueError("Campo 'confidence' deve ser numérico.")

    return data

# Uso:
# raw_answer = chain.invoke({"question": "..."})
# parsed = parse_structured_answer(raw_answer["output"])
# ...

4 Não instrumentar e não separar testes de execução: debug sem rastreio vira tentativa e erro

Quando algo quebra numa cadeia, você precisa enxergar:
o que entrou, em qual etapa,
o que saiu, e em que formato.
Sem rastreio, você fica dependente de “print” e vai perdendo velocidade.

• Executar tudo em linha: sem isolar etapas para teste unitário.
• Sem logs estruturados: não registra inputs/outputs (com cuidado para não vazar dados sensíveis).
• Sem métricas: sem medir tempo por etapa e taxas de falha (parse, validação, busca, etc.).
• Não reproduzir cenários: o teste não cobre inputs reais que quebram em produção.