La integración de API personalizada te permite conectar módulos de SleekFlow AI, como AgentFlow, con sistemas externos mediante los detalles de la API que proporciones.
Con una integración de API personalizada, tu agente de IA puede obtener datos externos, activar acciones o actualizar registros durante las conversaciones con clientes. Esto permite que el agente gestione flujos de trabajo que requieren datos empresariales en tiempo real, en lugar de depender únicamente de respuestas estáticas de la base de conocimientos.
Por ejemplo, el agente puede:
- Crear enlaces de pago mediante tu sistema interno.
- Obtener los datos de un cliente o de su membresía desde un CRM.
- Buscar productos o generar enlaces de reserva.
- Activar flujos de trabajo del backend según las solicitudes de los clientes.
Puedes configurar una integración de API personalizada describiendo el caso de uso de la API, subiendo documentación de API compatible, pegando documentación relevante en el chat de configuración o pegando un comando cURL sin procesar en ese chat. El creador de API personalizadas utiliza la información que proporciones para generar un esquema editable.
Antes de comenzar
Antes de configurar una integración de API personalizada, asegúrate de contar con lo siguiente:
- Acceso a la pestaña "Integraciones" de SleekFlow AI.
- Una idea clara de lo que quieres que el agente de IA haga con la API.
- La documentación de la API, los detalles del endpoint o los detalles de la solicitud del endpoint que quieres conectar.
- La clave de API, el token de portador o los detalles del encabezado de autenticación, si la API requiere autorización.
Si la pestaña "Integraciones" no está disponible o está bloqueada, comunícate con tu gerente de Éxito del Cliente para habilitar el acceso o actualizar tu plan.
También debes preparar la información de la API necesaria para la configuración. Esto puede incluir:
- Un archivo de documentación de API compatible.
- El texto relevante de la documentación de la API.
- Un comando cURL sin procesar.
- Una descripción breve del caso de uso de la API.
Los formatos de carga compatibles incluyen:
.JSON.YAML.YML.PDF
Cada archivo subido puede tener un tamaño máximo de 1 MB.
Si Copilot sugiere un endpoint o genera un esquema, revisa siempre los detalles antes de guardar la integración. Comprueba el endpoint, la URL base, los encabezados de autenticación, las entradas, las salidas y las descripciones de los campos para asegurarte de que coincidan con los requisitos de tu API.
Cómo funciona la integración de API personalizada
La integración de API personalizada define el esquema de API que AgentFlow puede utilizar.
Esto incluye:
- Entradas: datos que se envían a la API.
- Salidas: datos que devuelve la API.
- Descripciones: información que ayuda al agente a comprender qué significa cada campo.
- Fuente de datos: de dónde proviene el valor de cada entrada.
- URL base: el host de la API que se utiliza junto con las rutas de los endpoints.
La configuración de la integración de API personalizada y la configuración del Playbook de AgentFlow tienen propósitos diferentes.
| Área | Integración de API personalizada | Playbook de AgentFlow |
|---|---|---|
| Qué hace | Define la estructura de la API que AgentFlow puede utilizar. | Define cómo utiliza el agente la API durante una conversación. |
| Enfoque | Configuración técnica, como las entradas, las salidas y el esquema. | Lógica de la conversación, como cuándo llamar a la API, qué información recopilar y cómo responder. |
| Ejemplo |
Define un campo booking_date y su formato.
|
Indica al agente que solicite la fecha de la reserva antes de llamar a la API. |
| Dónde se configura | SleekFlow AI → pestaña "Integraciones". | SleekFlow AI → AgentFlow → agente → "Configuración" → "Acciones y Playbooks". |
| Resultado | Hace que la API esté disponible a nivel de empresa. | Controla qué agente puede utilizarla y cómo se usa en las conversaciones. |
La integración de API personalizada controla qué puede hacer la API y qué campos están disponibles. Para controlar cuándo debe el agente recopilar información, llamar a la API o utilizar su respuesta, actualiza el Playbook de AgentFlow.
Guardar una integración no la habilita automáticamente para todos los agentes. Debes habilitar la integración y sus endpoints para cada agente desde "Configuración" → "Acciones" y, luego, hacer referencia a la API en las instrucciones del Playbook.
Configura una integración de API personalizada
Usa el creador de API personalizadas para crear una integración a partir de la información de la API que proporciones. Puedes describir el caso de uso, subir documentación de API compatible, pegar la documentación en el chat de configuración o pegar un comando cURL sin procesar.
SleekFlow utiliza esta información para generar un esquema editable. Debes revisar siempre el esquema generado antes de guardar la integración.
Paso 1: Inicia una nueva integración de API personalizada
- Haz clic en el
ícono de la barra de navegación izquierda para ir a la página de SleekFlow AI. - En la página de SleekFlow AI, haz clic en "Integraciones", en la barra de navegación superior.
- Se te redirigirá a la pestaña "Integraciones".
- Haz clic en "Agregar integración", en la esquina superior derecha.
Esto abre el flujo de configuración para conectar una API externa. Usa la ventana de configuración conversacional de la izquierda para definir la integración.
En lugar de completar manualmente un formulario, puedes orientar a la IA proporcionando los detalles de la API, describiendo el caso de uso o pegando una solicitud de API existente.
El esquema generado por Copilot aparecerá en el lienzo del esquema, a la derecha. Debes revisar y perfeccionar siempre el esquema generado antes de guardar la integración.
Por ejemplo, puedes describir casos de uso como los siguientes:
- Crear un enlace de pago para un cliente.
- Obtener el estado de un pedido desde tu CRM.
- Buscar horarios disponibles para reservas.
- Actualizar el perfil de un cliente en un sistema externo.
La descripción ayuda a Copilot a comprender la acción de la API que quieres configurar.
Para los casos de uso de API públicas, Copilot puede sugerirte un endpoint relevante para que lo confirmes antes de generar el esquema. Para API internas o privadas, proporciona la documentación, los detalles del endpoint o un comando cURL sin procesar, de modo que Copilot pueda generar el esquema según la configuración de tu propia API.
Paso 2: Agrega la información de la API
Puedes proporcionar la información de la API de distintas maneras, según los recursos que ya tengas.
Opción 1: Describe el caso de uso de la API
Usa esta opción cuando sepas qué quieres que haga el agente y puedas proporcionar suficiente información sobre la API para que Copilot genere el esquema completo.
La API puede ser pública o privada. Debes proporcionar su documentación, los detalles del endpoint u otra información técnica necesaria para configurar la solicitud. La información que debes proporcionar depende de si Copilot puede acceder a la documentación de la API.
Para una API pública
Comparte un enlace a la documentación relevante de la API y describe la acción que quieres configurar. Siempre que sea posible, incluye un enlace directo al endpoint o a la sección específica de la documentación, en lugar de la página principal de la documentación de la API.
Por ejemplo:
"Usa este endpoint de la API de Stripe para crear un enlace de pago según el producto seleccionado y el correo electrónico del cliente: [enlace a la documentación de la API]".
Proporcionar un enlace específico a la documentación ayuda a Copilot a identificar el endpoint correcto sin tener que buscar en toda la documentación del proveedor de la API.
Para una API privada
Describe la acción que quieres que realice el agente y proporciona los detalles disponibles del endpoint, los parámetros de la solicitud, los requisitos de autenticación o ejemplos de respuestas.
Por ejemplo:
"Obtén un pedido de nuestro sistema interno de pedidos mediante el ID de pedido del cliente".
Copilot puede hacer preguntas adicionales antes de generar el esquema si necesita más información.
Nota: Evita ingresar únicamente una solicitud general, como "Conecta Stripe". Los proveedores de API de gran tamaño pueden ofrecer cientos de endpoints, y es posible que Copilot no pueda identificar el correcto sin un caso de uso específico o un enlace a la documentación.
Opción 2: Sube la documentación de la API
Usa esta opción cuando tengas la documentación de la API en un formato de archivo compatible.
Los formatos de carga compatibles incluyen:
.JSON.YAML.YML.PDF
Cada archivo subido puede tener un tamaño máximo de 1 MB.
Después de subir el archivo, Copilot revisará la documentación y la utilizará para generar el esquema.
Opción 3: Pega la documentación de la API
Usa esta opción cuando ya tengas la documentación del endpoint de la API que quieres configurar.
Puedes proporcionar la documentación de cualquiera de las siguientes maneras:
- Comparte un enlace a la documentación relevante de la API.
- Pega directamente en el chat de configuración los detalles relevantes del endpoint.
Siempre que sea posible, comparte un enlace que abra el endpoint o la sección específica de la documentación, en lugar de la página principal de la documentación de la API.
La documentación debe incluir detalles como los siguientes:
- URL del endpoint.
- Método de solicitud.
- Encabezados obligatorios.
- Parámetros de consulta.
- Parámetros de ruta.
- Cuerpo de la solicitud.
- Ejemplo de respuesta.
Esta opción resulta útil cuando solo quieres configurar un endpoint específico o cuando la documentación completa de la API contiene información que no es relevante para la acción.
Opción 4: Pega un comando cURL sin procesar
Usa esta opción cuando ya tengas una solicitud de API funcional obtenida de la documentación de la API, las herramientas para desarrolladores del navegador, Postman o la transferencia de un equipo de ingeniería.
Pega el comando cURL sin procesar en el chat de configuración. Copilot puede utilizarlo para identificar los detalles de la solicitud y generar el esquema.
Nota: Ingresar un comando cURL sin procesar es un método de configuración alternativo. Aun así, debes revisar el esquema generado antes de guardar la integración.
Paso 3: Revisa y perfecciona el esquema
After Copilot generates the schema, review the fields in the schema canvas before saving the integration.
The schema defines how AgentFlow understands and uses the API. Clear field descriptions and accurate settings help the agent call the API correctly during customer conversations.
For each endpoint, review the following sections:
Section |
What to review |
Base URL |
Check that the Base URL is correct. The Base URL is the API host used together with the endpoint path. |
Endpoint path |
Check that the endpoint path matches the API action you want the agent to perform. |
Request method |
Check that the request method is correct, such as GET, POST, PUT, or DELETE. |
Inputs |
Check the fields the API needs to receive. Make sure each description clearly explains what value should be provided. |
Data source |
Choose whether each input value should be collected from chat or set as a static value. |
Outputs |
Check the fields returned by the API. Make sure each description clearly explains what the field means. |
Expose to AI |
Turn this on only for output fields that the agent should use when generating a response. Turn it off for fields that are irrelevant to the conversation, not needed by the agent, or contain sensitive information. |
Revisa la URL base
La URL base se muestra en el lienzo del esquema después de la configuración.
Revísala cuidadosamente antes de guardar la integración, en especial si tu API tiene distintos entornos, como pruebas y producción.
La URL base funciona junto con la ruta del endpoint para determinar adónde se envía la solicitud de API.
Advertencia: Si la URL base es incorrecta, las llamadas a la API pueden fallar o enviarse al entorno equivocado.
Revisa las entradas y la fuente de datos
En la sección "Entradas", comprueba los campos que la API necesita recibir.
Para cada entrada, revisa lo siguiente:
- Nombre del campo.
- Descripción.
- Fuente de datos.
- Valor estático, si se utiliza.
La descripción del campo debe explicar claramente qué valor se necesita. Esto ayuda al agente a asignar la información del cliente al campo correcto de la API.
Revisa las salidas y la opción "Exponer a la IA"
En la sección "Salidas", comprueba los campos que devuelve la API.
Activa "Exponer a la IA" únicamente para los campos que el agente deba utilizar al generar respuestas para los clientes.
Desactiva esta opción para los campos que:
No sean útiles para la conversación.
Solo sean necesarios para el procesamiento del backend.
Contengan información sensible.
Puedan confundir al agente si se exponen.
Expón únicamente los campos de salida necesarios para la respuesta del agente. Esto ayuda a mantener las respuestas enfocadas y reduce la información innecesaria.
Nota: La configuración de la integración define los campos y las descripciones de la API. Para controlar cuándo debe el agente recopilar información, llamar a la API o utilizar la respuesta de la API, actualiza el Playbook de AgentFlow.
Paso 4: Define cómo se proporcionan los valores de entrada
En la sección "Entradas", usa la columna "Fuente de datos" para seleccionar cómo debe proporcionarse el valor de cada entrada. Puedes elegir "Recopilar desde el chat" o "Valor estático".
Recopilar desde el chat
Selecciona "Recopilar desde el chat" cuando el valor deba provenir del cliente durante la conversación.
Usa esta opción para información que puede variar según el cliente o la solicitud, como el correo electrónico, la fecha de la reserva, la preferencia de producto o el número de pedido.
Cuando uses "Recopilar desde el chat":
- Asegúrate de que la descripción del campo explique claramente qué información se necesita.
- Actualiza el Playbook de AgentFlow para que el agente sepa cuándo solicitar esta información al cliente.
- Prueba el agente para confirmar que el valor recopilado se asigne al campo correcto de la API.
Valor estático
Selecciona "Valor estático" cuando se deba enviar el mismo valor cada vez que se llame a la API.
Usa esta opción para valores fijos, como un parámetro predeterminado del sistema, un código de región, un indicador interno o un identificador de canal.
Cuando uses "Valor estático":
- Ingresa el valor fijo en el campo "Valor".
- Comprueba que el valor coincida con el formato requerido por tu API.
- Guarda los cambios antes de probar la integración en AgentFlow.
Nota: La fuente de datos controla de dónde proviene el valor de entrada. La descripción del campo explica qué significa el valor. El Playbook de AgentFlow controla cuándo debe el agente recopilar o utilizar ese valor.
Paso 5: Guarda y publica la integración
Antes de guardar, revisa los detalles de la integración para asegurarte de que sean correctos.
Comprueba que:
- El esquema del endpoint sea correcto.
- Cada entrada tenga la descripción y la fuente de datos correctas.
- Los valores estáticos se hayan ingresado correctamente, si se utilizan.
- Las descripciones de las salidas sean claras.
- Solo se expongan a la IA los campos de salida adecuados.
Cuando estés listo, haz clic en "Guardar".
Después de guardar, la integración de API personalizada estará disponible para los módulos compatibles de SleekFlow AI, como AgentFlow.
Nota:
- Puedes volver a editar y guardar la integración después de crearla. Después de hacer cambios, revisa y prueba los Playbooks de AgentFlow que utilicen esta integración.
- Después de guardar, la URL base seguirá visible en el lienzo del esquema y en la página de detalles de la integración para futuras consultas.
- Si la URL base es incorrecta, las llamadas a la API pueden fallar o enviarse al entorno equivocado.
Administra tu integración de API personalizada
Puedes administrar la integración de API personalizada después de agregarla a SleekFlow.
Sigue estos pasos para administrar tus integraciones de API personalizadas:
- Haz clic en el
ícono de la barra de navegación izquierda para ir a la página de SleekFlow AI. - En la página de SleekFlow AI, haz clic en "Integraciones", en la barra de navegación superior.
- Se te redirigirá a la página "Integración de API personalizada", donde encontrarás la API personalizada que agregaste al espacio de trabajo de SleekFlow.
Puedes abrir una integración de API personalizada para revisar su configuración, incluidos el nombre de la integración, la configuración de autenticación, la URL base, el esquema del endpoint, las entradas, las salidas y los agentes asignados.
Edita una API personalizada
Importante
Los cambios en las entradas, las salidas, las descripciones de los campos, las rutas de los endpoints o los nombres de los comandos del Playbook pueden afectar el comportamiento del agente. Después de editar una integración, revisa y prueba la configuración de AgentFlow para asegurarte de que todo funcione según lo esperado.
Después de crear una integración de API personalizada, puedes actualizar su configuración en cualquier momento. Esto te permite perfeccionar las entradas, ajustar las salidas o actualizar la autenticación a medida que evolucionen tu API o el caso de uso.
Para editar una API personalizada:
- En el panel de integraciones de API personalizadas, ubica la API personalizada que quieras editar.
- Haz clic en la API personalizada.
- Se te redirigirá a la página de detalles de la API personalizada.
Actualiza el nombre de la integración
Puedes cambiar el nombre de la integración de API personalizada para que refleje mejor su propósito. Usa un nombre claro y descriptivo para que sea fácil identificarla al seleccionarla en AgentFlow.
Nota: Actualizar el nombre de la integración no afecta la configuración de la API ni la forma en que se utiliza en las configuraciones existentes de AgentFlow.
Revisa la URL base
La URL base está visible en la página de detalles de la API personalizada.
Usa este campo para comprobar qué host o entorno de la API utiliza la integración. Esto resulta especialmente útil si tu API tiene distintos entornos, como pruebas y producción.
Ya no es necesario pedirle al agente creador que obtenga la URL base después de crear la integración.
Advertencia: Si la URL base es incorrecta, las llamadas a la API pueden fallar o enviarse al entorno equivocado.
Actualiza la configuración de autenticación
En la sección "Autenticación", puedes configurar o actualizar las credenciales de la API.
- Haz clic en "Actualizar clave" para modificar la clave de API o el token de portador.
- Asegúrate de que el método de autenticación coincida con los requisitos de tu API.
Los cambios que realices aquí afectarán la autorización de todas las solicitudes de API.
Edita el esquema del endpoint
En la sección "Esquema del endpoint", puedes revisar los endpoints incluidos en la integración de API personalizada.
Cada endpoint muestra el método de solicitud, la ruta del endpoint y una descripción breve de lo que hace. Puedes expandir un endpoint para revisar su configuración. Revisa estos detalles junto con la URL base para asegurarte de que la solicitud se envíe al endpoint correcto de la API.
Haz clic en "Agregar/Editar endpoints" para actualizar el esquema de los endpoints, agregar nuevos endpoints o eliminarlos si cambia la configuración de la API.
Actualiza el nombre del comando del Playbook
Cada endpoint tiene un nombre de comando del Playbook.
Este es el nombre del comando utilizado al configurar la integración en AgentFlow. Usa un nombre claro y reconocible que describa la acción, como /get_available_slots o /create_booking.
Si cambias el nombre de un comando que ya utiliza un agente, revisa la configuración relacionada de AgentFlow para asegurarte de que el agente siga haciendo referencia al comando correcto.
Edita las entradas
En la sección "Entradas", revisa los campos que la API necesita recibir.
Para cada entrada, puedes:
- Actualizar la descripción.
- Seleccionar la "Fuente de datos".
- Ingresar un valor si la fuente de datos está configurada como "Valor estático".
Consejos:
- Usa "Recopilar desde el chat" cuando el agente deba obtener el valor del cliente durante la conversación.
- Usa "Valor estático" cuando se deba enviar el mismo valor cada vez que se llame al endpoint.
Las descripciones de las entradas deben explicar claramente qué valor se necesita. Esto ayuda al agente a asignar la información recopilada al campo correcto de la API.
Edita las salidas
En la sección "Salidas", revisa los campos que devuelve la API.
Para cada salida, puedes:
- Actualizar la descripción.
- Activar o desactivar "Exponer a la IA".
Activa "Exponer a la IA" para los campos que el agente deba poder utilizar en las respuestas a los clientes. Desactiva esta opción para los campos que no sean útiles para la conversación o que no deban mostrarse al agente.
Consejo: Expón únicamente los campos de salida necesarios para la respuesta del agente. Esto ayuda a mantener las respuestas enfocadas y reduce la información innecesaria.
Revisa los agentes asignados
En la parte inferior de la página, revisa "Agentes asignados" para ver qué agentes utilizan actualmente esta integración.
Si aparece un agente en la lista, puedes administrar cómo utiliza la integración desde la configuración del agente.
Guarda los cambios
Después de realizar las actualizaciones, haz clic en "Guardar cambios", en la parte inferior de la página.
Las actualizaciones se aplicarán a la integración de API personalizada. Después de guardar, revisa y prueba las configuraciones de AgentFlow que utilicen esta integración, especialmente si cambiaste los nombres de los comandos, los detalles de los endpoints, las entradas, las salidas o los campos expuestos.
Elimina una API personalizada
Para eliminar una API personalizada:
- En el panel de integraciones de API personalizadas, ubica la API personalizada que quieras eliminar.
- Haz clic en el
ícono que aparece junto a la API personalizada. - Selecciona "Eliminar".
- Aparecerá un mensaje de advertencia.
- Haz clic en "Eliminar" para confirmar la acción.