Tools (Ferramentas)

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.

Tipos de Tools

O Kiraa oferece cinco tipos de Tools, cada uma para uma finalidade diferente:

Endpoint

Integre com APIs externas para buscar ou enviar dados em tempo real durante a conversa.

Handoff

Transfira a chamada para um atendente humano via SIP.

Encerrar Chamada

Encerre chamadas de forma controlada, com mensagem de despedida e timeout por inatividade.

Agendamento

Deixe o agente consultar disponibilidade, agendar, reagendar e cancelar compromissos em múltiplas agendas do Google Calendar.

CRM Action

Permite que o agente aja no CRM durante a conversa: mover etapa, criar tarefa, agendar retorno, marcar conversão, marcar pessoa errada, adicionar tag.

Como funcionam?

Crie a Tool

Configure uma Tool com as especificações necessárias (URL, número de destino, etc.)

Vincule ao Agente

Conecte a Tool aos agentes que devem utilizá-la

Agente usa automaticamente

Durante a conversa, o agente identifica quando usar cada Tool baseado na descrição e no campo “Quando Usar”

Resultado integrado

A Tool executa a ação e retorna o resultado para o agente continuar a conversa

Uma mesma Tool pode ser vinculada a múltiplos agentes, permitindo reutilização e consistência.

Detalhes por Tipo

Endpoint
Handoff
Encerrar Chamada
Agendamento
CRM Action

Tool Endpoint

Permite que seu agente faça chamadas HTTP para APIs externas durante a conversa. Ideal para integrar com sistemas existentes.Exemplos de uso:

Consultar CEP para obter endereço
Buscar preço de produto ou status de pedido
Verificar disponibilidade de estoque
Enviar dados para um CRM ou ERP

Campos de Configuração

Campo	Obrigatório	Descrição
Nome	Sim	Identificador da Tool (ex: `consultar_cep`)
Descrição	Sim	Explica ao agente o que a Tool faz
Método HTTP	Sim	GET, POST, PUT ou DELETE
URL	Sim	Endereço do endpoint (ex: `https://api.exemplo.com/dados`)
Autenticação	Não	Tipo de autenticação para o endpoint (veja detalhes abaixo)
Headers	Não	Cabeçalhos HTTP adicionais (ex: Content-Type)
Query Params Schema	Não	Esquema dos parâmetros de URL
Body Schema	Não	Esquema do corpo da requisição
Quando Usar	Não	Instruções de quando o agente deve acionar a Tool
Instruções de Resposta	Não	Como o agente deve apresentar a resposta da API ao cliente
Mensagem de Erro	Não	O que o agente fala quando a API retorna erro ou está indisponível

Autenticação

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.

Schemas de Parâmetros

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.

Testar Endpoint

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.

Exemplo: Consulta de CEP

Para configurar uma Tool que busca endereço por CEP:

Nome: consultar_cep
Descrição: “Consulta o endereço completo a partir do CEP informado pelo cliente”
Método: GET
URL: https://viacep.com.br/ws/{cep}/json/
Instruções de Resposta: “Informe ao cliente o endereço completo: logradouro, bairro, cidade e estado”
Quando Usar: “Quando o cliente informar um CEP ou perguntar sobre endereço”

Tool Handoff

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:

Transferir para suporte técnico avançado
Redirecionar para time de vendas
Encaminhar reclamações para ouvidoria
Escalar atendimentos sensíveis

Campos de Configuração

Campo	Obrigatório	Descrição
Nome	Sim	Identificador da Tool (ex: `transferir_suporte`)
Descrição	Sim	Explica ao agente quando usar esta transferência
Departamento	Sim	Setor de destino (ex: suporte, vendas, financeiro)
Prioridade	Sim	Nível de urgência na fila
Número de Destino	Sim	Número E.164 ou SIP URI para onde transferir
Tocar Tom de Espera	Não	Tocar tom de discagem durante a transferência (padrão: ativado)
Quando Usar	Não	Instruções de quando transferir

Níveis de Prioridade

Prioridade	Descrição
Baixa	Atendimento pode aguardar
Normal	Atendimento padrão
Alta	Atendimento prioritário
Urgente	Atendimento imediato

Número de Destino

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.

Exemplo: Transferência para Vendas

Nome: transferir_vendas
Descrição: “Transfere a chamada para a equipe de vendas”
Departamento: Vendas
Prioridade: Alta
Número de Destino: +551140001234
Tocar Tom de Espera: Ativado
Quando Usar: “Quando o cliente quiser fazer uma compra ou pedir uma proposta comercial”

