> ## 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.
# Agentes
> Crie e configure seus assistentes de voz com inteligência artificial
O **Agente** é o coração do Kiraa. Ele é o assistente de voz com inteligência artificial que atende suas chamadas, conversa com seus clientes e executa tarefas. Pense nele como o "cérebro" que conecta todos os outros recursos da plataforma.
## O que é um Agente?
Um agente é um assistente virtual de voz que você configura para representar sua empresa em ligações telefônicas. Ele:
* **Atende chamadas** automaticamente quando vinculado a um número de telefone
* **Conversa naturalmente** usando inteligência artificial avançada
* **Segue suas instruções** para manter a personalidade e comportamento desejados
* **Executa tarefas** como consultar sistemas, transferir para humanos ou fazer cálculos
* **Responde perguntas** usando documentos da sua base de conhecimento
Cada agente é uma combinação única de personalidade, conhecimento e capacidades que você define.
***
## Como o Agente Conecta Tudo
O agente é o hub central que une todos os recursos do Kiraa:
```mermaid theme={null}
flowchart TB
subgraph Agente["Agente de Voz"]
I["Configuração (Guiado ou Texto Livre)"]
V[Voz]
end
Skills[Skills] --> Agente
Rules[Rules] --> Agente
Tools[Tools] --> Agente
Docs[Documentos] --> Agente
Agente --> Phone[Número de Telefone]
Phone --> Cliente[Cliente Liga]
```
| Recurso | O que faz | Como o agente usa |
| ---------------- | ------------------------------------ | -------------------------------- |
| **Configuração** | Define personalidade e comportamento | Segue como diretriz principal |
| **Skills** | Ensina tarefas específicas | Sabe executar procedimentos |
| **Rules** | Estabelece limites e restrições | Respeita o que não pode fazer |
| **Tools** | Integra com sistemas externos | Executa ações durante a conversa |
| **Documentos** | Fornece conhecimento específico | Busca informações para responder |
| **Voz** | Define como o agente fala | Responde com a voz configurada |
***
## Configurando seu Agente
Ao criar ou editar um agente, você configura os campos abaixo.
### Nome
| Campo | Obrigatório | Descrição |
| -------- | :---------: | -------------------------------------------------------------------------------------------------------- |
| **Nome** | Sim | Identificador do agente no dashboard. Use nomes descritivos como "Atendente SAC" ou "Vendedor Outbound". |
### Modos de Configuração
O Kiraa oferece duas formas de definir o comportamento do agente. Ao criar ou editar, escolha o modo pelo toggle **Guiado / Texto Livre**.
### Modo Guiado
O modo guiado é um formulário estruturado que orienta você a preencher as informações essenciais do agente em etapas. Ideal para quem quer rapidez e não precisa de controle granular sobre cada detalhe do prompt.
#### 1. Empresa
| Campo | Obrigatório | Descrição |
| ------------------------ | :---------: | ------------------------------------------------------------------------------------------------- |
| **Nome da empresa** | Sim | O nome da empresa que o agente representa. Ex: *Kiraa* |
| **Segmento** | Sim | O setor de atuação da empresa. Ex: *Tecnologia*, *Saúde*, *Varejo* |
| **O que a empresa faz?** | Sim | Breve descrição do negócio. Ex: *Plataforma de agentes de voz com IA para atendimento telefônico* |
#### 2. Objetivo do Agente
| Campo | Obrigatório | Descrição |
| ----------------------- | :--------------: | --------------------------------------------------------------------------------------------------------------------- |
| **Objetivo** | Sim | Selecione o objetivo principal: *Vendas*, *Suporte*, *Cobrança*, *Agendamento*, *Qualificação*, *Pesquisa* ou *Outro* |
| **Descreva o objetivo** | Sim (se "Outro") | Campo de texto livre que aparece ao selecionar "Outro" para descrever o objetivo personalizado |
#### 3. Persona e Tom de Voz
| Campo | Obrigatório | Descrição |
| ------------------ | :--------------: | ------------------------------------------------------------------------------------------------------------- |
| **Nome do agente** | Não | O nome que o agente usará na conversa. Ex: *Ana*, *Carlos*, *Sofia* |
| **Gênero** | Não | *Feminino*, *Masculino* ou *Neutro* |
| **Personalidade** | Não | Traços de personalidade. Ex: *Simpática e prestativa, mas objetiva* |
| **Tom** | Não | Selecione o tom de comunicação: *Profissional*, *Descontraído*, *Empático*, *Direto*, *Consultivo* ou *Outro* |
| **Descreva o tom** | Não (se "Outro") | Campo de texto livre que aparece ao selecionar "Outro" para descrever o tom personalizado |
#### 4. Fluxo de Conversa
Defina as etapas que o agente deve seguir durante a ligação. Cada etapa é uma instrução curta que descreve uma fase da conversa.
* Clique em **Adicionar etapa** para inserir novas etapas
* **Arraste** para reordenar as etapas
* Clique no **X** para remover uma etapa
Exemplo de fluxo para um agente de vendas:
1. Cumprimentar o cliente e se apresentar
2. Perguntar como pode ajudar
3. Identificar a necessidade do cliente
4. Apresentar a solução adequada
5. Responder objeções
6. Encaminhar para fechamento
O fluxo de conversa ajuda o agente a manter a estrutura da ligação. Quanto mais claras as etapas, mais organizada será a conversa.
### Modo Texto Livre
No modo texto livre, você escreve diretamente as instruções do agente em um campo de texto aberto. Isso dá controle total sobre o prompt e é ideal para cenários avançados ou específicos.
| Campo | Obrigatório | Descrição |
| -------------- | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Instruções** | Sim | Define quem o agente é, como se comporta e qual seu objetivo. Mínimo de 10 caracteres. Veja [Boas Práticas para Instruções](#boas-práticas-para-instruções). |
O modo Texto Livre é recomendado para usuários que já têm experiência com engenharia de prompts ou que precisam de total flexibilidade na definição do comportamento.
### Mensagem Inicial
| Campo | Obrigatório | Descrição |
| -------------------- | :---------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mensagem Inicial** | Não | A primeira frase que o agente fala ao atender. Se não definida, ele aguarda o cliente falar primeiro. Ex: *"Olá! Aqui é a Ana da Empresa X. Como posso ajudar?"* |
### Configurações de Voz
**Voz** -- Selecione a voz que o agente usará para falar. O Kiraa oferece vozes em português brasileiro, masculinas e femininas.
| Categoria | Disponibilidade | Características |
| ------------ | ------------------ | ----------------------------------- |
| **Standard** | Todos os planos | Vozes de alta qualidade |
| **Premium** | Scale e Enterprise | Vozes mais naturais e expressivas |
| **Clonada** | Enterprise | Vozes personalizadas da sua empresa |
Ouça o preview de cada voz antes de escolher. Clique no botão de play ao lado de cada opção.
**Velocidade da Fala** -- Ajuste a velocidade com que o agente fala (padrão: 1.0x). O intervalo disponível é de **0.8x** a **1.2x**.
| Velocidade | Uso recomendado |
| --------------- | ------------------------------------ |
| **0.8x - 0.9x** | Público idoso, informações complexas |
| **0.9x - 1.1x** | Uso geral (padrão) |
| **1.1x - 1.2x** | Público jovem, informações simples |
### Controle de Duração da Chamada
Para evitar que ligações se estendam indefinidamente, você define um **tempo máximo de chamada**. Quando o limite é atingido, o agente fala a mensagem de encerramento e desliga automaticamente.
| Campo | Padrão | Intervalo | Descrição |
| ---------------------------- | ------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------- |
| **Duração Máxima** | 10 min | 1 a 60 min | Tempo máximo que a chamada pode durar |
| **Mensagem de Encerramento** | *"Nosso tempo de conversa chegou ao limite. Se precisar, ligue novamente. Até mais!"* | -- | Mensagem que o agente fala quando o tempo acaba |
O timer de duração começa a contar assim que a chamada é iniciada, independente de quem está falando. Ao atingir o limite, o agente fala a mensagem de encerramento e a chamada é finalizada.
Para agentes de cobrança ou suporte complexo, considere aumentar a duração máxima para 20-30 minutos. Para qualificação rápida de leads, 5-10 minutos costuma ser suficiente.
### Reconhecimento de Voz (STT)
Estas configurações ajudam a melhorar a precisão do reconhecimento de voz do agente.
**Termos-Chave** -- Adicione palavras ou siglas específicas do seu negócio para que o reconhecimento de voz as identifique com mais precisão. Útil para nomes de produtos, marcas, siglas ou termos técnicos que o modelo pode não reconhecer naturalmente.
Exemplos: `Kiraa`, `PIX`, `CNPJ`, `TechStore`, `NF-e`
**Idioma** -- Define o idioma principal do reconhecimento de voz. O padrão é **Português Brasileiro (pt-BR)**.
***
## Templates Pré-configurados
Para acelerar a criação, o Kiraa oferece templates prontos com instruções, skills e rules otimizadas para diferentes cenários.
### Vendas Ativa (Outbound)
Ideal para ligações de prospecção e telemarketing ativo.
* Fazer o primeiro contato com potenciais clientes
* Qualificar leads através de perguntas
* Agendar reuniões com o time comercial
* Lidar com objeções iniciais
**Inclui:** 3 Skills (Abertura de Cold Call, Qualificação por Telefone, Agendamento de Reunião) e 3 Rules (Respeitar Pedido de Não Ligar, Identificar Momento Ruim, Limite de Tentativas).
### SAC Receptivo (Inbound)
Para atendimento de clientes que ligam com dúvidas ou problemas.
* Acolher o cliente com empatia
* Identificar e validar o cliente
* Resolver demandas ou direcionar corretamente
* Gerenciar esperas e transferências
**Inclui:** 3 Skills (Identificação do Cliente, Gerenciamento de Espera, Encerramento de Ligação) e 3 Rules (Não Interromper o Cliente, Comunicar Antes de Agir, Nunca Abandonar o Cliente).
### Cobrança Ativa (Outbound)
Para ligações de cobrança com foco em negociação de acordos.
* Localizar e confirmar o devedor
* Apresentar débitos de forma objetiva
* Negociar acordos dentro da alçada
* Manter ética e conformidade legal
**Inclui:** 3 Skills (Localização do Devedor, Negociação de Acordos, Lidar com Situações Difíceis) e 3 Rules (Confidencialidade Absoluta, Proibido Ameaçar, Respeitar Limites Legais).
### Cobrança Receptiva (Inbound)
Para atender devedores que ligam querendo negociar.
* Valorizar a iniciativa do cliente
* Consultar débitos rapidamente
* Oferecer as melhores condições disponíveis
* Fechar acordos na mesma ligação
**Inclui:** 3 Skills (Consulta Rápida de Débitos, Ofertas Diretas de Acordo, Orientações de Pagamento) e 3 Rules (Valorizar a Iniciativa, Resolver na Ligação, Confirmar Dados do Acordo).
### Suporte Técnico Receptivo (Inbound)
Para atendimento técnico por telefone.
* Diagnosticar problemas através de perguntas
* Guiar soluções passo a passo verbalmente
* Adaptar a linguagem ao nível do cliente
* Escalar quando necessário
**Inclui:** 3 Skills (Diagnóstico por Perguntas, Orientação Verbal, Escalação por Telefone) e 3 Rules (Adaptar ao Nível do Cliente, Confirmar Antes de Encerrar, Manter o Cliente Informado).
Ao usar um template, as Skills e Rules são criadas automaticamente e vinculadas ao agente. Você pode editá-las depois.
***
## Recursos Vinculáveis
Após criar o agente, você pode enriquecer suas capacidades vinculando recursos:
Ensine tarefas específicas com blocos de conhecimento reutilizáveis.
Defina limites e restrições de comportamento.
Conecte a APIs, encerre chamadas, transfira para humanos, agende compromissos e **aja no CRM** (mover etapa, criar tarefa, agendar retorno).
Adicione sua base de conhecimento para o agente consultar.
As **Tools CRM Action** dão ao agente o poder de operar o pipeline durante a conversa:
[`move_to_stage`](/tools#crm-action) (move o cliente entre etapas),
[`create_task`](/tasks) (delega trabalho humano),
[`schedule_callback`](/callbacks) (agenda retorno cross-channel — voz ou WhatsApp),
`add_client_tag`, `mark_converted`, `mark_wrong_person`. Configure cada uma como uma tool separada em **Studio de IA > Tools**.
### Diferença entre Instruções, Skills e Rules
| Recurso | Propósito | Escopo | Exemplo |
| -------------------------- | -------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Configuração do Agente** | Define "quem" o agente é | Único do agente | Modo Guiado: preencher empresa, objetivo e persona. Modo Texto Livre: "Você é um atendente amigável da Empresa X" |
| **Skills** | Ensina "o que" o agente sabe fazer | Reutilizável entre agentes | "Como agendar uma reunião" |
| **Rules** | Define "o que" o agente NÃO pode fazer | Reutilizável entre agentes | "Nunca revelar dados para terceiros" |
Use a **Configuração do Agente** (Guiado ou Texto Livre) para personalidade e contexto geral. Use **Skills** para procedimentos específicos. Use **Rules** para restrições e compliance.
***
## Criando seu Agente
No menu lateral, abra **Studio de IA** e clique em **Agentes**. Depois, clique em **Novo Agente** no canto superior direito.
Selecione um **template** para começar com instruções, skills e rules pré-configuradas, ou escolha **Do Zero** para configurar tudo manualmente.
Escolha um nome descritivo (ex: "Atendente SAC", "Vendedor Outbound").
Alterne entre **Guiado** e **Texto Livre** usando o toggle. No modo Guiado, preencha as informações da empresa, objetivo, persona e fluxo. No modo Texto Livre, escreva as instruções diretamente.
* Selecione a **voz** e ajuste a **velocidade da fala**
* Defina a **Mensagem Inicial** (opcional)
* Adicione **Termos-Chave** para reconhecimento de voz (opcional)
* Configure a **Duração Máxima** da chamada
Clique em **Criar Agente**. Se usou um template, as Skills e Rules são vinculadas automaticamente.
Após criar, vincule **Tools**, **Documentos**, **Skills** e **Rules** adicionais na página de detalhes do agente.
***
## Ciclo de Vida do Agente
### Estados
| Estado | Badge | Descrição |
| ----------- | ----- | ---------------------------------------------------------------------------------- |
| **Inativo** | Cinza | Agente criado mas não está em execução. Pode ser editado e configurado livremente. |
| **Ativo** | Verde | Agente em execução, pronto para atender chamadas. |
### Fluxo de Trabalho
```mermaid theme={null}
flowchart LR
A[Criar Agente] --> B[Configurar Recursos]
B --> C[Guardrails Aprovam]
C --> D[Testar no Playground]
D --> E{Funcionando?}
E -->|Sim| F[Vincular a Número]
E -->|Não| G[Editar]
G --> C
F --> H[Produção]
```
### Ativação
Ao criar um agente, ele passa por uma **análise automática de guardrails**. Quando aprovado, o agente fica ativo automaticamente — o badge muda para verde e ele está pronto para atender chamadas.
Para desativá-lo, clique em **Parar**. O agente deixará de atender chamadas imediatamente.
Ao parar um agente vinculado a um número, as chamadas para aquele número não serão mais atendidas até você reativar o agente ou vincular outro.
### Editando um Agente
Ao editar um agente, as alterações passam por uma nova análise de guardrails e são aplicadas automaticamente após aprovação.
A análise de guardrails garante que o agente esteja em conformidade com as regras de segurança da plataforma.
***
## Boas Práticas
### Dicas para o Modo Guiado
O modo guiado já orienta você a preencher as informações certas, mas algumas dicas ajudam a obter melhores resultados:
Seja específico. Em vez de "fazemos tecnologia", escreva "plataforma SaaS de gestão financeira para pequenas empresas".
Combine traços complementares. Ex: "Simpática e prestativa, mas objetiva e focada em resultados".
Crie entre 4 e 8 etapas. Poucas etapas deixam o agente sem direção; muitas tornam a conversa rígida demais.
Se nenhuma opção do select se encaixa, use "Outro" e descreva com clareza. Ex: "Confirmar presença em eventos e coletar preferências alimentares".
### Boas Práticas para Instruções
As instruções são o campo mais importante do agente no modo Texto Livre. Aqui está como escrevê-las bem:
#### Estrutura Recomendada
```text theme={null}
[IDENTIDADE]
Você é [nome/papel] da [empresa]. Seu objetivo é [objetivo principal].
[CONTEXTO]
[Descreva o cenário de uso, tipo de ligação, perfil do cliente]
[COMPORTAMENTO]
- Como deve se comunicar
- Tom de voz esperado
- Nível de formalidade
[FLUXO]
1. Primeiro passo da conversa
2. Segundo passo
3. ...
[REGRAS GERAIS]
- O que deve fazer
- O que não deve fazer
```
#### Exemplo Completo
```text theme={null}
Você é a Ana, assistente de atendimento da TechStore, uma loja de eletrônicos.
Seu objetivo é ajudar clientes com dúvidas sobre produtos e pedidos.
CONTEXTO:
Os clientes ligam com perguntas sobre especificações de produtos,
status de pedidos, trocas e devoluções. Você tem acesso ao sistema
de pedidos e catálogo de produtos.
COMPORTAMENTO:
- Seja sempre educada e prestativa
- Use linguagem clara e acessível (evite jargões técnicos)
- Demonstre paciência, mesmo com perguntas repetidas
- Chame o cliente pelo nome quando souber
FLUXO PADRÃO:
1. Cumprimente e pergunte como pode ajudar
2. Identifique a necessidade do cliente
3. Busque a informação ou execute a ação
4. Confirme se resolveu a demanda
5. Ofereça ajuda adicional antes de encerrar
REGRAS:
- Sempre confirme dados sensíveis antes de informar
- Nunca prometa prazos que não pode garantir
- Se não souber algo, diga que vai verificar
- Transfira para humano se o cliente insistir
```
#### O que Evitar
**Instruções vagas** não funcionam bem. Evite:
* "Seja um bom atendente" (muito genérico)
* "Ajude o cliente" (não especifica como)
* "Responda perguntas" (óbvio demais)
* Instruções de uma linha
* Falta de contexto
* Objetivos vagos
* Comportamento não especificado
* Regras ausentes
* Instruções detalhadas (200-500 palavras)
* Contexto claro do negócio
* Objetivos específicos e mensuráveis
* Comportamento explícito
* Regras claras de conduta
***
## Página de Detalhes do Agente
Ao clicar em um agente na listagem, você acessa a página de detalhes com:
**Cabeçalho** -- Nome, status (Ativo/Inativo), data de criação, voz selecionada, velocidade da fala e quantidade de Tools vinculadas.
**Ações** -- Ativar, Parar, Playground, Editar e Excluir (variam conforme o estado do agente).
**Seções de Recursos** -- Tools, Base de Conhecimento, Skills e Rules. Cada seção permite vincular, desvincular e visualizar os recursos.
***
## Resolução de Problemas
| Problema | Causa Provável | Solução |
| ---------------------------------- | -------------------------------------- | --------------------------------------------- |
| Agente não atende chamadas | Não está ativo ou guardrails pendentes | Verifique o status de aprovação do agente |
| Agente não aparece no Playground | Não está ativo | Ative o agente na página de detalhes |
| Alterações não aplicaram | Guardrails em análise | Aguarde a aprovação automática dos guardrails |
| Agente não usa uma Tool | Tool não vinculada | Vincule a Tool na página do agente |
| Respostas fora do contexto | Instruções vagas | Melhore as instruções com mais detalhes |
| Agente não encontra informações | Documento não vinculado | Vincule o documento ao agente |
| Chamada encerrou antes do esperado | Duração máxima baixa | Aumente o tempo em Duração Máxima |
### Checklist de Produção
Antes de colocar um agente em produção:
* [ ] Configuração do agente está completa (Guiado: todos os campos obrigatórios preenchidos / Texto Livre: instruções detalhadas e claras)
* [ ] Mensagem inicial está adequada (ou deixou vazia intencionalmente)
* [ ] Voz e velocidade estão configuradas
* [ ] Duração máxima da chamada está definida
* [ ] Skills necessárias estão vinculadas
* [ ] Rules de compliance estão vinculadas
* [ ] Tools para integrações estão vinculadas
* [ ] Documentos relevantes estão vinculados
* [ ] Agente foi testado no Playground
* [ ] Guardrails aprovaram o agente (status ativo)
* [ ] Número de telefone está vinculado (se aplicável)
***
## Excluindo um Agente
Excluir um agente é uma ação **permanente e irreversível**. Todos os vínculos com Tools, Documents, Skills e Rules serão removidos.
Na página de detalhes, clique no ícone de lixeira e confirme a exclusão.
**O que acontece ao excluir:**
* O agente é removido permanentemente
* Vínculos com Tools, Documents, Skills e Rules são desfeitos
* Se estava vinculado a um número, o número fica sem agente
* Skills, Rules e Documentos **não são excluídos** (continuam disponíveis para outros agentes)
***
## Próximos Passos
Ensine tarefas específicas aos seus agentes
Defina limites e restrições de comportamento
Integre seus agentes com sistemas externos e ações no CRM
Adicione conhecimento aos seus agentes
Vincule agentes a números para receber chamadas
Teste seus agentes em tempo real
Centralize contatos e histórico de ligações com o agente
Organize leads em etapas e use classificação automática após chamadas