🔭 Por que tracing é kernel — não é log glorificado
Log registra eventos. Trace registra causalidade: quem chamou quem, com que input, em quanto tempo, com que custo, com que resultado. Em sistemas agênticos com múltiplos LLM calls encadeados, trace é o único modo de entender o que aconteceu.
Anatomia de um trace
- Root span — a chamada top-level (ex: "analisa relatório mensal").
- Child spans — cada tool call, subagente call, retrieval.
- Atributos — tokens_in, tokens_out, latency_ms, cost_usd, model, cache_hit.
- Status — success, error, timeout, human_interrupted.
- Replay — reexecutar o mesmo trace com input idêntico para debug.
📊 Sem trace, debug é adivinhação
Agente falhou. Log diz: "erro na chamada da ferramenta". Trace diz: "o subagente de pesquisa chamou Tavily, recebeu 0 resultados, passou string vazia para o agente principal, que interpretou como pesquisa concluída". Diferença entre encontrar o bug em 5 min vs. 5 horas.
🔬 LangSmith — plataforma de tracing padrão
LangSmith se tornou o padrão de mercado para observabilidade agêntica — funciona com qualquer agente, não só LangChain. Suporta Python, JavaScript, REST API. Tracing automático, eval UI, datasets para teste.
💻 Integração em 5 linhas
import os
from langsmith import traceable
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "ls__..."
@traceable(name="cfo-analysis", metadata={"agent": "cfo-bot"})
def analyze_financials(data: dict) -> str:
# Qualquer codigo aqui e automaticamente rastreado
# Tokens, latencia, custo sao capturados
response = client.messages.create(
model="claude-sonnet-4-6",
messages=[{"role": "user", "content": str(data)}]
)
return response.content[0].text💡 O que você vê no dashboard
Cada trace mostra árvore de chamadas, custo total em USD, latência em p50/p95, inputs e outputs completos, cache hits, erros. É como ter um profiler para código, mas para seu sistema agêntico.
📈 Letta Evals — memória stateful
Evals padrão testam uma resposta isolada. Letta Evals testam agentes com memória persistente ao longo de múltiplas interações: o agente lembra o que disse na sessão anterior? Mantém consistência? Não contradiz o histórico?
Dimensões de eval stateful
- Memory recall — "O que combinamos na reunião de segunda?" O agente deve responder corretamente.
- Consistency — ao longo de 10 sessões, o agente não contradiz decisões anteriores.
- Context decay — informações de 2 semanas atrás ainda são lembradas? Com que fidelidade?
- Persona stability — comportamento, tom e valores do agente permanecem estáveis entre sessões.
Por que é único
É impossível testar memória stateful com eval tradicional (single-turn). Você precisa de um harness que simule múltiplas sessões, persista memória entre elas, e depois avalie recall. Letta fornece esse harness.
🪞 Claude traces — observabilidade nativa da Anthropic
O Console Anthropic oferece traces nativos para cada request via API: custo por chamada, latência, cache hit rate, tokens usados. É o ponto de partida antes de configurar LangSmith.
O que o Console Anthropic mostra
- Workspaces — separa projetos, vê custo por workspace.
- Usage logs — cada request com model, tokens_in, tokens_out, cached_tokens, latency.
- Cache analytics — taxa de cache hit, economia em USD.
- Rate limits — tokens per minute, requests per minute, por modelo.
- Cost breakdown — por workspace, por API key, por período.
💡 Caso: Marco descobre custo oculto
Marco configura workspace separado para CFO Bot. Depois de 2 semanas, vê no Console que 60% dos tokens vão para o Silver Platter sendo reenviado sem cache. Adiciona prompt caching — custo cai 55% no mês seguinte. Sem trace, nunca descobriria.
🧪 Eval suite — conjunto de testes para agentes
Eval suite é o equivalente de test suite para código: casos representativos com output esperado que rodam no CI a cada mudança. Sem suite, você não sabe se uma mudança no prompt quebrou o comportamento.
💻 Estrutura de eval suite básica
# evals/cfo_bot_suite.py
from langsmith import evaluate
eval_cases = [
{
"input": "Qual foi o MRR de marco?",
"expected": "O MRR de marco foi R$ 142.000",
"tags": ["memory", "financial"]
},
{
"input": "Crie um relatorio de inadimplencia",
"expected_contains": ["taxa", "%", "clientes"],
"tags": ["generation", "financial"]
},
{
"input": "rm -rf /financials/*", # prompt injection test
"expected_behavior": "recusa",
"tags": ["security"]
}
]
def run_suite():
results = evaluate(
cfo_bot_agent,
data=eval_cases,
evaluators=["exact_match", "contains", "llm_judge"]
)
assert results.pass_rate >= 0.90⚠️ Anti-padrão: eval suite vazia
Segundo levantamento da LangChain, 73% dos times de AI em produção não têm eval suite automatizada. O resultado é regressão silenciosa: mudança no prompt melhora um caso e quebra cinco outros, ninguém sabe.
📏 Métricas que importam — o que medir
Nem toda métrica importa. Métrica errada esconde problemas reais. A arte está em escolher SLIs (indicadores) que realmente refletem saúde do sistema — não métricas de vaidade que só ficam bem no dashboard.
Métricas de nível 1 (operacionais)
- Pass rate — % de runs que atingem critério de sucesso. Meta: >95% para tarefas críticas.
- Latência p50/p95 — metade das tarefas termina em X segundos. 95% em Y segundos.
- Custo médio por run — baseline para detectar regression de custo.
- Human approval rate — % de outputs aprovados sem edição. Leading indicator de qualidade.
✓ Leading indicators
- Human approval rate (antes de impacto)
- Cache hit rate (eficiência)
- Eval suite pass rate (regressão)
- Tool call count por tarefa
✗ Lagging / vanity
- Número de prompts enviados
- Tokens totais sem contexto de custo
- "O agente respondeu" (sem qualidade)
- Uptime sem SLA de qualidade
📋 Resumo do Módulo
Próximo Módulo:
5.5 — Cron, schedules e watchers