Chamada HTTP (infraestrutura)

O que é

Chamada HTTP é a infraestrutura que permite a um agente consultar ou acionar uma API por meio de uma ferramenta HTTP customizada. Você não adiciona esse item pelo catálogo de ferramentas nativas: cria uma ferramenta da organização, configura o endpoint e depois a vincula aos agentes que devem usá-la.

O tipo atual é org_http_tool. O runtime também mantém compatibilidade com registros legados http_api, mas essa distinção interna não muda o fluxo de configuração.

Onde criar e vincular

No menu lateral, abra Ferramentas → Ativas. Na seção Ferramentas Customizadas, selecione Nova Ferramenta e depois Ferramenta HTTP / API. Criar ou editar a configuração-base requer Editar ferramentas (tools.write); excluir requer Excluir ferramentas (tools.delete).

Depois de salvar, abra o agente e use Ferramentas → Adicionar Ferramenta → Outras Ferramentas para vinculá-la. Uma configuração criada na página Ferramentas pertence à organização e pode ser reutilizada por vários agentes. Alterar a configuração-base passa a afetar todos os agentes vinculados; a exclusão fica bloqueada enquanto houver vínculo.

O editor do agente permite ajustar valores dos parâmetros apenas para aquele agente: o valor pode ser fornecido pelo modelo, fixado manualmente ou omitido quando o parâmetro é opcional. Endpoint, autenticação e schema continuam sendo administrados na página Ferramentas.

Veja o editor campo a campo em Ferramentas HTTP Customizadas.

O que o modelo recebe

O modelo vê somente o contrato necessário para decidir e montar a chamada:

o nome técnico, único dentro da organização;
a descrição da finalidade da ferramenta;
o JSON Schema dos parâmetros que ele pode fornecer.

Use um nome técnico específico, descrições orientadas à tarefa e parâmetros sem ambiguidade. Valores fixados ou omitidos no agente são retirados do schema exposto ao modelo. O token de autenticação nunca entra no prompt nem no resultado da ferramenta.

Como a requisição é montada

O executor aceita GET, POST, PUT, PATCH e DELETE. Ele substitui parâmetros de caminho :chave, acrescenta parâmetros de query e injeta a autenticação e os headers no servidor.

Em GET, valores já presentes na URL têm precedência; depois entram os parâmetros configurados e os argumentos adicionais do modelo.
Nos outros métodos, um template JSON pode usar os argumentos do modelo. Campos cujo placeholder não foi resolvido são removidos quando o template é JSON válido. Sem template, os argumentos adicionais formam o corpo JSON.
Enviar metadados da conversa acrescenta dados como conversa, contato externo, agente e modelo somente a corpos JSON de métodos diferentes de GET. Chaves já escritas no template prevalecem.
Fornecer identidade do lead ao contexto atua no contexto do modelo; não equivale a anexar esses dados automaticamente à requisição.

Para marcar parâmetros como obrigatórios, use o JSON Schema do modo avançado. O construtor visual atual cria parâmetros opcionais e não oferece controle de obrigatoriedade.

Segurança e limites de execução

A URL final é validada antes da chamada. Somente http e https são aceitos, e endereços locais, privados, reservados e de metadados de nuvem são bloqueados. Mesmo assim, trate o endpoint como parte confiável da sua arquitetura: envie apenas dados necessários, limite os privilégios da credencial e faça rotação periódica.

A interface mantém o segredo como campo de escrita e o executor o lê no servidor, sem expô-lo ao modelo. Porém, na implementação auditada, o valor é gravado diretamente na coluna de segredo, apesar do texto da interface afirmar que há criptografia. Até a correção do produto, não considere esse armazenamento um cofre criptografado em repouso.

Cada chamada tem limite efetivo de 30 segundos, mesmo que o formulário aceite um valor maior. O corpo da resposta é limitado a 1 MiB. Respostas JSON válidas são entregues como dados estruturados; as demais chegam como texto. Em erro HTTP, o agente recebe o status e apenas o início do corpo de erro.

Chamadas idênticas não são repetidas no mesmo turno, e até três ferramentas HTTP podem executar em paralelo no mesmo lote.

Teste e publicação

O painel Testar ferramenta envia uma requisição real ao endpoint e mostra status, duração e corpo. Use uma credencial e um ambiente de teste quando a operação puder criar, atualizar ou excluir dados. A ferramenta aparece como ativa depois de salva; um teste bem-sucedido não grava um selo de validação nem é requisito para ativação.

O teste atual não reproduz perfeitamente a execução do agente: parâmetros de query configurados e placeholders ausentes no corpo podem ser montados de forma diferente, e os metadados de conversa são fictícios. Portanto, valide também a versão salva em um agente de teste e confira no sistema de destino quais dados chegaram.

O salvamento da configuração, do segredo e da sincronização dos agentes ocorre em etapas separadas. Se uma delas falhar, releia a ferramenta antes de tentar novamente, confirme endpoint e autenticação e verifique se não foi criada uma duplicata.

Quando usar

Use uma ferramenta HTTP quando o agente precisar acessar um sistema sem integração pronta: uma API própria, um CRM ou ERP interno, um serviço público ou um webhook de automação. Não use uma chamada genérica quando uma ferramenta nativa ou integração existente já oferecer um contrato mais restrito, observável e fácil de manter.