Ferramentas HTTP Customizadas

Ferramentas HTTP customizadas permitem que seus agentes chamem qualquer API REST — webhooks do n8n/Make, CRMs, serviços internos, bots do Slack, etc. Você configura o endpoint uma única vez no nível da organização e depois conecta a ferramenta aos agentes que precisam dela.

Este guia cobre a criação passo a passo, explicando o que cada campo do formulário faz.

Onde criar

As ferramentas HTTP customizadas são criadas no painel admin:

Admin → Ferramentas → Ferramentas HTTP Customizadas → Nova Ferramenta Customizada

Depois de criada, ela aparece na aba Ferramentas de qualquer agente da organização e pode ser conectada com um clique.

Conceito-chave: Parâmetros vs. Body JSON

Antes de sair preenchendo o formulário, entenda a distinção mais importante:

Campo	Função
Parâmetros	Define o que a IA pode enviar quando chama a ferramenta. Vira o “contrato” que o modelo vê.
Body JSON	Define como esses valores são empacotados no corpo da requisição HTTP.

Os dois trabalham juntos: a IA preenche os parâmetros e o Body JSON usa {{placeholders}} para montar o payload final.

Exemplo prático

Imagine uma ferramenta que notifica um atendente humano via webhook:

Parâmetros (o que a IA envia):

{
  "type": "object",
  "properties": {
    "texto": {
      "type": "string",
      "description": "Resumo do problema do cliente"
    }
  },
  "required": ["texto"]
}

Body JSON (o que vai no corpo da requisição):

{"mensagem": "{{texto}}", "canal": "web", "prioridade": "alta"}

Quando o agente chama a ferramenta dizendo texto: "Cliente não consegue acessar o dashboard", o SquadOS envia para o endpoint:

{
  "mensagem": "Cliente não consegue acessar o dashboard",
  "canal": "web",
  "prioridade": "alta"
}

Repare que canal e prioridade são fixos (não vieram do modelo) e {{texto}} foi substituído pelo que a IA gerou.

Dica

Se você deixar o Body JSON em branco, o SquadOS envia os parâmetros como JSON flat (sem renomear nem adicionar campos fixos). Use Body JSON quando precisar de aninhamento, renomear campos ou adicionar valores fixos.

Passo a passo

1. Identificação da ferramenta

Campo	O que preencher
Nome da ferramenta	Nome amigável só para você, visto no painel. A IA não vê este texto. Ex: Atribuir Humano CRM.
Nome técnico	Identificador que a IA usa ao chamar a ferramenta. Apenas letras minúsculas, números e underscores. Ex: atribuir_humano_crm.
Descrição	O campo mais importante para a qualidade das chamadas. Explique o que a ferramenta faz e quando usá-la. A IA decide acionar a ferramenta baseada neste texto. Ex: Usa quando for necessário atribuir atendimento humano para questões que a IA não consegue esclarecer.

2. Método e URL

