---
title: "Ferramentas integradas"
description: "Instrua os agentes ThunderPhone a encerrar chamadas, transferir quem liga, navegar por teclados, aguardar em espera, pesquisar conhecimentos, reproduzir sons, enviar e-mails e calcular totais."
---

As ferramentas integradas permitem que um agente execute ações comuns em chamadas sem conectar sua
própria API. A maioria está disponível automaticamente; e-mail, sons, a calculadora e a pesquisa de
conhecimento aparecem somente depois que você configura a opção ou a fonte relacionada. Informe ao agente
quando usar cada ação no prompt.

| Ferramenta | Use para | Como habilitar | Chamadas compatíveis |
| --- | --- | --- | --- |
| `end_call` | Encerrar uma conversa concluída | Sempre disponível | Telefone, Talk no navegador, widget, simulação e Realtime |
| `transfer_call` | Encaminhar quem liga por telefone | Configure o roteamento no prompt | Chamadas telefônicas comuns; o Realtime em linha com `call_events` pode usar transferência fria. O Realtime de agente salvo não inclui essa opção. |
| `send_keypad_input` | Pressionar teclas em um menu telefônico | Sempre disponível em chamadas telefônicas comuns | Chamadas telefônicas; Realtime de saída em linha com `call_events`. O Realtime de agente salvo não inclui essa opção. |
| `no_response` | Continuar ouvindo enquanto um menu automatizado fala ou quem liga pensa em voz alta; quem liga e pede que o agente espere recebe apenas "Claro." | Sempre disponível | Todos os tipos de chamada |
| `wait_on_hold` | Aguardar em silêncio o retorno de uma pessoa | Incluído em chamadas de saída | Sessões telefônicas de saída e sessões Realtime em linha de saída |
| `search_knowledge_base` | Responder com base em fontes anexadas | Anexe conhecimento ao agente | Chamadas de agente salvo com conhecimento anexado |
| `play_sound` | Reproduzir um som de notificação configurado | **Avançado → Som da ferramenta** | Chamadas de agente salvo |
| `send_email` | Enviar e-mail para um destinatário fixo | **Avançado → Enviar e-mail** | Chamadas de agente salvo |
| `calculate` | Somar totais, taxas e troco com precisão | **Avançado → Calculadora** | Chamadas de agente salvo |

## `end_call`

Encerra a chamada atual quando o prompt instrui o modelo a fazer isso. Está disponível
por padrão e não tem configuração de agente.

Escreva a condição e qualquer despedida necessária no prompt:

```text
When the caller confirms they need nothing else, say goodbye and end the call.
```

Uma chamada encerrada pelo modelo tem `end_reason: "ai_hangup"`, incluindo uma que termina após o aviso de limite de tempo da chamada. A chamada termina com `max_duration` somente se o limite de tempo for atingido primeiro, e com `balance_exhausted` quando o saldo pré-pago se esgotar.

## `transfer_call`

Transfere quem liga por telefone para um número fixo fornecido pelo modelo. A transferência cega
é imediata. Uma transferência assistida com triagem liga privadamente para o destino antes de
conectar as partes. A transferência assistida exige um número VoIP importado e verificado
que possa realizar chamadas de saída.

Inclua o número de destino e a condição exata de encaminhamento no prompt:

```text
If the caller asks for billing, transfer them to +15551234567.
```

Uma transferência cega bem-sucedida tem `end_reason: "ai_transfer"`; uma transferência
assistida concluída tem `end_reason: "ai_warm_transfer"`. Uma tentativa assistida com falha
devolve o controle ao agente, portanto o encerramento posterior da chamada determina seu motivo
de encerramento. Em sessões que não são telefônicas, uma solicitação de transferência encerra a sessão.

Consulte [Transferir chamadas](/pt/guides/call-transfers) para configuração no dashboard e na API,
encaminhamento, triagem, tratamento de falhas, limites e testes.

## `send_keypad_input`

