Ferramentas do Agente

Ferramentas são capacidades extras que a Dani pode usar durante uma conversa. Existem dois tipos: ferramentas nativas (já vêm prontas) e ferramentas HTTP customizadas (você cria para integrar com sistemas externos).

Ferramentas nativas (builtins)

As ferramentas abaixo estão disponíveis para todos os agentes sem necessidade de configuração adicional. O modelo de IA decide quando usá-las com base no contexto da conversa e nas instruções do prompt.

Ferramenta	O que faz
transfer_queue	Transfere o ticket para uma fila específica pelo nome exato da fila
transferir_humano	Entrega o ticket para atendimento humano (encerra a IA naquele ticket)
close_ticket	Encerra o ticket com mensagem de despedida
agendar	Consulta horários disponíveis e confirma agendamentos na agenda nativa
send_quick_message	Envia uma resposta rápida pré-cadastrada (com mídia) pelo shortcode
enroll_floup	Inscreve o contato em uma sequência automática (Floup)
pause_floup	Cancela o floup ativo do contato
list_floups	Lista todos os floups disponíveis na empresa
query_active_floups	Verifica em quais floups o contato atual está inscrito
provedor_consultar_cliente	Consulta cadastro de cliente por CPF no ERP do provedor de internet (IXC/SGP)
provedor_segunda_via	Envia 2ª via de boleto/PIX para o cliente pelo CPF
provedor_status_conexao	Verifica situação da conexão do cliente no ERP
provedor_reiniciar_conexao	Reinicia a conexão de internet do cliente (exige confirmação explícita)
provedor_desbloqueio_confianca	Faz desbloqueio temporário para clientes suspensos por débito

Ferramentas de provedor

As ferramentas provedor_* exigem configuração prévia do ERP (IXC Soft ou SGP) nas integrações da empresa. Sem a integração configurada, essas ferramentas retornam erro.

Como orientar o uso das ferramentas no prompt

Mencione explicitamente no campo Personalidade quando e como usar cada ferramenta. Exemplo para a ferramenta de agendamento:

Quando o cliente quiser marcar um horário, use a ferramenta 'agendar'
sem parâmetros primeiro para listar os slots disponíveis. Depois,
quando ele confirmar data e horário, chame novamente com os dados.
Só confirme o agendamento se a ferramenta retornar ok=true.

---

Ferramentas HTTP customizadas

Você pode criar ferramentas que chamam qualquer API REST externa. Assim a Dani pode consultar seu CRM, sistema de pedidos, banco de dados de clientes — qualquer sistema que tenha uma API.

Acessando as ferramentas customizadas

1. Abra o agente (ícone de lápis)
2. Vá para a aba Ferramentas (sétima aba)
3. Clique em "Nova ferramenta"

WARNING

Salve o agente antes de criar ferramentas customizadas. O botão "Nova ferramenta" fica desabilitado enquanto o agente não foi salvo.

Campos de uma ferramenta HTTP

Identificação:

Campo	Regras	Exemplo
Nome	snake_case, único por agente. Não pode ser alterado após salvo	consultar_pedido
Descrição	O modelo de IA lê isso para decidir quando usar. Seja explícito	"Consulta o status de um pedido pelo número. Use quando o cliente perguntar sobre entrega ou status de compra."
Ativa	Toggle liga/desliga a ferramenta sem excluir

Requisição HTTP:

Campo	Descrição
Tipo	Sempre "HTTP (REST API externa)" — é o único tipo disponível
Método	GET, POST, PUT, DELETE ou PATCH
URL	Endpoint completo (ex: https://api.meucrm.com/pedidos/)
Headers	JSON com cabeçalhos fixos (ex: {"Content-Type": "application/json"})
Body template	Template Mustache do corpo da requisição. Use para injetar os valores passados pelo agente (ex: {"id":""})

Schema dos parâmetros:

O campo paramsSchema é um JSON Schema que diz ao modelo de IA quais informações ele precisa coletar do cliente para chamar a ferramenta. Exemplo para consultar pedido por número:

{
  "type": "object",
  "required": ["numero_pedido"],
  "properties": {
    "numero_pedido": {
      "type": "string",
      "description": "Número do pedido informado pelo cliente"
    }
  }
}

Resposta:

Campo	Descrição
responseTemplate	Template Mustache opcional para formatar a resposta da API antes de enviar ao modelo. Se vazio, o modelo recebe o JSON bruto e interpreta naturalmente

Autenticação:

Tipo	Campos adicionais
Nenhuma	—
Bearer token	Token (mascarado após salvo)
Basic auth	Username e Password
API key no header	Nome do header (ex: X-Api-Key) e Valor
API key na query	Nome do parâmetro e Valor

Segredos (tokens e senhas) são mascarados na tela após salvamento (exibem ••••1234). Para trocar, basta digitar o novo valor.

Configuração avançada:

{"timeoutMs": 15000}

timeoutMs define quanto tempo (em ms) o sistema aguarda a resposta da API antes de desistir. Padrão: 15 segundos.

Testando uma ferramenta antes de ativar

Cada ferramenta salva tem um botão de play (Testar). Clique nele para abrir o diálogo de dry-run:

1. O sistema pré-preenche um JSON com os campos do paramsSchema
2. Edite os valores com dados reais de teste
3. Clique em "Executar"
4. O painel exibe: requisição montada (método, URL, headers, body), resposta HTTP (status, corpo) e tempo de execução

Isso permite validar a integração sem precisar conversar com a Dani.

Problemas comuns nas ferramentas

A Dani chama a ferramenta mas nunca recebe a informação certa

Revise a descrição da ferramenta. O modelo decide quando chamar e quais parâmetros usar com base apenas na descrição e no schema. Se a descrição for vaga, o modelo pode chamar na hora errada ou omitir campos obrigatórios.

Timeout na execução

A API externa está demorando mais de timeoutMs. Aumente o timeout no campo config ou otimize o endpoint externo.

Erro de autenticação (401/403)

O token ou chave de API expirou. Edite a ferramenta e insira as novas credenciais.

A ferramenta não aparece na aba

O agente ainda não foi salvo. Salve antes de criar ferramentas.