Tools

As Tools (Ferramentas) são recursos configuráveis que expandem as capacidades dos seus agentes de IA durante as conversas. Com elas, seu agente pode executar ações específicas como consultar APIs, realizar cálculos ou transferir para atendimento humano.

O que você pode fazer com Tools?

Endpoint

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

Handoff

Transfira o atendimento para um humano quando necessário.

Script

Execute código Python personalizado para cálculos e lógicas complexas.

Como funcionam?

Crie a Tool

Configure uma Tool com as especificações necessárias (URL, código, departamento, 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 configurada

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.

Tipos de Tools

Endpoint
Handoff
Script

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
Verificar disponibilidade de estoque
Consultar status de pedido

Campos de Configuração

Campo	Obrigatório	Descrição
Nome	Sim	Identificador único (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
Headers	Não	Cabeçalhos HTTP (ex: Authorization)
Query Params Schema	Não	Esquema JSON dos parâmetros de URL
Body Schema	Não	Esquema JSON do corpo da requisição
Template de Resposta	Não	Formato da resposta para o agente
Quando Usar	Não	Instruções de quando acionar a Tool
Requer Confirmação	Não	Se deve confirmar antes de executar

Exemplo de Configuração

{
  "name": "consultar_cep",
  "description": "Consulta o endereço completo a partir do CEP informado",
  "method": "GET",
  "url": "https://viacep.com.br/ws/{cep}/json/",
  "when_to_use": "Quando o cliente informar um CEP ou perguntar sobre endereço"
}

Tool Handoff

Permite transferir a conversa para um atendente humano. Essencial para casos que exigem intervenção humana.Exemplos de uso:

Suporte técnico avançado
Negociações de vendas
Tratamento de reclamações
Assuntos sensíveis

Campos de Configuração

Campo	Obrigatório	Descrição
Nome	Sim	Identificador único (ex: `transferir_suporte`)
Descrição	Sim	Explica quando usar esta transferência
Departamento	Sim	Setor de destino (suporte, vendas, etc.)
Prioridade	Sim	Nível de urgência na fila
Webhook URL	Não	URL para notificar sistemas externos
Coletar Contexto	Não	Enviar histórico da conversa ao atendente
Quando Usar	Não	Instruções de quando transferir
Requer Confirmação	Não	Confirmar com usuário antes de transferir

Níveis de Prioridade

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

Exemplo de Configuração

{
  "name": "transferir_vendas",
  "description": "Transfere para o time de vendas",
  "department": "vendas",
  "priority": "high",
  "collect_context": true,
  "requires_confirmation": true,
  "when_to_use": "Quando o cliente quiser fazer uma compra ou pedir proposta"
}

Tool Script

Permite executar código Python personalizado durante a conversa. Ideal para cálculos e lógicas específicas.Exemplos de uso:

Calcular juros e parcelas
Validar documentos (CPF, CNPJ)
Converter unidades
Processar dados

Campos de Configuração

Campo	Obrigatório	Descrição
Nome	Sim	Identificador único (ex: `calcular_juros`)
Descrição	Sim	Explica o que o script faz
Código Python	Sim	Código com função `execute()`
Parâmetros	Não	Lista de parâmetros que o script recebe
Timeout	Não	Tempo máximo de execução (1-120s)
Imports Permitidos	Não	Módulos Python permitidos
Quando Usar	Não	Instruções de quando executar
Requer Confirmação	Não	Confirmar antes de executar

Tipos de Parâmetros

Tipo	Exemplo
`string`	`"texto"`
`integer`	`42`
`float`	`3.14`
`boolean`	`true`
`list`	`[1, 2, 3]`
`dict`	`{"chave": "valor"}`

Imports Disponíveis

math - Funções matemáticas
datetime - Manipulação de datas
json - Processamento de JSON
re - Expressões regulares
random - Números aleatórios

Estrutura do Código

O código deve conter uma função execute():

def execute(**kwargs):
    valor = float(kwargs.get('valor', 0))
    taxa = float(kwargs.get('taxa', 0))
    
    resultado = valor * (1 + taxa/100)
    
    return {
        "valor_final": round(resultado, 2),
        "success": True
    }

O código executa em ambiente seguro com permissões limitadas. Apenas os imports listados são permitidos.

Acessando a Página de Tools

Acesse o Dashboard

Faça login em app.tropicall.ai

Navegue para Tools

No menu lateral, clique em Tools

Visualize suas ferramentas

A página mostra cards de estatísticas, filtros e a lista de Tools criadas

Interface da Página

A página de Tools oferece:

Cards de Estatísticas: Total de Tools e quantidade por tipo
Campo de Busca: Pesquise por nome ou descrição
Filtro de Tipo: Filtre por Endpoint, Handoff ou Script
Grid de Cards: Visualize todas as suas Tools

Criando uma Tool

Tool Endpoint

Clique em Nova Tool

No canto superior direito, clique no botão Nova Tool

Selecione Endpoint

No diálogo de seleção, escolha Endpoint

Preencha as informações básicas

Nome: Identificador sem espaços (ex: consultar_produto)
Descrição: Explique claramente o que a Tool faz

Configure o endpoint

Método: Selecione GET, POST, PUT ou DELETE
URL: Informe o endereço completo da API

Adicione Headers (opcional)

Clique em Adicionar e configure os cabeçalhos HTTP necessários

Configure Schemas (opcional)

Defina os schemas JSON para parâmetros e body se necessário

Finalize

Configure o Template de Resposta e Quando Usar, depois clique em Criar Tool

Tool Handoff

Clique em Nova Tool

No canto superior direito, clique no botão Nova Tool

Selecione Handoff

No diálogo de seleção, escolha Handoff

Preencha as informações básicas

Nome: Identificador (ex: transferir_suporte)
Descrição: Explique quando usar esta transferência

Configure o handoff

Departamento: Informe o setor de destino
Prioridade: Selecione o nível de urgência

Configure opções

Coletar Contexto: Ative para enviar histórico ao atendente
Requer Confirmação: Ative para confirmar antes de transferir

Finalize

Preencha Quando Usar e clique em Criar Tool

Tool Script

Clique em Nova Tool

No canto superior direito, clique no botão Nova Tool

Selecione Script

No diálogo de seleção, escolha Script

Preencha as informações básicas

Nome: Identificador (ex: calcular_desconto)
Descrição: Explique o que o script faz

Escreva o código

Implemente a função execute(**kwargs) que retorna um dicionário

Defina os parâmetros

Clique em Adicionar para cada parâmetro e configure nome, tipo e descrição

Configure imports

Adicione os módulos Python que seu código precisa usar

Finalize

Defina o Timeout, configure Quando Usar e clique em Criar Tool

Vinculando Tools a Agentes

Após criar uma Tool, você precisa vinculá-la 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

Clique em Vincular Tool

Clique no botão Vincular Tool

Selecione a Tool

Na aba Tools Existentes, busque e selecione a Tool desejada, ou crie uma nova na aba Criar Nova

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.

Exemplos Práticos

Consulta de CEP

{
  "type": "endpoint",
  "name": "consultar_cep",
  "description": "Busca o endereço completo a partir do CEP",
  "config": {
    "method": "GET",
    "url": "https://viacep.com.br/ws/{cep}/json/",
    "response_template": "Endereço: {logradouro}, {bairro} - {localidade}/{uf}",
    "when_to_use": "Quando o cliente informar um CEP"
  }
}

Transferência para Vendas

{
  "type": "handoff",
  "name": "transferir_vendas",
  "description": "Transfere para equipe de vendas",
  "config": {
    "department": "vendas",
    "priority": "high",
    "collect_context": true,
    "requires_confirmation": true,
    "when_to_use": "Quando o cliente quiser comprar ou pedir proposta"
  }
}

Calculadora de Parcelas

def execute(**kwargs):
    valor = float(kwargs.get('valor', 0))
    parcelas = int(kwargs.get('parcelas', 1))
    taxa = float(kwargs.get('taxa', 0))
    
    if taxa > 0:
        taxa_decimal = taxa / 100
        valor_parcela = valor * (taxa_decimal * (1 + taxa_decimal)**parcelas) / ((1 + taxa_decimal)**parcelas - 1)
    else:
        valor_parcela = valor / parcelas
    
    return {
        "valor_parcela": round(valor_parcela, 2),
        "total_a_pagar": round(valor_parcela * parcelas, 2)
    }

Boas Práticas

Nomenclatura

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

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.

Segurança

Nunca exponha credenciais na URL. Use headers para autenticação.

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 está clara
Endpoint retornando erro	Confirme URL, headers e teste a API diretamente
Script falhando	Verifique se `execute()` existe e se os imports estão listados
Handoff não transfere	Confirme departamento e se “Requer Confirmação” não está bloqueando

Próximos Passos

Agora que você sabe como usar Tools, explore outros recursos:

Documentos

Adicione conhecimento aos seus agentes via RAG

Playground

Teste seus agentes com Tools configuradas

Começando

Recursos

​Tools

​O que você pode fazer com Tools?

Endpoint

Handoff

Script

​Como funcionam?

​Tipos de Tools

​Tool Endpoint

​Campos de Configuração

​Exemplo de Configuração

​Tool Handoff

​Campos de Configuração

​Níveis de Prioridade

​Exemplo de Configuração

​Tool Script

​Campos de Configuração

​Tipos de Parâmetros

​Imports Disponíveis

​Estrutura do Código

​Acessando a Página de Tools

​Interface da Página

​Criando uma Tool

​Tool Endpoint

​Tool Handoff

​Tool Script

​Vinculando Tools a Agentes

​Exemplos Práticos

​Consulta de CEP

​Transferência para Vendas

​Calculadora de Parcelas

​Boas Práticas

Nomenclatura

Descrições

Campo Quando Usar

Segurança

​Resolução de Problemas

​Próximos Passos

Documentos

Playground

Tools

O que você pode fazer com Tools?

Como funcionam?

Tipos de Tools

Tool Endpoint

Campos de Configuração

Exemplo de Configuração

Tool Handoff

Campos de Configuração

Níveis de Prioridade

Exemplo de Configuração

Tool Script

Campos de Configuração

Tipos de Parâmetros

Imports Disponíveis

Estrutura do Código

Acessando a Página de Tools

Interface da Página

Criando uma Tool

Tool Endpoint

Tool Handoff

Tool Script

Vinculando Tools a Agentes

Exemplos Práticos

Consulta de CEP

Transferência para Vendas

Calculadora de Parcelas

Boas Práticas

Resolução de Problemas

Próximos Passos