Envia dígitos DTMF (teclado telefônico) `0`–`9`, `*` e `#` para uma linha telefônica. O
modelo usa esse recurso para navegar por uma URA, o menu automatizado que pede a quem liga para pressionar
teclas. Está disponível por padrão e não tem configuração de agente.

Informe ao modelo quais menus ele pode navegar e de onde vêm os valores solicitados.
Não peça para ele adivinhar opções de menu:

```text
Follow the phone menu for account status. Press a key only after the menu
states what that key does. Enter the account number supplied by the caller.
```

A plataforma remove caracteres não compatíveis e envia os dígitos válidos em ordem.
Se não restarem dígitos válidos ou se a chamada não puder enviar entradas do teclado,
a falha será retornada ao agente para que ele possa se recuperar.

## `no_response`

Mantém o agente em silêncio enquanto um sistema automatizado ainda está falando ou pede que ele continue ouvindo, e enquanto quem liga pensa em voz alta ("hum, deixa eu ver") ou se vira para falar com outra pessoa. Quando quem liga pede que o agente espere enquanto faz algo ("um segundo", "deixa eu verificar", "pode aguardar um instante?") e não dá mais nada para responder, o agente diz apenas "Claro." (não "Sem pressa") e espera que quem liga volte a falar. As mensagens de verificação de silêncio do agente continuam ativas e são sempre faladas se a linha permanecer silenciosa. Não se aplica à saudação de uma pessoa ao vivo, a uma pergunta ou a uma fila de espera real. Está disponível por padrão e não tem configuração do agente.

Se o seu prompt informar ao agente o que dizer quando quem liga pedir um momento, o prompt prevalece.

Normalmente, a descrição integrada é suficiente. Para chamadas com uso intenso de URA, reforce o
limite no prompt:

```text
Stay silent while a phone menu is still speaking. Answer a live person as soon
as they address you.
```

Essa ação não encerra a chamada.

## `wait_on_hold`

Coloca um agente de saída em um estado de espera silenciosa até que uma pessoa retorne.
O modelo só o utiliza depois que a outra parte diz explicitamente que o agente está sendo
colocado em espera. Ele fica disponível automaticamente em chamadas de saída e não tem
configuração no painel.

```text
If a person explicitly puts you on hold, wait silently. When they return,
continue from the question you were discussing.
```

Não instrua o agente a usá-lo para uma mensagem de "aguarde" de uma URA. Por padrão, a espera dura
até 15 minutos. Para chamadas de saída comuns, `POST /v1/call`
aceita um `max_hold_seconds` inteiro positivo; o Realtime inline restringe
`max_hold_seconds` a 10–900 segundos. Se a pessoa
retornar, o agente retoma sem alterar o motivo de encerramento da chamada. Se o limite
expirar, a plataforma encerra a chamada com `end_reason: "ai_hangup"`.

## `search_knowledge_base`

Pesquisa documentos anexados ao agente e retorna trechos relevantes. Anexe
uma base de conhecimento ou documentos individuais de conhecimento para ativá-la e, em seguida, informe ao
modelo quais respostas devem vir dessas fontes:

```text
Search the knowledge base before answering policy questions. If the first
search is inconclusive, try once more with different key terms.
```

Se uma pesquisa falhar, o resultado será retornado ao agente. Consulte [Base de
conhecimento](/pt/guides/knowledge-base) para a configuração no painel e na API.

## `play_sound`

Reproduz o som de notificação configurado do agente após qualquer fala no mesmo
turno. No painel, defina **Avançado → Som da ferramenta** como **Chime**, **Ding**
ou **Beep** e, em seguida, publique o agente. **Nenhum** remove a ferramenta.

Com a [API de Agents](/api-reference/agents), prepare `play_sound_asset` como
`"chime"`, `"ding"` ou `"beep"` e, em seguida, publique. Defina-o como `""` para desativar
a ferramenta.

```text
After confirming that an appointment was saved, say "You're all set" and play
the notification sound.
```

Uma falha de reprodução é retornada ao agente e não encerra a chamada.

## `send_email`

