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.

Onde criar

As ferramentas HTTP customizadas são criadas no painel admin em Ferramentas → Ativas → Nova Ferramenta Customizada.

Depois de criada, ela aparece na seção Outras Ferramentas quando você clica em + Adicionar Ferramenta dentro de qualquer agente da organização.

O formulário

Clicar em + Nova Ferramenta Customizada abre o modal Criar ferramenta HTTP.

Identificação

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 (usado pela IA)	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. 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.

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.

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).
Header customizado	Igual ao API Key, mas permite adicionar 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 — só preencha se quiser substituir o segredo.

Conceito-chave: Parâmetros vs. Body JSON

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.

Exemplo prático

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 (corpo enviado ao endpoint):

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

Quando o agente chama dizendo texto: "Cliente não consegue acessar", o SquadOS envia:

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

canal e prioridade são fixos; {{texto}} foi substituído pelo valor da IA.

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.

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:

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.

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. Se desmarcado, o valor padrão é sempre usado.

Parâmetros de query

Adicionados à URL como ?chave=valor. Mesma lógica dos path params.

Outras

• 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 informações como conversation_id, agent_id, external_contact. Útil para webhooks que precisam correlacionar com a conversa.

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).

A ferramenta só fica com indicador verde (configurada) após um teste com sucesso.

Conectando ao agente

Depois de salva, a ferramenta aparece em Outras Ferramentas quando você clica em + Adicionar Ferramenta dentro de qualquer agente:

1. Abra o agente em Agentes → [seu agente] → Ferramentas.
2. Clique em + Adicionar Ferramenta.
3. Em OUTRAS FERRAMENTAS, escolha a ferramenta HTTP que você acabou de criar.
4. (Opcional) Configure overrides por agente se quiser fixar valores específicos 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 da organização afeta imediatamente todos os agentes que a usam.
• Um propósito por ferramenta: em vez de uma “super ferramenta” com 20 parâmetros, prefira várias específicas. A IA escolhe melhor entre ferramentas especializadas.