• Método HTTP: GET, POST, PUT, PATCH ou DELETE. O campo Body JSON só aparece quando o método não é GET.
• URL do endpoint: URL completa. Você pode usar :chave para marcar parâmetros de path (ex: https://api.exemplo.com/users/:id) — esses parâmetros são configurados na seção Parâmetros de path mais abaixo.

3. Autenticação

Como o SquadOS se autentica com a API. O segredo é armazenado criptografado no servidor e a IA nunca tem acesso a ele.

Tipo	Como funciona
Nenhuma	Endpoint público, sem autenticação.
Bearer Token	Envia Authorization: Bearer SEU_TOKEN.
API Key (Header)	Envia um header customizado (ex: X-API-Key: SEU_TOKEN). Você define o nome do header.
Header customizado	Igual ao API Key, mas permite adicionar um prefixo ao valor (ex: Authorization: Token SEU_TOKEN).

Ao editar uma ferramenta existente, o campo de segredo aparece vazio com placeholder •••••••• (manter atual). Deixe vazio para preservar o valor atual — só preencha se quiser substituir o segredo.

4. Body JSON (para POST/PUT/PATCH/DELETE)

Template do corpo enviado ao endpoint. Aceita:

• Valores fixos: {"canal": "web"} → canal sempre será "web".
• Placeholders: {"mensagem": "{{texto}}"} → {{texto}} é substituído pelo parâmetro texto em tempo real.
• Aninhamento: {"data": {"user": {"name": "{{nome}}"}}}.
• Arrays: {"tags": ["{{categoria}}", "alta"]}.

Se deixar em branco, o SquadOS envia os parâmetros da IA direto como JSON flat.

5. Parâmetros

O contrato que descreve para a IA quais argumentos ela pode/deve enviar. Há dois modos de edição:

• Builder: interface visual com linhas nome / tipo / descrição / obrigatório. Ideal para casos simples.
• JSON Schema: cole um JSON Schema completo. Útil para tipos complexos (enums, objetos aninhados, arrays tipados).

Cada parâmetro definido aqui:

1. Vira um {{placeholder}} disponível no Body JSON.
2. É descrito para a IA — descrições claras melhoram muito a precisão.
3. Pode ser marcado como required para forçar a IA a fornecê-lo.

Cuidado

Sem parâmetros, a IA não tem o que passar para a ferramenta. Se o Body JSON tem {{texto}} mas o parâmetro texto não foi definido, o placeholder fica literal no payload enviado.

6. Configurações avançadas (opcionais)

Expanda as seções colapsáveis no final do formulário:

Headers customizados

Headers HTTP enviados em toda requisição, além dos de autenticação. Use para Content-Type, Accept, X-Source, etc.

Parâmetros de path

Substituem trechos da URL marcados com :chave. Exemplo: URL https://api.exemplo.com/users/:id com path param id.

Cada path param tem:

• Chave: nome do placeholder na URL (sem o :).
• Valor padrão: valor fixo a usar se a IA não fornecer.
• IA fornece: se marcado, a IA preenche em runtime com base nos parâmetros. Se desmarcado, o valor padrão é sempre usado.

Parâmetros de query

Adicionados à URL como ?chave=valor. Mesma lógica dos path params (chave + valor padrão + IA fornece).

Configurações avançadas

• Timeout: tempo máximo (em ms) que o SquadOS espera pela resposta. Padrão: 30000ms (30s).
• Enviar metadados da conversa: quando marcado, adiciona ao body da requisição informações como conversation_id, agent_id, external_contact, etc. Útil para webhooks que precisam correlacionar a chamada com a conversa no SquadOS.

Testando a ferramenta

Antes de salvar, use o botão Testar no rodapé do modal. Ele abre um painel que:

1. Mostra os parâmetros obrigatórios para você preencher manualmente.
2. Executa a requisição real contra o endpoint.
3. Exibe a resposta completa (status HTTP + corpo).

Use o teste para validar autenticação, formato do body e estrutura da resposta antes de conectar a ferramenta aos agentes.

Conectando ao agente

Depois de salva, a ferramenta aparece na aba Ferramentas de qualquer agente:

1. Abra o agente em Admin → Agentes → [seu agente].
2. Vá até a aba Ferramentas.
3. Clique em Adicionar ferramenta e selecione a ferramenta HTTP criada.
4. (Opcional) Configure overrides por agente se quiser fixar valores específicos para este agente sem alterar a ferramenta base.

A IA passa a ter a ferramenta disponível imediatamente nas próximas conversas.

Boas práticas

• Descrições importam: a qualidade da descrição da ferramenta e dos parâmetros é o que mais afeta a precisão das chamadas. Seja específico sobre quando usar.
• Use required nos parâmetros que são realmente obrigatórios. Isso força a IA a perguntar ao usuário se faltar informação.
• Teste antes de conectar: um endpoint mal configurado em produção gera erros em todas as conversas dos agentes que usam a ferramenta.
• Edite com cuidado: alterar uma ferramenta afeta imediatamente todos os agentes que a usam. O SquadOS avisa quantos agentes serão impactados antes de salvar.
• Um propósito por ferramenta: em vez de uma “super ferramenta” com 20 parâmetros, prefira várias ferramentas específicas. A IA escolhe melhor entre ferramentas especializadas.