> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Graphs

> Visualize caminhos de delegação entre vários agentes, chamadas de ferramentas e invocações de subagentes como um grafo direcionado na interface Traces do Toqan Router, incluindo execuções do LangGraph.

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**](/docs/pt-BR/ai-studio/observability/traces.md) 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:

| Tipo de span | O nó representa | Ícone |
| - | - | - |
| `span.agent_execution` | Execução de agente de nível superior | |
| `span.agent` | Etapa de orquestração dentro de um agente | |
| `span.agent_tool_execution` | Chamada de ferramenta dentro de uma etapa de agente | |
| `span.tool` | Invocação de ferramenta externa (HTTP, MCP, função) | |
| `span.chain` | Etapa de chain do LangChain/LangGraph | |
| `span.chat_completion` | Chamada ao modelo | |

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.

## Relacionados

* [Traces](/docs/pt-BR/ai-studio/observability/traces.md): explore traces com as visualizações de trace, thread e linha do tempo
* [Span Attributes](/docs/pt-BR/ai-studio/observability/span-attributes.md): referência completa de `orq.span_type` e dos atributos de agente


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.