Ferramentas externas (APIs personalizadas)
Conecte APIs próprias — CRM, catálogo de produtos, estoque, base de imóveis ou qualquer sistema com API HTTP — para que seus agentes de IA consultem dados em tempo real durante conversas.
O que é
As ferramentas externas permitem que um agente Treffen AI chame a sua API como se fosse uma ferramenta interna. Durante uma conversa, a IA decide quando consultar sua API, envia os parâmetros corretos e usa a resposta para responder ao cliente.
Exemplo (imobiliária): o cliente pergunta "Vocês têm apartamento de 2 quartos em São Paulo até R$ 800 mil?". O agente chama a ferramenta search_properties na API do CRM e responde com os imóveis disponíveis.
Quando usar
| Cenário | Exemplo de ferramenta |
|---|---|
| Catálogo ou estoque | search_products, get_product |
| CRM ou base de clientes | get_customer, update_lead |
| Imóveis ou veículos | search_properties, get_property |
| Disponibilidade externa | check_stock, get_price |
Se o dado já está no Treffen (contatos, tickets, calendário de reservas), use as ferramentas nativas da plataforma. APIs personalizadas são para sistemas externos que você já opera.
Como configurar
1. Criar a integração
No painel administrativo, acesse a área de Integrações (ou APIs personalizadas, conforme o menu do seu tenant) e crie uma nova integração:
| Campo | Descrição |
|---|---|
| Nome | Identificação interna (ex.: "CRM Imobiliária") |
| URL base | Endereço HTTPS da sua API (ex.: https://api.seucrm.com/v1) |
| Autenticação | Bearer token, API key no header ou Basic |
| Hosts permitidos | Domínios que a plataforma pode chamar (segurança) |
Use Testar integração para validar credenciais e conectividade antes de ativar.
2. Definir ferramentas
Para cada operação que a IA pode executar, crie uma ferramenta:
| Campo | Descrição |
|---|---|
| Nome da ferramenta | Identificador em minúsculas com underscore (ex.: search_properties) |
| Descrição | O que a ferramenta faz — a IA usa isso para decidir quando chamá-la |
| Método HTTP | GET, POST, etc. |
| Caminho | Path com parâmetros entre chaves (ex.: /properties?city={city}&max_price={max_price}) |
| Parâmetros | Schema JSON dos parâmetros aceitos (cidade, quartos, preço máximo, etc.) |
Exemplo de ferramenta de busca de imóveis:
- Nome:
search_properties - Descrição: Buscar imóveis disponíveis por cidade, quartos e preço máximo em BRL
- Método:
GET - Caminho:
/properties?city={city}&bedrooms={bedrooms}&max_price={max_price} - Parâmetros obrigatórios:
city
3. Ativar a integração
Após criar pelo menos uma ferramenta habilitada, ative a integração. Integrações inativas não são usadas pelos agentes.
4. Habilitar no agente
Em Treffen AI → Agentes, edite o agente desejado e inclua as ferramentas externas no conjunto de ferramentas habilitadas (enabled toolsets). Somente ferramentas habilitadas no agente podem ser chamadas durante conversas.
Veja também Como criar um agente.
Segurança e limites
A plataforma aplica proteções automáticas ao chamar APIs externas:
| Proteção | O que significa para você |
|---|---|
| HTTPS obrigatório | Apenas URLs seguras (exceto em ambientes de desenvolvimento) |
| Bloqueio de endereços internos | IPs privados e redes internas não são acessíveis (proteção SSRF) |
| Hosts permitidos | Só domínios que você autorizou podem ser chamados |
| Limite de resposta | Respostas muito grandes são truncadas antes de chegar à IA |
| Isolamento por tenant | Cada conta só acessa suas próprias integrações |
| Timeout | Chamadas que demoram demais são encerradas (máx. ~30 segundos) |
Credenciais (tokens, senhas) são armazenadas de forma criptografada e nunca aparecem em logs ou respostas da IA.
Solução de problemas
| Problema | Possível causa | O que fazer |
|---|---|---|
| Ferramenta não encontrada | Nome incorreto ou integração inativa | Verifique o nome exato e se a integração está ativa |
| Timeout | API lenta ou indisponível | Teste a API diretamente; otimize tempo de resposta |
| Host não permitido | Domínio fora da lista de hosts | Adicione o domínio em Hosts permitidos |
| Erro 4xx/5xx | Credenciais ou path incorretos | Use Testar integração e revise path e parâmetros |
| IA não chama a ferramenta | Ferramenta não habilitada no agente | Inclua a ferramenta no agente em enabled toolsets |
| Resposta incompleta | Muitos registros na resposta | Reduza o volume retornado pela sua API ou use filtros mais específicos |
Perguntas frequentes
Preciso de desenvolvedor para configurar? Sim, é necessário que sua API esteja documentada e acessível via HTTPS. A configuração no Treffen pode ser feita por um administrador com os dados da API.
A IA vê minhas credenciais? Não. A plataforma injeta a autenticação automaticamente; a IA recebe apenas o resultado da consulta.
Quantas ferramentas posso criar? Não há limite fixo documentado; organize por integração (ex.: uma integração "CRM" com várias ferramentas).
Funciona com qualquer API REST? Sim, desde que use HTTPS, retorne JSON e os endpoints estejam acessíveis publicamente (com autenticação).
Links relacionados
- Agentes — Criar e configurar agentes de IA
- Como adicionar conhecimento — RAG com documentos e sites
- SDR Studio — Fluxos de qualificação SDR
- Bots e IA — Provedores de IA e automações
- Referência da API — API do Treffen para integrações inversas