Tool Encerrar Chamada (End Call)

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

Campos de Configuração

Campo	Obrigatório	Descrição
Nome	Sim	Identificador da Tool (ex: `encerrar_chamada`)
Descrição	Não	Descrição complementar
Mensagem de Despedida	Sim	Frase que o agente fala antes de desligar (padrão: “Obrigado pelo contato. Até logo!”)
Timeout por Inatividade	Não	Tempo em segundos sem resposta do usuário para encerrar automaticamente (10 a 300 segundos). Desabilitado por padrão.
Quando Usar	Não	Contextos em que a IA deve encerrar a chamada

Como funciona o Timeout por Inatividade

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.

Exemplo: Encerramento Padrão

Nome: encerrar_chamada
Descrição: “Encerra a chamada quando apropriado”
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”

Tool Agendamento

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.

Campos de Configuração

Campo	Obrigatório	Descrição
Nome	Sim	Identificador da Tool (ex: `agendar_consulta`)
Descrição	Não	Explicação complementar
Agendas	Sim	Uma ou mais agendas, cada uma representando um profissional ou recurso
Dados a coletar	Não	Dados que o agente deve pedir ao cliente antes de confirmar
Quando Usar	Não	Instruções de quando o agente deve acionar a Tool
Mensagem de Confirmação	Não	Frase que o agente fala após confirmar o agendamento

Configurando as Agendas

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.

Dados a Coletar

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.

Opção	Observações
Nome completo	Recomendado em quase todos os cenários
CPF	Útil para clínicas e serviços regulamentados
Telefone	Pré-preenchido quando o cliente já está no CRM
E-mail	Útil para envio de confirmação por e-mail
Observações	Campo livre (ex: sintoma, tipo de atendimento)

Reagendamento e cancelamento

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.

Vínculo com o agente

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

Exemplo: Clínica com dois médicos

Nome: agendar_consulta
Descrição: “Permite agendar, reagendar e cancelar consultas”
Agendas:
- Dra. Ana Silva — conta ana@clinica.com, calendário principal, seg-sex 08:00-18:00, 30 min, America/Sao_Paulo
- Dr. Bruno Lima — conta bruno@clinica.com, calendário principal, seg-qua-sex 14:00-20:00, 45 min, America/Sao_Paulo
Dados a coletar: Nome, CPF, Telefone, Observações
Quando Usar: “Quando o cliente quiser marcar, mudar ou cancelar uma consulta”
Mensagem de Confirmação: “Pronto! Sua consulta está agendada. Você receberá uma confirmação em breve.”

Tool CRM Action

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.

Sub-ação: `move_to_stage` (mover etapa do board)

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.

Sub-ação: `create_task` (criar tarefa humana)

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.

Sub-ação: `schedule_callback` (agendar retorno)

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.

Sub-ações secundárias (voz)

Disponíveis apenas no agente de voz, sem campos extras de configuração — só nome, descrição e “Quando usar”:

mark_wrong_person — marca o número como pessoa errada. Dispara automações com trigger intent="not_the_person".
mark_converted — marca conversão (aceita deal_value como parâmetro do agente). Grava nota na timeline.
add_client_tag — adiciona tag ao cliente. Cascateia trigger tag_added em automações.

Como criar uma Tool CRM Action

Nova Tool

Em Studio de IA > Tools, clique em Nova Tool.

Escolha CRM Action

Selecione o card CRM Action, depois escolha a sub-ação (move_to_stage, create_task, schedule_callback, etc.).

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.

Defina Quando Usar

Descreva os cenários concretos — quanto mais claros, mais precisa a decisão do agente.

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.

Exemplo: agente de vendas com 4 ações

Tool 1 — Mover etapa: move_to_stage, pipeline “Vendas”, etapas permitidas: “Lead qualificado”, “Proposta enviada”, “Negociação”.
Tool 2 — Criar tarefa: create_task, responsável padrão = vendedor sênior.
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.

Criando uma Tool

Clique em Nova Tool

Na página de Tools, clique no botão Nova Tool no canto superior direito

Selecione o tipo

Escolha entre Endpoint, Handoff, Encerrar Chamada, Agendamento ou CRM Action

Preencha os campos

Configure os campos específicos do tipo escolhido (veja detalhes de cada tipo acima)

Crie a Tool

Clique em Criar Tool para salvar

Vinculando Tools a Agentes

Após criar uma Tool, vincule-a aos agentes que devem utilizá-la:

Acesse o Agente

Vá para a página Agentes e clique no agente desejado

Localize a seção Tools

