Ferramentas para o VoiceAgent

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.

Nível de utilizador: Admin

O que são as Ferramentas?

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

Como criar uma Ferramenta

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.

Veja como configurar cada parte:

Referência dos campos da Ferramenta

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`).
Parâmetros do corpo	Disponível apenas para os métodos `POST`, `PUT` e `PATCH`. Defina os campos a enviar no corpo do pedido.

Compreender os parâmetros

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:

Tipos de parâmetros

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": ["[email protected]", "[email protected]"]). 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.

Parâmetros de caminho

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 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 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.”

Parâmetros do corpo

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:

{
  "customer_id": "abc123",
  "attendee": {
    "email": "[email protected]"
  },
  "recipients": ["[email protected]", "[email protected]"]
}

Atribuir Ferramentas a VoiceAgents

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:

Aceda à secção Cenários e Salvaguardas da configuração do VoiceAgent.
Crie um novo Cenário ou edite um já existente.
Defina a situação em que a Ferramenta deve ser utilizada.
No campo Ação, selecione Tool Call.
No menu Ferramentas, escolha a Ferramenta que quer que o VoiceAgent utilize.
Guarde a configuração.

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

Dicas para utilizar as Ferramentas eficazmente

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 — estamos aqui para o ajudar.

Primeiros passos

Números e portabilidade

IA

AI Sales Dialer

CloudTalk Phone e Go

Mensagens

Dashboard

Integrações

Faturação e subscrição

Notícias e atualizações técnicas

Dashboard antigo

O que são as Ferramentas?

Como criar uma Ferramenta

Referência dos campos da Ferramenta

Compreender os parâmetros

Tipos de parâmetros

Parâmetros de caminho

Parâmetros do corpo

Atribuir Ferramentas a VoiceAgents

Dicas para utilizar as Ferramentas eficazmente

​O que são as Ferramentas?

​Como criar uma Ferramenta

​Referência dos campos da Ferramenta

​Compreender os parâmetros

​Tipos de parâmetros

​Parâmetros de caminho

​Parâmetros do corpo

​Atribuir Ferramentas a VoiceAgents

​Dicas para utilizar as Ferramentas eficazmente

O que são as Ferramentas?

Como criar uma Ferramenta

Referência dos campos da Ferramenta

Compreender os parâmetros

Tipos de parâmetros

Parâmetros de caminho

Parâmetros do corpo

Atribuir Ferramentas a VoiceAgents

Dicas para utilizar as Ferramentas eficazmente