Envia um e-mail de texto simples para o único destinatário configurado pelo proprietário do agente.
O modelo fornece o assunto e o corpo. Ele nunca vê um parâmetro de destinatário
e não pode escolher nem alterar o endereço.

No painel, ative **Avançado → Enviar e-mail**, salve um endereço de destinatário
e, em seguida, publique o agente. Com a [API de Agents](/api-reference/agents), prepare tanto
`send_email_enabled: true` quanto um `send_email_recipient` não vazio e, em seguida, publique.
Defina o gatilho e o conteúdo obrigatório no prompt:

```text
When the caller asks to leave a message, collect their name, callback number,
and message. Read the details back for confirmation, then email them.
```

Uma chamada pode tentar enviar no máximo três e-mails. Cada assunto é limitado a 300
caracteres e cada corpo a 20.000 caracteres. Configuração ausente, conteúdo inválido,
o limite por chamada e falhas de entrega são retornados ao agente.
Uma entrega com falha ainda consome uma das três tentativas.

Teste com um destinatário controlado antes de publicar amplamente. O Talk no navegador e
as simulações enviam e-mails reais; não há modo de simulação.

## `calculate`

Avalia uma expressão aritmética com precisão e retorna o resultado, para que o agente
não some preços de cabeça. Fica desativada por padrão. No painel,
ative **Avançado → Calculadora** e implante o agente. Com a [API de
agentes](/api-reference/agents), defina `calculator_enabled: true` no estágio e implante.

O modelo escreve a expressão, como `2*23.5 + 16.5 + 4`, e informa o
resultado a quem liga. As expressões podem usar números, `+`, `-`, `*`, `/` e
parênteses. Uma chamada pode incluir até 10 expressões separadas por `;`, como
um subtotal e o total com uma taxa de entrega, com até 500 caracteres no total.
Os resultados são arredondados para 10 casas decimais. A matemática usa aritmética decimal exata, portanto
`0.1 + 0.2` retorna `0.3`. A divisão por zero e qualquer outro problema na expressão
retornam ao agente como um erro a ser corrigido. Ela é executada no ThunderPhone e
responde instantaneamente, sem frase de preenchimento nem som de digitação.

Ative-a para agentes que informam totais de pedidos, taxas ou troco. Não é necessário
alterar o prompt.

## Nota de compatibilidade

A configuração **Avançado → Avisos ininterruptíveis** e o campo legado
`speak_uninterruptible_enabled` permanecem por compatibilidade, mas ativá-los
não tem efeito. Deixe a configuração desativada; nenhum prompt pode ativar esta ferramenta.

Para um aviso obrigatório na abertura da chamada, use **Anúncio de consentimento**. Ele é reproduzido
literalmente antes da conversa comum e não pode ser interrompido. Consulte [Leis de consentimento para gravação
de chamadas](/pt/guides/recording-consent-laws).

## Teste e monitore ferramentas integradas

Use o Talk no navegador ou uma simulação para verificar prompts, pesquisa de conhecimento, sons
e e-mail. Esses ambientes não conseguem reproduzir o comportamento da rede telefônica. Teste
a navegação por teclado e a espera em uma chamada telefônica de saída e teste uma transferência
assistida completa em uma chamada real usando um número VoIP importado qualificado. O suporte ao Realtime
é limitado conforme mostrado na tabela acima.

## Chamadas, preços e webhooks

As ações integradas não têm taxa por uso da ferramenta. As cobranças normais de chamadas e do provedor
ainda se aplicam; consulte [Preços](/pt/guides/pricing). Suas chamadas e resultados podem aparecer
na transcrição concluída, mas não emitem `telephony.tool` nem `web.tool`.
Esses eventos são destinados a [funções definidas pelo usuário](/pt/tools/overview). Apenas um desligamento
ou transferência concluídos alteram o `end_reason` da chamada; outras falhas são retornadas
ao agente. Consulte [Webhooks de conclusão](/pt/webhooks/call-complete) para obter o registro da chamada.