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

# Ferramentas para o VoiceAgent

> Configure Ferramentas para que o seu VoiceAgent realize ações em tempo real através de API

<Note>
  Neste artigo, vai aprender como as **Ferramentas do VoiceAgent** permitem ações em tempo real durante chamadas em curso, possibilitando que o seu VoiceAgent interaja diretamente com sistemas externos através de API.

  Ao utilizar as Ferramentas, pode transformar o seu VoiceAgent num verdadeiro resolvedor de problemas, reforçando a automação e proporcionando experiências mais rápidas e inteligentes aos clientes.
</Note>

**Nível de utilizador:** Admin

***

<h2 id="h_4216241551">
  O que são as Ferramentas?
</h2>

As Ferramentas permitem que o seu VoiceAgent realize ações específicas durante uma chamada, através de pedidos de API a sistemas de terceiros. Pode configurar exatamente o que cada ferramenta faz e quando deve ser acionada, com base na conversa.

**Por exemplo**:

* Um cliente pergunta: “Onde está a minha encomenda?” → o VoiceAgent utiliza uma ferramenta para obter a informação de rastreio mais recente.

* Um paciente diz: “Posso mudar a minha consulta para sexta-feira?” → o VoiceAgent chama a sua API de agendamento para verificar a disponibilidade e reagendar.

**Outros exemplos de utilização:**

* **Obter dados:**

  * Consultar os detalhes de um ticket de suporte

  * Aceder a informação de preços ou disponibilidade em tempo real

* **Executar ações:**

  * Atualizar um contacto no CRM

  * Acionar um reembolso

***

<h2 id="h_c800e5f3ba">
  Como criar uma Ferramenta
</h2>

Para começar, aceda a **Dashboard > VoiceAgents > Gestão de Ferramentas** e clique no botão ➕ no canto superior direito, ou selecione **Criar uma Ferramenta** para abrir o painel de configuração onde pode definir o funcionamento da nova ferramenta.

<Frame>
  <img src="https://mintcdn.com/cloudtalk/g8s2E4Yk8cWS5656/images/help-center/articles/11275049/89b356edddea-screenshot-2025-05-07-at-11-20-17.png?fit=max&auto=format&n=g8s2E4Yk8cWS5656&q=85&s=484f51baeac2354c6fdf2fa12e8e794d" alt="" width="400" data-path="images/help-center/articles/11275049/89b356edddea-screenshot-2025-05-07-at-11-20-17.png" />
</Frame>

Veja como configurar cada parte:

<h4 id="h_425b566d96">
  Referência dos campos da Ferramenta
</h4>

