Ferramentas HTTP Customizadas

Ferramentas HTTP customizadas permitem que um agente consulte ou acione uma API REST, como um webhook do n8n ou Make, um CRM, um ERP ou um serviço próprio. A configuração-base pertence à organização; cada agente recebe apenas um vínculo e, se necessário, overrides dos parâmetros.

Para entender como a chamada é executada, veja também Chamada HTTP (infraestrutura).

Antes de começar

Confirme quatro pontos fora do SquadOS:

1. o método e a URL pública do endpoint;
2. o formato exato de path, query, headers e corpo;
3. a autenticação e uma credencial com o menor privilégio possível;
4. se a chamada apenas consulta dados ou produz efeitos, como criar, atualizar ou excluir registros.

Use um endpoint e uma credencial de teste durante a configuração. O painel de teste envia uma requisição real e pode produzir o mesmo efeito externo de uma chamada feita pelo agente.

Criar a ferramenta

1. No menu lateral, abra Ferramentas → Ativas.
2. Na seção Ferramentas Customizadas, selecione Nova Ferramenta.
3. No seletor Nova Ferramenta, escolha Ferramenta HTTP / API. A outra opção cria um Servidor MCP.
4. Preencha o drawer Criar ferramenta HTTP e selecione Criar ferramenta.

Criar ou editar exige Editar ferramentas (tools.write). Excluir exige Excluir ferramentas (tools.delete). Ferramentas salvas aparecem como Ativa sem depender de um teste bem-sucedido.

Identidade e endpoint

Campo	Contrato atual
Nome da ferramenta	Obrigatório. Nome amigável mostrado no painel; até 100 caracteres. O modelo não recebe esse nome.
Nome técnico (usado pela IA)	Gerado a partir do nome amigável em letras minúsculas, números e _. Selecione Personalizar para alterá-lo. É único na organização e aparece ao modelo.
Descrição	Opcional, até 500 caracteres. Diga o que a ferramenta faz, quando deve ser chamada e quando não deve. O modelo usa esse texto para escolher a ferramenta.
Método	GET, POST, PUT, PATCH ou DELETE.
URL do endpoint	Obrigatória, até 2.048 caracteres. Use :chave para um parâmetro de path, por exemplo https://api.exemplo.com/users/:id.

O salvamento verifica apenas se nome e URL não estão vazios; ele não comprova que a URL é válida, pública ou alcançável. Use Testar ferramenta antes de vincular a configuração a um agente.

Caution

O runtime aceita somente http e https e bloqueia localhost, redes privadas e reservadas e endpoints de metadados de nuvem. Uma URL recusada no teste ou na conversa deve ser corrigida; não tente contornar a proteção.

Autenticação

Tipo	Header enviado
Nenhuma	Nenhum header de autenticação.
Bearer Token	Authorization: Bearer SEU_TOKEN.
API Key (Header)	Header configurado ou X-API-Key quando o nome fica vazio; o valor é o segredo.
Header customizado	Header configurado ou Authorization; pode acrescentar um prefixo, como Token.

Ao editar, o segredo é um campo de escrita: deixe-o vazio para preservar o valor atual e preencha-o para substituir. O executor recupera a credencial no servidor e nunca a inclui no prompt ou no resultado entregue ao modelo.

Danger

Apesar do texto atual da interface afirmar que o segredo é criptografado, a implementação auditada grava o valor diretamente na coluna de segredo. Use credenciais dedicadas e restritas, faça rotação periódica e não trate esse armazenamento como um cofre criptografado em repouso.

Selecionar Nenhuma impede o uso do segredo, mas não apaga o valor já armazenado. Não existe ação separada para remover apenas a credencial: para garantir sua invalidação, revogue-a no serviço de destino; excluir a ferramenta remove o registro associado.

Parâmetros que o modelo pode enviar

Os parâmetros formam o JSON Schema mostrado ao modelo. Cada linha do construtor visual oferece:

• Nome;
• Tipo: string, number, boolean ou object;
• Descrição.

Selecione Adicionar para criar outra linha. O construtor visual atual não oferece controle Obrigatório; toda linha nova é opcional. Para definir required, enum, array, objeto aninhado ou outras constraints, use Editar como JSON Schema (avançado). O texto aceita até 64.000 caracteres e só é validado como JSON sintaticamente válido ao salvar.

Exemplo de schema com um argumento obrigatório:

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

Danger

O editor atual não preserva schemas avançados ao reabrir a ferramenta: ele volta ao construtor visual e retém somente nome, tipo, descrição e lista required. Salvar novamente pode remover enum, array, estrutura aninhada e outras constraints. Guarde o schema-fonte fora do SquadOS e não reedite uma ferramenta que dependa desses recursos sem conferir o contrato completo.

Corpo JSON

O bloco Corpo JSON aparece dentro de Avançado somente para métodos diferentes de GET. Ele aceita até 64.000 caracteres e combina valores fixos com placeholders {{nome_do_parametro}}.

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

Se o modelo enviar texto: "Cliente não consegue acessar", o corpo será:

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

Quando o template é JSON válido, campos cujo placeholder não recebeu valor são removidos. Quando o template deixa de ser JSON válido, o executor envia o texto resultante sem converter ou validar. Sem template, os argumentos do modelo formam um objeto JSON simples.

Opções avançadas

Abra Avançado para configurar:

Headers customizados

São enviados em toda requisição. O executor começa com Content-Type: application/json, aplica os headers customizados e, por último, injeta o header de autenticação. Portanto, a autenticação configurada prevalece quando usa o mesmo nome de header.

