Como conectar um agente de IA à sua própria API

Crie uma ação personalizada para que um agente do Sell Whisper AI possa chamar o seu endpoint HTTP durante uma conversa, com entradas, autenticação e uma execução de teste. A partir do Starter.

Passos

Siga esta ordem

  1. Crie uma ação personalizada

    Abra o agente, vá em Ações (Actions), depois em Ações personalizadas (Custom actions), e crie uma ação do tipo Chamada de API (API Call). As ações personalizadas estão disponíveis a partir do Starter.

    Lista de ações personalizadas de um agente
  2. Descreva quando usá-la

    Dê à ação um nome e uma descrição e preencha Quando usar (When to Use) em linguagem simples: esse texto diz à IA quando chamar o seu endpoint. Em Entradas do usuário (User Inputs), adicione cada valor que o agente deve coletar, com o tipo dele e a indicação de ser obrigatório ou não.

    Formulário de ação personalizada para uma chamada de API, com quando usá-la e o endpoint
  3. Aponte-a para o seu endpoint

    Defina o método, a URL do endpoint, os cabeçalhos, os parâmetros de consulta e um corpo de requisição em JSON. Escolha o tipo de autenticação: chave de API, bearer token, autenticação básica ou um cabeçalho personalizado.

  4. Teste e ative

    Salve e depois clique em Testar com dados reais (Test with Live Data) para executar a chamada. Exija a confirmação do usuário para tudo o que altera dados, ative a ação e experimente-a no Playground.

Quatro tipos de ação personalizada

TipoO que faz
Chamada de API (API Call)Chama o seu endpoint HTTP a partir dos servidores do Sell Whisper AI e entrega a resposta ao agente
Link de botão (Button Link)Mostra um botão que abre uma URL
Formulário (Form)Mostra um formulário e envia a um webhook o que o seu cliente preenche
Cliente (Client)Executa um handler que você registra na sua própria página, no navegador do visitante

Este guia usa a Chamada de API (API Call). Ela serve para consultas, como o status de um pedido, o saldo de uma conta ou uma reserva, e para alterações, como cancelar uma assinatura.

Escreva a descrição para a IA

O agente decide quando chamar uma ação com base na descrição dela e no texto de Quando usar (When to Use); então escreva-os como se estivesse orientando um novo colega: o que a ação retorna e as situações que pedem o uso dela. Dê um nome claro a cada entrada e diga como é um valor válido. Descrições vagas são o motivo mais comum para uma ação nunca ser chamada ou ser chamada na hora errada.

Mantenha a segurança

  • Autenticação. Armazene a chave de API, o bearer token ou as credenciais básicas na ação; eles nunca são mostrados ao seu cliente.
  • Confirmação. Ative a confirmação do usuário para tudo o que altera dados, para que o seu cliente aprove a chamada antes.
  • Limites e novas tentativas. Defina um tempo limite e um número de novas tentativas para um endpoint lento, e limites de taxa em Avançado (Advanced).
  • Quem está pedindo. Para chamadas específicas de uma conta, verifique os usuários logados para que a requisição leve uma identidade assinada pelo seu servidor.

Mostre o resultado

Ative a visualização de resultado para mostrar a resposta como um card, um formulário ou uma tabela no widget. Os apps de mensagens recebem o mesmo conteúdo em texto.

Relacionados

Perguntas frequentes

Dúvidas comuns

A resposta pode ser exibida como um card ou uma tabela?
Sim. Ative a visualização de resultado e mapeie a resposta para um card, um formulário ou uma tabela. Os canais que não conseguem exibi-los, como o WhatsApp, recebem o mesmo conteúdo em texto.
Uma ação pode ser executada na minha página em vez de em um servidor?
Sim. O tipo Cliente (Client) passa a chamada a um handler que você registra na sua página por meio do SDK do widget. Ele é oferecido somente no widget do site.
Onde posso ver o que foi chamado?
Cada ação personalizada mantém registros de execução com o status, as entradas, as saídas e a duração de cada chamada.

Documentação relacionada

Comece agora

Coloque os passos em prática

Comece grátis, sem cartão de crédito.