Como rastrear falhas em orquestração de agentes sem perder o contexto

Um agente falha no meio de uma orquestração complexa, você olha pro log e vê só um erro genérico sem contexto. Qual agente quebrou? Qual tool call falhou? Qual input gerou a resposta vazia? O rastro se perde na execução distribuída e você fica adivinhando onde está o problema.

Isso é insano. Sistemas multiagentes rodam em paralelo, encadeiam tool calls e passam contexto entre agentes, então quando uma falha acontece em qualquer ponto da cadeia, sem tracing adequado você fica sem mapeamento causal. Você precisa de observabilidade dedicada, porque um print simples não conta mais.

Por que sistemas multiagentes são difíceis de debugar

Multiagentes executam em paralelo, com contexto distribuído entre vários processos. Um agente chama outro, que chama uma tool, que chama um retriever, e se qualquer ponto falhar, a resposta final quebra sem deixar claro onde foi o erro. Tool calls encadeadas somem no rastro, inputs se perdem na passagem entre agentes, e você fica sem visibilidade do fluxo completo.

Sem tracing, você tem erros silenciosos. Agente retorna vazio, tool call falha sem exception, loop infinito consome tokens e timeout acontece sem explicação. É como debugar código sem stack trace: você sabe que deu ruim, mas não sabe onde nem por que.

Contexto no Claude Code

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Pré-requisitos para tracing efetivo

Antes de sair colocando observabilidade, você precisa da base certa. Logging estruturado é não-negociável: logs em JSON com campos padronizados, não texto solto. IDs de rastreamento por requisição (trace IDs) precisam ser gerados no começo da execução e propagados entre todos agentes e tool calls, assim todo fluxo fica vinculado ao mesmo trace.

Capturar entradas e saídas de cada agente é essencial. Input cru, output processado, erros com stack trace, decisões de roteamento. Tudo isso precisa ser loggado em checkpoints. E você precisa de uma camada de observabilidade: OpenTelemetry com convenções gen_ai.* ou uma plataforma dedicada que já implemente isso.

Contexto entre agentes de IA

Passo 1: entenda a hierarquia de spans

A estrutura de tracing em sistemas multiagentes segue uma hierarquia: root span é a requisição completa, agent spans são os agentes individuais, LLM spans são as chamadas de modelo, tool spans são as chamadas de ferramenta, e retriever spans são as buscas de contexto. Cada nível adiciona contexto ao trace.

root span (requisição)
├── agent span (planner)
│   ├── LLM span (chamada ao modelo)
│   └── tool span (busca web)
├── agent span (executor)
│   ├── LLM span (chamada ao modelo)
│   └── tool span (execução de código)
└── retriever span (busca em vetor store)

Quando você visualiza essa hierarquia, fica claro onde a execução quebrou. Se o tool span falhou, o problema está na chamada da ferramenta. Se o LLM span retornou vazio, o modelo não gerou resposta útil. É um mapa de execução, não só um log.

Erro comum: não respeitar a hierarquia e criar um span gigante que engloba tudo. Isso perde a granularidade que permite isolar qual etapa específica falhou.

Passo 2: implemente trace IDs em toda orquestração

O trace ID precisa ser gerado no início da requisição e propagado para cada agente e tool call. Sem isso, você não consegue correlacionar logs de diferentes partes do sistema. Cada agente deve receber o trace ID no input e repassar nas chamadas que faz.

import uuid

trace_id = str(uuid.uuid4())

def agent_step(input_data, trace_id):
    result = process(input_data)
    log({"trace_id": trace_id, "step": "agent_step", "input": input_data, "output": result})
    return result

def tool_call(param, trace_id):
    response = execute_tool(param)
    log({"trace_id": trace_id, "step": "tool_call", "param": param, "response": response})
    return response

O trace ID é a cola que junta todos os logs da mesma execução. Quando uma falha acontece, você filtra todos os logs com aquele trace ID e vê o fluxo completo do começo ao fim.

