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

# Ferramentas (Tools)

> Amplie o que a IA consegue fazer com integrações e ações definidas em código Python.

## O que é

As **ferramentas (tools)** ampliam o que a IA consegue fazer, permitindo que ela execute ações e integrações específicas (por exemplo, consultar um sistema externo ou processar dados). Uma ferramenta é definida por um **código em Python** e pode ser usada por **agentes** ou anexada a uma mensagem no chat.

<Info>
  **Recurso técnico/avançado.** Criar ferramentas exige conhecimento de programação (Python). O **uso** de ferramentas já criadas, porém, é simples e não requer programação.
</Info>

## Como acessar

* Barra lateral → **Ferramentas**
* Para criar: botão **Novo → Ferramenta** ou o botão de criação na própria página.

<Note>
  A página só aparece se o módulo **Workspace** e a permissão de **Ferramentas** estiverem habilitados para você.
</Note>

## Usar uma ferramenta (uso simples)

* **No chat:** digite `$` na mensagem ou use **+ → Anexar ferramenta** e selecione a ferramenta. Você pode anexar **até 2 ferramentas por mensagem**.
* **Em um agente:** no bloco de **parâmetros avançados** do agente, na **seleção de ferramentas**, marque as ferramentas que ele poderá usar (veja [Agentes](/guia/agentes)).

## Criar uma ferramenta (uso técnico)

Na tela de criação, você usa o **editor de ferramenta**, onde define:

* **ID** e **Nome** da ferramenta.
* **Descrição** (metadados).
* **Código** em Python que implementa a ferramenta.
* **Valves (parâmetros configuráveis)** — valores que ajustam o comportamento da ferramenta sem alterar o código.
* **Controle de acesso (Compartilhar)** — quais usuários/grupos podem **usar**.

<Warning>
  O código pode declarar uma versão mínima exigida da plataforma. Se a versão do Symphony for **inferior** à exigida, o salvamento é bloqueado com um aviso.
</Warning>

Após salvar, uma mensagem confirma **"Ferramenta criada com sucesso"**.

## Editar e compartilhar

* **Editar:** abra uma ferramenta da lista para alterar código, metadados e valves.
* **Compartilhar:** defina quem pode **usar** ("Pode usar") a ferramenta.

## Boas práticas

* Dê **nomes e descrições claras** para que outros entendam o que a ferramenta faz.
* Use **valves** para tornar a ferramenta configurável sem reescrever código.
* Compartilhe ferramentas apenas com quem realmente precisa.
* Teste a ferramenta em uma conversa antes de disponibilizá‑la amplamente.

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Preciso programar para usar ferramentas?">
    Não para **usar**. Apenas para **criar/editar** o código de uma ferramenta.
  </Accordion>

  <Accordion title="Quantas ferramentas posso usar por mensagem?">
    Até **2** por mensagem.
  </Accordion>

  <Accordion title="A ferramenta não salva e mostra erro de versão. O que é?">
    A ferramenta exige uma versão da plataforma mais nova do que a instalada. Atualize a plataforma ou ajuste a versão exigida no código.
  </Accordion>
</AccordionGroup>

## Limitações conhecidas

* A criação de ferramentas requer conhecimento de **Python**.
* Máximo de **2 ferramentas por mensagem** no chat.
* O salvamento é bloqueado se a versão exigida pela ferramenta for maior que a da plataforma.
* A criação/edição depende da permissão de **Ferramentas** no Workspace.