| **Campo** | **Descrição** |
| - | - |
| **Nome da Ferramenta** | Um nome claro e descritivo que ajuda o VoiceAgent a decidir quando utilizar esta ferramenta. Utilize nomes como `book_meeting`, `update_contact` ou `trigger_refund`. Só são permitidos os seguintes carateres: `a-z`, `A-Z`, `0-9`, `_`, `-` |
| **Descrição da Ferramenta** | Descreva em linguagem natural o que a ferramenta faz e quando deve ser utilizada. Isto ajuda a IA a compreender em que situações deve acionar a ferramenta. |
| **Mensagem de espera de resposta** | Uma mensagem curta que o VoiceAgent reproduz enquanto espera pela resposta da API. Isto ajuda a gerir o silêncio durante a execução. Exemplo: `Let me check that for you. One moment please.` |
| **Método e Endpoint** | O método HTTP e o endpoint da API que a ferramenta vai chamar. Por exemplo: `GET https://api.example.com/orders` |
| **Cabeçalhos** | Defina os cabeçalhos exigidos pela API. Normalmente, são constantes como `Authorization`, `Content-Type` ou cabeçalhos de versionamento. |
| **Parâmetros de caminho** | Utilizados para preencher valores dinâmicos dentro do URL do endpoint (por exemplo, `#{{customer_id}}` em [`https://api.acme.com/#{{customer_id}}/orders`](https://api.acme.com//orders)). |
| **Parâmetros do corpo** | Disponível apenas para os métodos `POST`, `PUT` e `PATCH`. Defina os campos a enviar no corpo do pedido. |

<h2 id="h_4f39ac973b">
  Compreender os parâmetros
</h2>

Ao definir uma ferramenta, os parâmetros ajudam o VoiceAgent a passar os valores corretos para a sua API. Existem três tipos principais de parâmetros que pode utilizar tanto nas definições de caminho como nas de corpo:

<h4 id="h_b5a4e2b47e">
  Tipos de parâmetros
</h4>

| **Tipo** | **Descrição** |
| - | - |
| **Constante** | Um valor fixo que permanece igual em todas as chamadas de API. Útil quando sabe exatamente o valor que quer enviar sempre. |
| **Parâmetro** | Um valor dinâmico enviado a partir do seu system prompt. Aqui, indica o nome de uma variável que deve corresponder à enviada no pedido de API que aciona a ferramenta. |
| **LLM Prompt** | Uma instrução em linguagem natural para a IA sobre como extrair um valor da conversa. Ideal quando o valor depende do que o interlocutor diz. |

Cada parâmetro tem também um **tipo de dados** que controla o formato do valor no pedido de API. Tipos disponíveis:

* **String, Integer, Number, Boolean** funcionam como valores escalares simples.

- **List** envia o valor como um array JSON (por exemplo, `"recipients": ["a@b.com", "c@d.com"]`). Ao selecionar List, também escolhe um tipo de elemento (List of String, List of Integer, etc.). Se o agente extrair apenas um valor, este é automaticamente colocado num array de um elemento, em vez de falhar.

* **Object** envia o valor como um objeto JSON. Note que os parâmetros do tipo objeto são apenas descritivos: o agente é informado de que o parâmetro é um objeto e vê a sua descrição, mas não conhece os nomes específicos dos campos, por isso não consegue impor uma estrutura interna. Isto funciona bem para payloads simples de transmissão direta.

<h3 id="h_52e9885b1b">
  Parâmetros de caminho
</h3>

São valores colocados diretamente no URL. Defina-os utilizando chavetas dentro do URL do endpoint, como em `#{{customer_id}}`.

Veja como isto funciona na prática:

**Endpoint de exemplo:**\
[`https://api.acme.com/#{{customer_id}}/orders`](https://api.acme.com//orders)

Neste caso, o `customer_id` torna-se um parâmetro de caminho.

**Se definido como Parâmetro:**

| Parâmetro | Origem do valor |
| - | - |
| `customer_id` | variável `customer_identifier` do system prompt |

**Exemplo de pedido acionador**:

```
{
    "call_number": "++44123123123",
    "voice_agent_id": "6819f0e147851f618cd6aed6",
    "call_properties": {
        "system_prompt": {
            "variables": {
                "customer_identifier": "abc123",
            }
        }
    }
}
```

Isto resulta numa chamada a:\
[`https://api.acme.com/abc123/orders`](https://api.acme.com/abc123/orders)

**Para extrair através de LLM Prompt:**\
Utilize uma instrução clara, como:\
*“*Extraia o número de identificação do cliente mencionado pelo interlocutor, se este o fornecer. Se não o fornecer espontaneamente, peça-o.*”*

<Frame>
  <img src="https://mintcdn.com/cloudtalk/g8s2E4Yk8cWS5656/images/help-center/articles/11275049/815cc3074282-image.png?fit=max&auto=format&n=g8s2E4Yk8cWS5656&q=85&s=a76817755f1e24e31cf664aec8ebcfec" alt="" width="650" height="644" data-path="images/help-center/articles/11275049/815cc3074282-image.png" />
</Frame>

<h3 id="h_453492ae81">
  Parâmetros do corpo
</h3>

Para os métodos `POST`, `PUT` e `PATCH`, poderá ser necessário enviar um corpo de pedido. Estes funcionam da mesma forma que os parâmetros de caminho e também podem utilizar constantes, variáveis do system prompt ou LLM prompts.

**Os objetos aninhados** podem ser definidos utilizando notação de ponto.

**Exemplo de definição:**

| **Parâmetro** | **Tipo** | **Valor** |
| - | - | - |
| `customer_id` | Parâmetro | `customer_identifier` |
| `attendee.email` | LLM Prompt | *“Extraia o endereço de email do cliente a partir da conversa.”* |
| `recipients` | LLM Prompt | *"Extraia todos os endereços de email mencionados pelo interlocutor."* |

**Pedido acionador**:

```
{
    "call_number": "++44123123123",
    "voice_agent_id": "6819f0e147851f618cd6aed6",
    "call_properties": {
        "system_prompt": {
            "variables": {
                "customer_identifier": "abc123",
            }
        }
    }
}
```

**Este pedido resultará no seguinte corpo:**

```json theme={"system"}
{
  "customer_id": "abc123",
  "attendee": {
    "email": "john@acme.com"
  },
  "recipients": ["a@b.com", "c@d.com"]
}
```

<Frame>
  <img src="https://mintcdn.com/cloudtalk/0LuB-WYxwheF-8cl/images/help-center/articles/11275049/5b9ade3e0dcb-image-1.png?fit=max&auto=format&n=0LuB-WYxwheF-8cl&q=85&s=e35de45d644f8dfa1eb99f165c09c437" alt="" width="853" height="367" data-path="images/help-center/articles/11275049/5b9ade3e0dcb-image-1.png" />
</Frame>

***

<h2 id="h_0809ce1434">
  Atribuir Ferramentas a VoiceAgents
</h2>

As Ferramentas permitem que os VoiceAgents realizem ações específicas durante uma chamada, como acionar fluxos de trabalho externos, enviar dados para outros sistemas ou terminar a chamada. Um único VoiceAgent pode utilizar várias Ferramentas, e a mesma Ferramenta pode ser utilizada em vários VoiceAgents.

As Ferramentas são acionadas como **ações dentro de um Cenário do VoiceAgent**. Isto significa que o VoiceAgent só vai utilizar uma Ferramenta quando a situação definida no Cenário ocorrer durante a chamada.

Para utilizar uma ferramenta dentro de um cenário:

1. Aceda à secção **Cenários e Salvaguardas** da configuração do VoiceAgent.

2. Crie um novo **Cenário** ou edite um já existente.

3. Defina a situação em que a Ferramenta deve ser utilizada.

4. No campo **Ação**, selecione **Tool Call**.

5. No menu **Ferramentas**, escolha a Ferramenta que quer que o VoiceAgent utilize.

6. Guarde a configuração.

   <Frame>
     <img src="https://mintcdn.com/cloudtalk/0LuB-WYxwheF-8cl/images/help-center/articles/11275049/194bac00bc65-image.png?fit=max&auto=format&n=0LuB-WYxwheF-8cl&q=85&s=b4b12e4f82fb42298f289c4fb49b63d7" alt="" width="1178" height="642" data-path="images/help-center/articles/11275049/194bac00bc65-image.png" />
   </Frame>

Depois de configurado, o VoiceAgent vai utilizar automaticamente a Ferramenta selecionada quando as condições do cenário forem cumpridas durante uma chamada.

***

<h2 id="h_b446948f0c">
  Dicas para utilizar as Ferramentas eficazmente
</h2>

* **Utilize nomes de ferramenta claros e descritivos**\
  Dê a cada ferramenta um nome que reflita claramente o que ela faz. Evite abreviaturas ou códigos internos.

  * Bom: `trigger_refund`, `get_order_status`, `book_appointment`

  * Não tão bom: `rfnd_tool_v1`, `statusQ`, `app_sched_new`

* **Escreva uma descrição em linguagem natural**\
  No campo Descrição da Ferramenta, explique quando e porquê o VoiceAgent deve utilizar a ferramenta. Para ferramentas mais complexas, adicione uma breve descrição para cada argumento que o agente precisa de recolher.

***

*Precisa de ajuda ou tem alguma pergunta?* Contacte-nos através do nosso [Portal de suporte](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884) — estamos aqui para o ajudar.


## Related topics

- [Ferramentas do VoiceAgent: Cal.com](/pt/articles/14073361-voiceagent-tools-cal-com.md)
- [VoiceAgents para Chamadas Recebidas](/pt/articles/11399385-voiceagents-for-inbound-calls.md)
- [Acionar uma chamada do VoiceAgent a partir do Zapier](/pt/articles/11831224-triggering-a-voiceagent-call-from-zapier.md)


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