Expanda as capacidades dos seus agentes com ferramentas personalizadas
As Tools (Ferramentas) expandem as capacidades dos seus agentes durante as conversas. Com elas, seu agente pode consultar APIs, transferir para humanos ou encerrar chamadas de forma controlada.
Se o endpoint exige autenticação, configure o tipo adequado na seção Autenticação do formulário:
Tipo
Campos
Descrição
Nenhuma
—
Endpoint público, sem autenticação
Bearer Token
Token
Envia o header Authorization: Bearer <token>
Basic Auth
Usuário, Senha
Envia o header Authorization: Basic <base64>
API Key
Nome do Header, Chave
Envia a chave em um header customizado (padrão: X-API-Key)
As credenciais são armazenadas de forma segura e nunca são expostas na URL. Use sempre a seção de Autenticação em vez de colocar tokens diretamente nos Headers.
Os campos Query Params Schema e Body Schema definem quais dados o agente deve coletar do cliente para enviar na requisição. Para cada parâmetro, você configura:
Nome: identificador do parâmetro (ex: cep, pedido_id)
Tipo: string, number, integer, boolean, object ou array
Descrição: explica ao agente o que é este campo
Obrigatório: se o agente deve obrigatoriamente coletar este dado
Você pode usar o editor visual para adicionar campos um a um, ou alternar para o modo JSON para colar o esquema diretamente.
Antes de vincular a Tool a um agente, use o botão Testar Endpoint para validar a configuração. Se o endpoint possui parâmetros, um modal pedirá que você preencha valores de teste. O resultado mostra o status HTTP, tempo de resposta, corpo da resposta e headers retornados.
Transfere a chamada para um atendente humano via SIP. Quando o agente aciona essa Tool, o cliente é redirecionado para o número ou ramal de destino configurado.Exemplos de uso:
O campo Número de Destino aceita diferentes formatos dependendo do seu cenário:
Formato
Exemplo
Quando usar
E.164
+5511999999999
Números de telefone convencionais (PSTN)
SIP URI (Twilio)
sip:+5511999999999@seu-trunk.pstn.twilio.com
Transferência via trunk Twilio
SIP URI (outro provedor)
sip:+5511999999999@sip.seuprovedor.com
Conforme documentação do seu trunk SIP
SIP URI (Ramal)
sip:ramal100@pbx.empresa.com
Transferência para ramal interno
A transferência usará automaticamente o mesmo SIP trunk da chamada em andamento.
A transferência via Handoff funciona apenas em chamadas telefônicas reais (recebidas ou feitas via SIP). Ela não funciona no Playground, que utiliza WebRTC. Para testar o Handoff, faça uma ligação telefônica real para o número vinculado ao agente.Além disso, o SIP REFER deve estar habilitado no seu provedor SIP para que a transferência funcione. Consulte a documentação de SIP Trunks.
Permite encerrar chamadas de forma controlada. Essa Tool funciona de duas maneiras complementares:
Encerramento pela IA — O agente decide encerrar a chamada com base nos contextos que você definir (ex: quando o assunto está resolvido, quando o usuário foge do escopo).
Encerramento por inatividade — A chamada é encerrada automaticamente se o usuário ficar em silêncio por um tempo configurado.
Em ambos os casos, o agente fala a mensagem de despedida antes de desligar.Exemplos de uso:
Encerrar quando o atendimento está concluído
Desligar se o usuário ficar em silêncio (ex: esqueceu de desligar)
Encerrar quando o usuário foge completamente do escopo
Quando habilitado, um timer conta o tempo de silêncio do usuário. O timer:
Reseta cada vez que o usuário fala
Pausa enquanto o agente está falando ou pensando
Conta apenas quando o agente está aguardando resposta do usuário
Se o timer atingir o limite configurado, o agente fala a mensagem de despedida e encerra a chamada.
O timeout por inatividade é diferente da duração máxima da chamada (configurada no agente). A duração máxima limita o tempo total da ligação. O timeout por inatividade encerra apenas quando há silêncio prolongado.
Mensagem de Despedida: “Obrigado pelo contato. Se precisar de algo mais, ligue novamente. Até logo!”
Timeout por Inatividade: 30 segundos
Quando Usar: “Quando o usuário pedir para encerrar a chamada, quando fugir completamente do escopo do atendimento, ou quando o assunto estiver resolvido e não houver mais perguntas”
Permite que o agente consulte disponibilidade, agende, reagende e cancele compromissos diretamente no Google Calendar, inclusive em várias agendas diferentes em paralelo — útil, por exemplo, para uma clínica que atende por vários profissionais, cada um com sua agenda.Exemplos de uso:
Clínica com vários médicos, cada um com sua agenda
Consultório que atende em horários diferentes por profissional
Escritório que divide atendimento por especialista
Qualquer negócio que precise oferecer escolha de profissional e horário em uma mesma ligação
Antes de criar a Tool de Agendamento você precisa conectar pelo menos uma conta do Google Calendar em Integrações > Plugins. Cada profissional pode ter sua própria conta conectada. Veja Plugins.
Cada agenda representa um profissional ou recurso agendável. O agente escolhe a agenda certa durante a conversa e verifica a disponibilidade dentro das regras que você definir.Para cada agenda configure:
Campo
Descrição
Nome / Rótulo
Como a agenda aparece para o agente (ex: Dra. Ana Silva, Sala de Exames)
Título do Evento
Modelo do título que será criado no Google Calendar (pode usar variáveis)
Conta Google Calendar
Conta conectada em Plugins onde o compromisso será criado
Calendário
Calendário específico dentro daquela conta (principal ou secundário)
Início / Fim do expediente
Janela diária de atendimento
Dias disponíveis
Seg–Dom que o profissional atende
Duração (minutos)
Duração padrão de cada compromisso
Fuso horário
Fuso em que os horários são interpretados
Use Adicionar Agenda para vincular quantos profissionais quiser. Cada agenda pode usar uma conta Google Calendar diferente — ideal para que cada pessoa mantenha sua própria conta.
Se uma conta do Google Calendar usada na agenda for desconectada, a plataforma avisa e pede para reconectá-la em Integrações > Plugins. Enquanto isso, aquela agenda específica fica indisponível.
Marque quais informações o agente deve pedir ao cliente antes de confirmar o agendamento. Os dados coletados vão para a descrição do evento no Google Calendar.
A mesma Tool também permite ao agente reagendar ou cancelar compromissos existentes do cliente durante a ligação — não há uma configuração separada. O agente identifica o compromisso, conversa com o cliente e executa a alteração na agenda correspondente.
Cada agente pode ter apenas uma Tool de Agendamento vinculada por vez. Ao tentar vincular uma segunda, a opção aparece desabilitada com a mensagem “Já existe uma tool de agendamento vinculada”.
Permite que o agente aja diretamente no CRM durante a conversa — sem depender de alguém da equipe atualizar o cliente depois. Cada Tool CRM Action tem uma sub-ação específica.Sub-ações disponíveis:
Sub-ação
O que o agente faz
Canal
move_to_stage
Move o cliente entre etapas do board, escolhendo a etapa com base nas descrições do pipeline
Voz + WhatsApp
create_task
Cria uma tarefa humana para o time quando precisa de mão-de-obra humana
Voz + WhatsApp
schedule_callback
Agenda retorno — nova ligação ou WhatsApp na hora marcada
Voz + WhatsApp
add_client_tag
Adiciona uma tag ao cliente
Voz
mark_converted
Marca o cliente como convertido (com valor opcional do deal)
Voz
mark_wrong_person
Marca que o número fala com pessoa errada
Voz
Você cria uma Tool CRM Action por sub-ação — não é uma única tool com tudo dentro. Isso dá controle fino sobre quando o agente pode fazer cada coisa e permite descrições específicas.
O agente decide se o cliente deve ser movido entre etapas do board com base na conversa. As etapas são pré-aprovadas por você (whitelist).
Campo
Descrição
Pipeline
Board (funil) que essa tool pode mexer
Etapas permitidas
Subconjunto de etapas que o agente pode escolher como destino — selecione 2 ou mais
Quando usar
Reforço opcional sobre o critério para mover
A tool só funciona se o cliente já estiver no pipeline configurado. Se o cliente está em outro funil, o agente recebe erro estruturado e segue a conversa sem mover.
Como o agente decide a etapa: o agente recebe a lista de etapas permitidas com nome + descrição de cada uma. Quanto mais clara a descrição (ver Board), mais precisa a movimentação.Tracking visual: o card no Kanban mostra 🤖 + nome do agente + tempo relativo quando movido pela IA. A timeline registra stage_change com metadata.source='agent'.Cascata: se a etapa de destino tem automação com trigger stage_entry, ela é disparada automaticamente.
O agente cria uma Tarefa quando identifica trabalho humano: confirmar com terceiro, conferir documento, resolver pendência.
Campo
Descrição
Responsável padrão (opcional)
UUID de usuário usado quando o agente não consegue determinar o responsável
Quando usar
Cenários típicos (ex: “use sempre que o cliente pedir conferência humana”)
Resolução automática do responsável: parâmetro do agente → responsável padrão da tool → assigned_to do cliente. Se nenhum resolve, retorna erro para o agente.Tarefa interna, não-visível ao cliente: o agente NÃO comenta sobre criar tarefa durante a conversa. A tarefa aparece em /tasks para o time humano.
O agente agenda nova conversa quando o cliente diz “me liga depois” ou “manda no WhatsApp em vez”. Ver Retornos para detalhes completos.
Campo
Descrição
Duração máxima da chamada
Teto da call agendada (default 300s)
Integração WhatsApp (opcional)
Se preenchida, o agente pode trocar de canal: voz → WhatsApp. Sem isso, o agente só pode agendar nova ligação.
Quando usar
Cenários típicos
O agente WhatsApp nunca agenda call (regra de segurança). Cross-channel só funciona no sentido voz → WhatsApp.
Por trás:schedule_callback reusa a engine de Automações — cria uma run em uma “system automation” do agente. Aparece em /retornos (sidebar) e na timeline do cliente.
Selecione o card CRM Action, depois escolha a sub-ação (move_to_stage, create_task, schedule_callback, etc.).
3
Configure os campos específicos
Cada sub-ação tem seu formulário. Para move_to_stage: pipeline + etapas permitidas. Para schedule_callback: integração WhatsApp opcional. Etc.
4
Defina Quando Usar
Descreva os cenários concretos — quanto mais claros, mais precisa a decisão do agente.
5
Vincule ao agente
Em Studio de IA > Agentes, abra o agente e adicione a tool em Recursos vinculáveis.
Você pode vincular várias Tools CRM Action ao mesmo agente — uma para cada sub-ação que ele precisa executar. Por exemplo: um agente de vendas pode ter move_to_stage, create_task, schedule_callback e mark_converted ao mesmo tempo.
Tool 3 — Agendar retorno: schedule_callback, com integração WhatsApp ativa para fallback.
Tool 4 — Marcar conversão: mark_converted.
Resultado: o agente conduz a conversa completa, qualifica, propõe, fecha o deal — tudo registrado direto no CRM, sem ninguém atualizando o cliente depois.