Parâmetros de path

Cada linha tem Chave, Valor padrão e IA fornece. A chave substitui :chave na URL e o valor é codificado para URL. Quando IA fornece está ativo, o parâmetro entra no contrato do agente como obrigatório; quando está desativado, o valor fixo é usado.

Parâmetros de query

Também usam Chave, Valor padrão e IA fornece. Em GET, valores já escritos na URL têm precedência, depois entram as linhas configuradas e, por fim, argumentos adicionais do modelo que ainda não existem na query.

Timeout

O campo aceita de 1.000 a 300.000 ms, mas runtime e teste aplicam um teto efetivo de 30.000 ms (30 segundos). Não configure um valor maior esperando que a chamada aguarde mais.

Enviar metadados da conversa

Acrescenta conversation_id, conversation_title, external_contact, agent_id, model_used, ai_enabled e external_user_id. Isso ocorre somente em métodos diferentes de GET, quando o corpo final é um objeto JSON válido. Chaves já definidas no corpo prevalecem.

Fornecer identidade do lead ao contexto

Disponibiliza ao modelo o identificador externo e o nome do contato para que ele possa preencher argumentos. Essa opção não acrescenta automaticamente os dados ao endpoint. Ative apenas quando a finalidade da ferramenta exigir identificação do lead.

Caution

Fechar o drawer após alterar apenas schema, corpo, headers, path/query, timeout ou os dois controles de contexto pode descartar a mudança sem mostrar Descartar alterações?. Salve explicitamente antes de sair.

Testar a ferramenta

O painel Testar ferramenta permanece no final do drawer.

1. Preencha os valores de teste.
2. Selecione Executar teste.
3. Confira status HTTP, duração e corpo exibidos.
4. Verifique no sistema de destino a URL, os headers, o corpo e qualquer efeito criado.

O teste usa a credencial digitada ou, ao editar, o segredo já armazenado. Ele envia uma requisição real, mas não reproduz perfeitamente o runtime:

• trata todos os argumentos como strings de até 100 caracteres, mesmo quando o schema declara number, boolean ou object;
• pode montar parâmetros de query configurados de forma diferente;
• substitui placeholders ausentes do corpo de forma diferente;
• usa metadados fictícios de conversa;
• recebe indicador de truncamento e headers de resposta, mas o painel não os mostra.

Um teste verde não grava estado de validação e não garante que a chamada do agente será idêntica. Faça também uma conversa controlada com um agente de teste.

Vincular e configurar no agente

1. Abra Agentes → seu agente → Ferramentas.
2. Selecione Adicionar Ferramenta.
3. Em Outras Ferramentas, escolha a ferramenta HTTP.
4. Abra a ferramenta vinculada para configurar cada parâmetro como valor decidido pela IA, valor manual ou Não enviar quando for opcional.
5. Salve e teste uma nova conversa.

Parâmetros de path fornecidos pela IA são obrigatórios. Parâmetros opcionais podem ser omitidos. O link Configuração base é gerenciada em Admin > Ferramentas volta ao editor organizacional.

Caution

O seletor do agente ainda não acompanha todas as permissões granulares. Um usuário pode ver um vínculo que o backend recusará; uma função personalizada com tools.write também pode não ver Nova Ferramenta porque esse atalho ainda depende do papel legado Admin. Crie a configuração-base em Ferramentas e confira também agents.write.

Editar, recuperar e excluir

Ao editar uma ferramenta vinculada, o SquadOS mostra Esta ferramenta está em uso e lista quantos agentes serão afetados. A mudança na configuração-base vale imediatamente para todos eles.

Configuração, sincronização dos vínculos e segredo são salvos em etapas separadas. Se aparecer erro, recarregue a lista antes de repetir: confirme o valor realmente persistido e procure uma ferramenta duplicada. Uma falha tardia pode deixar somente parte da alteração aplicada.

Para excluir, remova primeiro a ferramenta de todos os agentes; a chave estrangeira bloqueia a exclusão enquanto houver vínculos. Excluir a ferramenta é irreversível e também remove seu registro de segredo.

Limites que afetam a resposta do agente

• cada chamada termina em no máximo 30 segundos;
• o corpo da resposta é lido até 1 MiB;
• o modelo não recebe aviso quando esse corpo foi truncado;
• respostas JSON válidas viram dados estruturados; outras respostas chegam como texto;
• em status não 2xx, o agente recebe o status e somente os primeiros 500 caracteres do corpo de erro;
• uma chamada idêntica não é repetida no mesmo turno;
• até três chamadas HTTP podem executar em paralelo no mesmo lote.

Prefira endpoints paginados, respostas pequenas e operações idempotentes. Para ações com efeito externo, aceite uma chave de idempotência e registre no sistema de destino o identificador da conversa ou da operação.

Checklist de publicação

• O nome técnico descreve uma única ação e a descrição explica quando chamar.
• O schema contém somente argumentos que o modelo deve decidir.
• Valores sensíveis e constantes estão no servidor ou como valores fixos, nunca no prompt.
• A credencial tem escopo mínimo e pode ser revogada sem afetar outros sistemas.
• Path, query, headers e corpo foram confirmados no sistema de destino.
• Erros 4xx, 5xx, timeout e resposta vazia foram testados.
• O endpoint é idempotente ou protege contra repetição entre turnos.
• A versão salva foi validada em um agente de teste antes de chegar a conversas reais.