Erro comum: gerar um novo trace ID em cada agente. Isso fragmenta o rastro e você não consegue reconstruir o fluxo completo.

Passo 3: configure logging estruturado com breadcrumbs

Breadcrumbs são marcadores em pontos de decisão e bifurcações do fluxo. Logue input cru, output processado, erros com contexto, decisões de roteamento (qual agente escolher, qual tool chamar, qual branch seguir). Cada checkpoint adiciona uma migalha que permite reconstruir o caminho.

log({
    "trace_id": trace_id,
    "level": "agent_decision",
    "agent": "planner",
    "input": user_query,
    "decision": "route_to_researcher",
    "reason": "needs_external_data"
})

log({
    "trace_id": trace_id,
    "level": "tool_call",
    "tool": "web_search",
    "input": {"query": search_term},
    "output": search_results,
    "latency_ms": 234
})

O erro comum é loggar só depois que a falha acontece. Mas sem o estado anterior ao erro, você não sabe que input causou o problema. Logue antes, durante e depois de cada passo.

Passo 4: use a técnica de debug por trace ID

O workflow de debugging é simples: pegue o trace ID da resposta com falha, carregue os traces filtrando por esse ID e analise a hierarquia de spans até encontrar onde a execução quebrou. Em plataformas com dashboard, você cola o trace ID na busca e vê o fluxo visualmente.

1. Requisição retorna erro genérico
2. Extraia trace_id do response ou log
3. Na plataforma: search.trace_id == "abc-123-def"
4. Navegue na hierarquia de spans
5. Identifique o span com status "error"
6. Reveja input/output/error desse span
7. Corrija a causa raiz

Em LangSmith, por exemplo, você clica em "View Trace" e vê cada step com input, output e metadata. Em Portkey, o trace ID fica visível no dashboard e você filtra os logs daquela execução específica. A chave é poder reconstruir a sequência completa.

Erro comum: debugar por tentativa e erro, mexendo em código sem ver o fluxo. Com trace ID você vai direto ao ponto onde falhou.

Sintomas comuns de falhas em orquestração

Ferramentas de observabilidade comparadas

Qual ferramenta escolher

Se você já usa LangChain ou LangGraph, LangSmith é o caminho natural. Integração nativa, pricing claro e tracing em tempo real. A camada Developer grátis com 5.000 traces/mês já cobre desenvolvimento e testes iniciais.

Se preferir open source e controle total, Langfuse é a escolha. Tracing automático com LangGraph, trace names, run names, tags e metadata integrados. Você hospeda e mantém, então não fica preso a roadmap de terceiro.

Para observabilidade abrangente que vai além de LLMs, Portkey oferece traces, logs e trace IDs visíveis no dashboard com foco em LangGraph. É bom para quem quer uma visão completa da execução.

Budget limitado? Helicone tem plano Hobby grátis com 10.000 requests, mas atenção: a integração LangGraph é mantida mas não mais ativamente desenvolvida. Serve para começar, mas talvez não seja ideal a longo prazo.

Quando tracing de agentes é essencial

O investimento se justifica quando você tem sistema em produção com múltiplos agentes orquestrados. Debugar falhas intermitentes em produção sem tracing é perda de tempo. Workflows complexos com tool calls encadeadas exigem visibilidade: cada chamada é um ponto potencial de falha.

Se você precisa de auditoria (compliance, regulamentação), tracing é não-negociável. Você precisa provar o que cada agente fez, por qual decisão tomou. E para otimizar custos, tracing revela onde está gastando tokens demais: quais agentes, quais chamadas, onde você pode cortar.

Próximo passo

Comece pequeno. Implemente trace IDs em toda orquestração e logging estruturado em checkpoints. Isso já vai te dar visibilidade muito maior que logs soltos. Depois, adicione uma ferramenta de observabilidade que se adeque ao seu stack e orçamento. Tracing em sistemas multiagentes é como debugar código: você precisa das ferramentas certas para não perder tempo adivinhando onde está o problema.