Pular para o conteúdo principal
A visualização Agent Graph representa fluxos de trabalho com vários agentes e várias etapas como um grafo direcionado. Cada nó representa um span (uma etapa de agente, uma chamada de ferramenta ou uma invocação de subagente), e as arestas mostram o caminho de delegação do pai para o filho. O grafo aparece abaixo da árvore do trace no painel Traces quando um trace contém spans de agente.

​
Como os grafos são gerados

Os grafos são gerados por dois caminhos distintos, dependendo do framework.

​
Grafos pré-carimbados (LangGraph)

Quando um trace se origina do LangGraph, a estrutura do grafo vem pré-carimbada no atributo orq.trace.graph do span raiz. O atributo contém:
  • Nós: cada um com um id, um type e span_ids mapeados para a hierarquia de spans do trace
  • Arestas: cada uma com um ID de nó source e target
A interface Traces lê esse atributo diretamente e renderiza o grafo sem precisar inferir a estrutura a partir das relações pai/filho entre spans.

​
Grafos derivados (todos os outros frameworks)

Para frameworks que não pré-carimbam um grafo (OpenAI Agents SDK, CrewAI, AutoGen, Agno e agentes gerenciados do Toqan Router), o grafo é derivado automaticamente da hierarquia de spans:
  1. O trace deve conter pelo menos um span cujo tipo comece com span.agent (por exemplo, span.agent, span.agent_execution, span.agent_tool_execution)
  2. Depois de acionado, todo span do trace se torna um nó do grafo; não há filtro por tipo durante a derivação
  3. As relações pai/filho entre spans se tornam arestas
  4. O mecanismo de layout posiciona os nós de cima para baixo usando um algoritmo dagre
Isso significa que qualquer trace com spans de agente gera automaticamente um grafo que mostra toda a hierarquia de execução, mesmo sem instrumentação específica do framework.

​
Tipos de span no grafo

Tipos de span comuns que aparecem como nós do grafo: Os nós são rotulados pelo nome do span. Quando várias chamadas são agrupadas em um único nó (a mesma etapa repetida), um selo mostra a contagem (por exemplo, x3 para três chamadas idênticas). Clicar em um nó agrupado percorre os spans individuais, exibindo um indicador de posição (por exemplo, 2/3).

​
Controles do grafo

O painel do grafo pode ser redimensionado e recolhido:
  • Aumentar / diminuir / redefinir o zoom: ajuste a visualização para enquadrar o grafo ou focar em nós específicos
  • Recolher / expandir: oculte ou mostre o painel do grafo abaixo da árvore do trace
  • Mover: arraste para navegar por grafos grandes
Arestas antiparalelas (A chama B e B chama A) são desenhadas em lados opostos dos nós para evitar sobreposição visual.

​
Depurar com grafos

​
Rastrear caminhos de delegação

Abra um trace com vários agentes e observe o painel do grafo de agentes abaixo da árvore do trace para ver qual agente delegou para qual subagente e em que ordem. O layout de cima para baixo mostra a cadeia de chamadas do agente raiz até as chamadas de ferramenta nas folhas.

​
Descobrir onde o tempo é gasto

O rótulo de cada nó mostra o nome e o tipo do span. Clique em um nó para destacá-lo na árvore do trace, onde a duração é exibida ao lado de cada span.

​
Inspecionar chamadas de subagentes com falha

Clique em um nó para abrir os detalhes do span no painel lateral, onde estão disponíveis a mensagem de erro, os atributos e os eventos. Spans com falha mostram um status de erro na lista da árvore do trace ao lado do grafo.

​
Depurar falhas em chamadas de ferramentas

Spans de ferramenta (span.tool, span.agent_tool_execution) mostram o nome da ferramenta no painel do span. Clique para ver argumentos, resultados e outros atributos.
  • Traces: explore traces com as visualizações de trace, thread e linha do tempo
  • Span Attributes: referência completa de orq.span_type e dos atributos de agente