Ação do Agente de IA: Make HTTP requests

Elegibilidade do plano: Disponível nos planos Advanced, Enterprise e em alguns planos Legacy selecionados. O teste está disponível para todos os usuários, mas publicar requer um plano elegível.

A ação Make HTTP requests permite que seu Agente de IA chame APIs externas durante uma conversa. Isso permite que o Agente de IA recupere dados em tempo real ou execute ações em sistemas externos com base na solicitação do contato. Por exemplo, ele pode verificar o status do pedido, obter informações da conta ou criar registros em outro sistema. Neste artigo, você aprenderá como configurar a ação de solicitação HTTP e testá-la com seu Agente de IA.

O Agente de IA:

1. Analisa a mensagem do contato para determinar se ela corresponde à intenção definida nas instruções da sua ação.

2. Coleta as informações necessárias.

3. Envia a solicitação HTTP.

4. Interpreta a resposta da API.

5. Responde naturalmente ao contato.

Adicionar a ação Make HTTP requests

Ative a ação e clique no botão “Add action” para começar a configurar sua solicitação HTTP.

Defina quando a ação deve ser executada

Dê um nome descritivo para a ação no campo Action name .

No campo When and how should this action be performed? descreva:

• Quando o Agente de IA deve usar esta ação

• O que ele recupera ou envia

• Quaisquer condições ou resultados a serem tratados

Exemplo:

Use esta ação para recuperar o status do pedido de um contato quando ele perguntar sobre o pedido. Se a API retornar um erro 404, informe ao contato que o pedido não pôde ser encontrado.

O Agente de IA usa essa descrição para decidir quando acionar a solicitação.

Informações que o Agente de IA pode precisar (opcional)

Defina as entradas necessárias nesta seção antes de chamar sua API.

São variáveis estruturadas que o Agente de IA deve coletar. A solicitação é acionada somente depois que todas as entradas obrigatórias estiverem disponíveis.

Se um valor estiver:

• Já mencionado na conversa → o Agente de IA o usa.

• Faltando → o Agente de IA solicita essa informação ao Contato.

As variáveis criadas aqui podem ser usadas na configuração da API. As variáveis de contato (como $contact.email) estão disponíveis automaticamente e não precisam ser adicionadas.

Configurações do campo

Configuração da API

Defina como o Agente de IA deve chamar sua API.

Você pode configurar:

• Método

• URL

• Parâmetros de consulta

• Cabeçalhos

• Corpo JSON (para POST, PUT, PATCH)

Referenciando variáveis

Você pode inserir variáveis na URL, parâmetros, cabeçalhos ou corpo usando $.

Existem dois tipos:

• Variáveis de contato — campos de contato existentes

  • $contact.email

• Variáveis do Agente de IA — campos definidos em Informações que o Agente de IA pode precisar

  • $agent.order_id

As variáveis são substituídas por valores reais quando a solicitação é executada. Se uma variável obrigatória do Agente de IA estiver faltando, o Agente de IA a solicitará antes de acionar a chamada à API.

Como o Agente de IA lida com as respostas da API

Exemplo de corpo:

{
  "order_id": "$agent.order_id",
  "email": "$contact.email"
}

O Agente de IA interpreta automaticamente a resposta JSON da API e gera uma resposta natural.

Exemplo de resposta da API:

{
  "status": "shipped",
  "eta": "2025-12-12"
}

Resposta do Agente de IA: “Boas notícias! Seu pedido foi enviado e está previsto para chegar em 12 de dezembro de 2025.”

Envio de imagens ou arquivos da resposta da API

Se a resposta da API incluir uma URL válida de imagem ou arquivo (por exemplo, uma planta, uma fatura ou uma foto do produto), o Agente de IA pode enviá-la como um anexo renderizado — o mesmo mecanismo usado para as URLs de Knowledge Source e Instruction. Veja Enviar arquivos e imagens como anexos.

Isso requer uma instrução explícita que o autorize, por exemplo:

Envie imagem/arquivo como anexo sempre que houver uma URL válida de imagem/arquivo na resposta da API.

Sem essa instrução, o Agente de IA usará a URL apenas para compor sua resposta de texto — não a enviará como anexo.

Testando

Você pode testar sua ação de solicitação HTTP no painel Test AI Agent antes de publicar.

Como testar

1. Inicie uma conversa de teste que corresponda às condições da sua ação.

   

2. Quando a intenção for detectada e as entradas necessárias estiverem disponíveis, o Agente de IA executa a solicitação HTTP.

3. Um evento de execução aparece no painel de teste:

   

   1. {AI Agent name} executou {Action name}

   2. Respostas 2xx são exibidas como sucesso

   3. Todos os outros códigos de status são exibidos como falha

4. Clique no evento para ver:

   1. Response aba (padrão) — corpo completo da resposta da API

   2. Request aba — payload completo da requisição cURL

   3. Opção de copiar para depuração

5. Após receber a resposta da API, o Agente de IA gera uma resposta com base nos dados retornados.

Notas importantes

• Eventos de execução aparecem apenas no painel Test AI Agent. Eles não aparecem na Caixa de entrada nem na Atividade do contato.

• Se as entradas obrigatórias estiverem faltando, o Agente de IA as pedirá antes de acionar a solicitação.

Melhores práticas

• Seja preciso na descrição da sua ação. Instruções vagas levam a acionamentos vagos.

• Defina claramente as entradas obrigatórias. Se o Agente de IA precisar pedir algo, deixe isso óbvio.

• Trate os casos de erro nas suas instruções.

• Teste sempre antes de publicar.

• Evite duplicar lógica já tratada por Workflows, a menos que seja intencional.

Limitações

• Máximo de 10 ações de solicitação HTTP por Agente de IA.

• Máximo por ação:

  • 20 campos de entrada de dados

  • 50 parâmetros

  • 50 cabeçalhos

• O Agente de IA determina quando chamar a API com base na sua descrição escrita. Instruções mal escritas podem causar acionamentos inesperados.

• O tratamento da resposta da API é automático. Você não pode mapear manualmente os campos de resposta — o Agente de IA interpreta o JSON de forma contextual.

• Eventos de execução de solicitações HTTP aparecem apenas no painel Test AI Agent e não na Atividade do contato.

• Agentes de IA por voz podem acionar a ação Make HTTP requests. No entanto, a resposta retornada da API não é passada de volta ao Agente de IA por voz para gerar a resposta, o que significa que conversas por voz não podem responder dinamicamente com base no resultado da API.

• Se o seu Agente de IA atualizar um campo de contato e também usar esse campo nesta ação no mesmo turno, a solicitação envia o valor antigo (ou vazio, se nunca definido) todas as vezes. Isso acontece independentemente de qual ação for executada primeiro. Se estiver interessado, vote na solicitação de recurso.