Acción del Agente IA: Realizar solicitudes HTTP

Elegibilidad del plan: Disponible en los planes Advanced, Enterprise y algunos Legacy. Las pruebas están disponibles para todos los usuarios, pero publicar requiere un plan elegible.

La acción Realizar solicitudes HTTP permite que tu Agente IA llame a APIs externas durante una conversación. Esto permite a tu Agente IA recuperar datos en tiempo real o activar acciones en sistemas externos según la solicitud del Contacto. Por ejemplo, puede verificar el estado de un pedido, recuperar información de una cuenta o crear registros en otro sistema. En este artículo, aprenderás a configurar la acción de solicitud HTTP y a probarla con tu Agente IA.

El Agente IA:

1. Analiza el mensaje del Contacto para determinar si coincide con la intención definida en las instrucciones de tu acción.

2. Recopila la información requerida.

3. Envía la solicitud HTTP.

4. Interpreta la respuesta de la API.

5. Responde de forma natural al Contacto.

Agrega una acción de solicitud HTTP

Activa la acción y haz clic en el botón “Agregar acción” para comenzar a configurar tu solicitud HTTP.

Define cuándo debe ejecutarse la acción

Asigna un nombre descriptivo a la acción en el campo Nombre de la acción.

En el ¿Cuándo y cómo debe realizarse esta acción? campo, describe:

• Cuándo debe usar tu Agente IA esta acción

• Qué recupera o envía

• Cualquier condición o resultado a manejar

Ejemplo:

Usa esta acción para obtener el estado del pedido de un Contacto cuando pregunte por su pedido. Si la API devuelve un error 404, informa al Contacto que no se encontró el pedido.

El Agente IA usa esta descripción para decidir cuándo activar la solicitud.

Información que puede necesitar el Agente IA (opcional)

Define las entradas requeridas en esta sección antes de llamar a tu API.

Son variables estructuradas que el Agente IA debe recopilar. La solicitud se activa solo después de que todas las entradas requeridas estén disponibles.

Si un valor es:

• Ya mencionado en la conversación → el Agente IA lo usa.

• Falta → el Agente IA se lo pide al Contacto.

Las variables creadas aquí pueden usarse en la configuración de la API. Las variables de Contacto (como $contact.email) están disponibles automáticamente y no necesitan añadirse.

Configuración del campo

Configuración de la API

Define cómo debe llamar tu Agente IA a tu API.

Puedes configurar:

• Método

• URL

• Parámetros de consulta

• Encabezados

• Cuerpo JSON (para POST, PUT, PATCH)

Referenciando variables

Puedes insertar variables en la URL, parámetros, encabezados o cuerpo usando $.

Hay dos tipos:

• Variables de Contacto — campos de Contacto existentes

  • $contact.email

• Variables del Agente IA — campos definidos en Información que pueda necesitar el Agente IA

  • $agent.order_id

Las variables se reemplazan por valores reales cuando se ejecuta la solicitud. Si falta una variable requerida del Agente IA, este la solicitará antes de activar la llamada a la API.

Cómo el Agente IA maneja las respuestas de la API

Cuerpo de ejemplo:

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

El Agente IA interpreta automáticamente la respuesta JSON de la API y genera una respuesta natural.

Ejemplo de respuesta de la API:

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

Respuesta del Agente IA: “¡Buenas noticias! Tu pedido ha sido enviado y se espera que llegue el 12 de diciembre de 2025.”

Pruebas

Puedes probar tu acción de solicitud HTTP en el panel Probar Agente IA antes de publicar.

Cómo probar

1. Inicia una conversación de prueba que coincida con las condiciones de tu acción.

   

2. Cuando se detecta la intención y las entradas requeridas están disponibles, el Agente IA ejecuta la solicitud HTTP.

3. Un evento de ejecución aparece en el panel de prueba:

   

   1. {AI Agent name} ejecutó {Action name}

   2. Las respuestas 2xx se muestran como éxito

   3. Todos los demás códigos de estado se muestran como fallo

4. Haz clic en el evento para ver:

   1. Respuesta pestaña (predeterminada) — cuerpo completo de la respuesta de la API

   2. Solicitud pestaña — carga útil completa de la solicitud cURL

   3. Opción de copiar para depuración

5. Después de recibir la respuesta de la API, el Agente IA genera una respuesta basada en los datos devueltos.

Notas importantes

• Los eventos de ejecución aparecen solo en el panel Probar Agente IA. No aparecen en la Bandeja de entrada ni en la Actividad del Contacto.

• Si faltan entradas requeridas, el Agente IA las solicitará antes de activar la solicitud.

Mejores prácticas

• Sé preciso en la descripción de tu acción. Las instrucciones vagas conducen a disparadores imprecisos.

• Define claramente las entradas requeridas. Si el Agente IA debe pedir algo, haz que sea evidente.

• Gestiona los casos de error en tus instrucciones.

• Siempre prueba antes de publicar.

• Evita duplicar la lógica ya gestionada por los Flujos de trabajo, a menos que esté diseñado intencionalmente.

Limitaciones

• Máximo 10 acciones de solicitud HTTP por Agente IA.

• Máximo por acción:

  • 20 campos de entrada de datos

  • 50 parámetros

  • 50 encabezados

• El Agente IA determina cuándo llamar a la API según tu descripción escrita. Instrucciones mal redactadas pueden causar activaciones inesperadas.

• El manejo de respuestas de la API es automático. No puedes mapear manualmente los campos de respuesta — el Agente IA interpreta el JSON de forma contextual.

• Los eventos de ejecución de solicitudes HTTP aparecen solo en el panel Probar Agente IA y no en la Actividad del Contacto.

• Los Agentes IA de voz pueden activar la acción Realizar solicitudes HTTP. Sin embargo, la respuesta de la API devuelta no se pasa de vuelta al Agente IA de voz para generar la respuesta, lo que significa que las conversaciones de voz no pueden responder dinámicamente según el resultado de la API.