Role até encontrar a seção Tools

Vincule a Tool

Clique em Vincular Tool e selecione a Tool desejada na lista, ou crie uma nova diretamente

Para desvincular uma Tool, clique no ícone de lixeira ao lado dela na seção Tools do agente. A Tool não será excluída, apenas desvinculada.

Boas Práticas

Nomenclatura

Use nomes descritivos em snake_case: consultar_pedido, calcular_frete. Evite nomes genéricos como tool1.

Descrições

Seja específico sobre o que a Tool faz. A descrição ajuda o agente a decidir quando usá-la.

Campo Quando Usar

Descreva cenários concretos e palavras-chave que devem acionar a Tool. Quanto mais preciso, melhor o agente decide.

Segurança

Nunca exponha credenciais na URL. Use a seção de Autenticação para configurar tokens e chaves em Tools do tipo Endpoint.

Ao excluir uma Tool, ela será automaticamente desvinculada de todos os agentes. Esta ação não pode ser desfeita.

Resolução de Problemas

Problema	Solução
Tool não é acionada pelo agente	Verifique se está vinculada e se a descrição e “Quando Usar” estão claros
Endpoint retornando erro	Confirme URL, método, autenticação e headers. Use o botão Testar Endpoint no formulário para validar
Handoff não transfere	Verifique se o número de destino está correto e se o SIP REFER está habilitado no seu provedor
Chamada não encerra por inatividade	Verifique se a Tool Encerrar Chamada está vinculada e o timeout por inatividade está habilitado
Tool de Agendamento indisponível	Confira se o Google Calendar está conectado em Integrações > Plugins e se a conta usada na agenda não foi desconectada

Próximos Passos

Agentes

Configure e gerencie seus agentes de voz

Documentos

Adicione conhecimento aos seus agentes

Playground

Teste seus agentes com Tools configuradas

SIP Trunks

Configure seus trunks SIP para transferências via Handoff

Plugins

Conecte o Google Calendar para usar a Tool de Agendamento

​Tipos de Tools

Endpoint

Handoff

Encerrar Chamada

Agendamento

CRM Action

​Como funcionam?

​Detalhes por Tipo

​Tool Endpoint

​Campos de Configuração

​Autenticação

​Schemas de Parâmetros

​Testar Endpoint

​Exemplo: Consulta de CEP

​Tool Handoff

​Campos de Configuração

​Níveis de Prioridade

​Número de Destino

​Exemplo: Transferência para Vendas

​Tool Encerrar Chamada (End Call)

​Campos de Configuração

​Como funciona o Timeout por Inatividade

​Exemplo: Encerramento Padrão

​Tool Agendamento

​Campos de Configuração

​Configurando as Agendas

​Dados a Coletar

​Reagendamento e cancelamento

​Vínculo com o agente

​Exemplo: Clínica com dois médicos

​Tool CRM Action

​Sub-ação: move_to_stage (mover etapa do board)

​Sub-ação: create_task (criar tarefa humana)

​Sub-ação: schedule_callback (agendar retorno)

​Sub-ações secundárias (voz)

​Como criar uma Tool CRM Action

​Exemplo: agente de vendas com 4 ações

​Criando uma Tool

​Vinculando Tools a Agentes

​Boas Práticas

Nomenclatura

Descrições

Campo Quando Usar

Segurança

​Resolução de Problemas

​Próximos Passos

Agentes

Documentos

Playground

SIP Trunks

Plugins

Tipos de Tools

Como funcionam?

Detalhes por Tipo

Tool Endpoint

Campos de Configuração

Autenticação

Schemas de Parâmetros

Testar Endpoint

Exemplo: Consulta de CEP

Tool Handoff

Campos de Configuração

Níveis de Prioridade

Número de Destino

Exemplo: Transferência para Vendas

Tool Encerrar Chamada (End Call)

Campos de Configuração

Como funciona o Timeout por Inatividade

Exemplo: Encerramento Padrão

Tool Agendamento

Campos de Configuração

Configurando as Agendas

Dados a Coletar

Reagendamento e cancelamento

Vínculo com o agente

Exemplo: Clínica com dois médicos

Tool CRM Action

Sub-ação: `move_to_stage` (mover etapa do board)

Sub-ação: `create_task` (criar tarefa humana)

Sub-ação: `schedule_callback` (agendar retorno)

Sub-ações secundárias (voz)

Como criar uma Tool CRM Action

Exemplo: agente de vendas com 4 ações

Criando uma Tool

Vinculando Tools a Agentes

Boas Práticas

Resolução de Problemas

Próximos Passos