Ferramenta API Externa
A ferramenta External API deixa o agente consultar (ou acionar) um sistema seu durante a conversa: a situação de um pedido, o saldo de um contrato, a abertura de um chamado.
Requisição
Seção intitulada “Requisição”| Campo | O que informar |
|---|---|
| Método HTTP | GET, POST, PUT, PATCH ou DELETE |
| URL | O endereço do endpoint. Pode conter placeholders |
| Timeout da requisição | 30 segundos (recomendado), 60 ou 120 |
| Credencial | Uma credencial global delegada a esta solução, ou Sem credencial |
A lista de credenciais mostra apenas as que foram delegadas para esta solução — veja Credenciais.
Headers e body
Seção intitulada “Headers e body”+ Adicionar Header inclui os cabeçalhos necessários (por exemplo, Content-Type). O campo
Body monta o corpo da requisição nos métodos que o aceitam.
Tanto a URL quanto os headers e o body aceitam placeholders: valores que o agente preenche a partir da conversa. É assim que o número do pedido informado pela pessoa chega ao seu endpoint.
Tratamento da resposta
Seção intitulada “Tratamento da resposta”| Campo | O que faz |
|---|---|
| Aplicar proteção de truncamento de respostas longas | Sim (recomendado) corta respostas muito grandes antes de entregá-las ao modelo |
| Truncar respostas maiores que (caracteres) | O limite aplicado |
Deixe a proteção ligada. Uma resposta enorme de API consome o contexto do agente, encarece o turno e costuma piorar a resposta. Se a informação útil está sendo cortada, o caminho é fazer o endpoint devolver menos — e não aumentar o limite indefinidamente.
Resumo da configuração
Seção intitulada “Resumo da configuração”O bloco no rodapé do formulário mostra, em uma linha, o que será gravado: método, URL, credencial, quantidade de headers e se há body. Confira antes de salvar.
Como validar
Seção intitulada “Como validar”- Salve a ferramenta e confirme que ela aparece Habilitada na lista.
- Abra o chat e faça a pergunta que deveria acioná-la.
- Expanda o bloco Atividade acima da resposta para ver se a chamada aconteceu.
| Sintoma | Causa provável |
|---|---|
| O agente nunca chama a ferramenta | Descrição vaga ou ferramenta desabilitada |
| A chamada falha com erro de autorização | Credencial errada, expirada ou não delegada à solução |
| O agente inventa o valor de um parâmetro | Falta instrução dizendo de onde tirar o dado; reforce nas instruções do agente |
| A resposta chega cortada | Limite de truncamento; reduza o retorno do endpoint |