> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiraa.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools (Ferramentas)
> 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.
## Tipos de Tools
O Kiraa oferece **cinco tipos** de Tools, cada uma para uma finalidade diferente:
Integre com APIs externas para buscar ou enviar dados em tempo real durante a conversa.
Transfira a chamada para um atendente humano via SIP.
Encerre chamadas de forma controlada, com mensagem de despedida e timeout por inatividade.
Deixe o agente consultar disponibilidade, agendar, reagendar e cancelar compromissos em múltiplas agendas do Google Calendar.
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?
Configure uma Tool com as especificações necessárias (URL, número de destino, etc.)
Conecte a Tool aos agentes que devem utilizá-la
Durante a conversa, o agente identifica quando usar cada Tool baseado na descrição e no campo "Quando Usar"
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
### 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 ` |
| **Basic Auth** | Usuário, Senha | Envia o header `Authorization: Basic ` |
| **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](/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:
1. **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).
2. **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](/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](/tasks) humana para o time quando precisa de mão-de-obra humana | Voz + WhatsApp |
| **`schedule_callback`** | Agenda [retorno](/callbacks) — 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](/board#por-que-a-descrição-da-etapa-importa)), 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](/automations) com trigger `stage_entry`, ela é disparada automaticamente.
***
#### Sub-ação: `create_task` (criar tarefa humana)
O agente cria uma [Tarefa](/tasks) 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](/callbacks) 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](/automations) — 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
Em **Studio de IA > Tools**, clique em **Nova Tool**.
Selecione o card **CRM Action**, depois escolha a **sub-ação** (move\_to\_stage, create\_task, schedule\_callback, etc.).
Cada sub-ação tem seu formulário. Para `move_to_stage`: pipeline + etapas permitidas. Para `schedule_callback`: integração WhatsApp opcional. Etc.
Descreva os cenários concretos — quanto mais claros, mais precisa a decisão do 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
Na página de Tools, clique no botão **Nova Tool** no canto superior direito
Escolha entre **Endpoint**, **Handoff**, **Encerrar Chamada**, **Agendamento** ou **CRM Action**
Configure os campos específicos do tipo escolhido (veja detalhes de cada tipo acima)
Clique em **Criar Tool** para salvar
***
## Vinculando Tools a Agentes
Após criar uma Tool, vincule-a aos agentes que devem utilizá-la:
Vá para a página **Agentes** e clique no agente desejado
Role até encontrar a seção **Tools**
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
Use nomes descritivos em snake\_case: `consultar_pedido`, `calcular_frete`. Evite nomes genéricos como `tool1`.
Seja específico sobre o que a Tool faz. A descrição ajuda o agente a decidir quando usá-la.
Descreva cenários concretos e palavras-chave que devem acionar a Tool. Quanto mais preciso, melhor o agente decide.
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
Configure e gerencie seus agentes de voz
Adicione conhecimento aos seus agentes
Teste seus agentes com Tools configuradas
Configure seus trunks SIP para transferências via Handoff
Conecte o Google Calendar para usar a Tool de Agendamento