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

# Composição de Tools

> Aninhe lógica reutilizável com o nó Tool: salvaguardas antirrecursão e rastreabilidade completa.

Você pode usar o nó **Tool** dentro de outras. Monte blocos reutilizáveis (validar identidade, cobrar, consultar estoque) e combine-os sem duplicar o canvas.

Disponível para todas as empresas.

## Como usar

<Steps>
  <Step title="Abra o canvas">
    No Brain Studio, vá à aba **Tools** e abra a que deseja compor (ou crie uma nova).
  </Step>

  <Step title="Arraste outra do buscador">
    No canvas aparece o buscador. Arraste a que precisar; ela é inserida como nó com seu `toolId`.

    A que você está editando **não aparece** na lista: você não pode referenciar a si mesma.
  </Step>

  <Step title="Configure entradas e saídas">
    Mapeie as entradas da filha (variáveis de memória, `$input` ou valores fixos). Os tipos declarados (**NUMBER**, **BOOLEAN**, **OBJECT**, **ARRAY**) são preservados na invocação; não chegam como string.
  </Step>

  <Step title="Publique">
    Publique a pai. Ao salvar e publicar, a plataforma rejeita autorreferências e detecta ciclos (por exemplo, A → B → A).
  </Step>
</Steps>

<Frame caption="Buscador no canvas">
  <img src="https://mintcdn.com/jelouai/xODihpYvJ1U6EAyJ/assets/images/nodos/tool-composition-picker-pt.png?fit=max&auto=format&n=xODihpYvJ1U6EAyJ&q=85&s=0ca542353df67a0eff4e64a345efdbc3" alt="Canvas mostrando o buscador para arrastar outra Tool" width="1571" height="902" data-path="assets/images/nodos/tool-composition-picker-pt.png" />
</Frame>

## Salvaguardas antirrecursão

Para evitar loops infinitos:

* **Sem autorreferência**: a atual não aparece no buscador e o salvamento bloqueia se você tentar referenciá-la.
* **Limite de aninhamento**: em tempo de execução há um teto de profundidade (padrão **5** níveis). Se for ultrapassado, a execução falha de forma controlada.
* **Detecção de ciclos**: ao publicar, um analisador detecta ciclos entre elas.

<Warning>
  Desenhe peças pequenas e com uma única responsabilidade. Aninhar demais dificulta a depuração e aproxima você do limite de profundidade.
</Warning>

## Rastreabilidade e depuração

Cada execução de uma filha gera um `executionId` que fica registrado na pai, mesmo que termine em **timeout**, erro ou sucesso.

No [Tester](/pt/guias/primeiros-passos/tester), no nó use **Debugar Tool** para inspecionar a execução interna da filha (nós, entradas, saídas e erros) sem abrir o canvas em separado.

## Timeout

As filhas têm um timeout configurável. O valor padrão é **30 segundos**. Se esgotar, o estado final da Tool pai inclui o `executionId` da filha e o resultado `TIMEOUT`, para que você possa depurá-la como em um erro normal.

## Tipos de entradas

Ao mapear entradas para uma filha, o builder persiste o tipo junto com o valor. O motor converte conforme o tipo declarado:

| Tipo declarado     | Comportamento                                       |
| ------------------ | --------------------------------------------------- |
| `NUMBER`           | Enviado como número (não como `"15"`)               |
| `BOOLEAN`          | Enviado como booleano                               |
| `OBJECT` / `ARRAY` | Enviado como estrutura, não como string serializada |
| `STRING`           | Enviado como texto                                  |

Assim você evita bugs silenciosos quando a filha espera um ID numérico ou um objeto.

## Boas práticas

* Prefira peças genéricas e reutilizáveis como blocos de composição.
* Documente entradas e saídas de cada filha para que o mapeamento na pai fique claro.
* Teste a composição no Tester e use **Debugar Tool** em cada nível aninhado.
* Mantenha a profundidade baixa; se precisar de muitos níveis, considere achatar o desenho.