Las herramientas permiten conectar tus agentes de IA con APIs y sistemas externos, lo que les permite consultar información o ejecutar acciones durante una conversación con el cliente.

Por ejemplo, puedes configurar una herramienta para consultar el estado de un pedido, verificar información de registro o buscar datos en un sistema interno.

1. Para acceder, ve a Zenvia Customer Cloud > Agentes de IA.

2. Haz clic en Herramientas.

3. Selecciona Crear herramienta +.

Configuración de la herramienta

En esta etapa, deberás ingresar los datos que identifican la herramienta y explican al agente cómo utilizarla.

1. Ref: Ingresa una referencia única para identificar la herramienta. Este identificador es utilizado por el modelo de IA para llamar a la herramienta durante la conversación.

Utiliza un nombre corto, sin espacios y, preferentemente, uno de los siguientes formatos:

• kebab-case: consultar-pedido

• snake_case: consultar_pedido

• camelCase: consultarPedido

• PascalCase: ConsultarPedido

Ejemplo: consultar-pedido

⚠️ Atención:  La referencia debe ser única dentro de la organización y no puede coincidir con la referencia de una herramienta nativa de la plataforma.

2. Nombre

Ingresa un nombre para identificar la herramienta en la plataforma. Elige nombres claros y objetivos que indiquen la finalidad de la integración.

Ejemplo: Consultar pedido.

3. Descripción

Explica qué hace la herramienta y en qué situaciones el agente deberá utilizarla. Este campo es importante porque orienta al modelo de IA sobre cuándo debe llamar a la herramienta.

Ejemplo: "Consulta el estado de un pedido utilizando el número proporcionado por el cliente. Utiliza esta herramienta siempre que el cliente quiera conocer el estado de una compra".

💡Tip: Escribe una descripción clara y específica. Evita los textos genéricos, ya que el agente necesita comprender en qué situaciones será necesaria la herramienta.

4. Argumentos

Haz clic en Agregar argumento para incluir los parámetros necesarios. Configura los argumentos de acuerdo con la información que requiere la API que vas a integrar.

Los argumentos son los datos que el agente deberá proporcionar para ejecutar la herramienta. Por ejemplo, para consultar un pedido, el agente necesita recibir el número correspondiente.

Ejemplo: Para una herramienta de consulta de pedidos, puedes utilizar:

• Argumento: orderId.

• Finalidad: Número de identificación del pedido que se consultará.

La descripción del argumento debe indicar claramente qué información necesita obtener el agente del cliente o de otra fuente.

Los argumentos configurados estarán disponibles en la solicitud mediante el espacio de nombres input. Por ejemplo, para utilizar el número de pedido proporcionado por el agente, utiliza: {{input.orderId}}.

Si la herramienta no necesita recibir ningún parámetro, no es necesario agregar argumentos. En ese caso, el modelo podrá llamar a la herramienta sin proporcionar parámetros.

5. Configuración de la solicitud

Define cómo la plataforma enviará una solicitud a la API externa.

Antes de completar los campos, consulta la documentación de la API que deseas integrar para identificar el método, la dirección, los encabezados y los parámetros necesarios.

5.1 Método

Selecciona el método HTTP utilizado por la API. El método determina el tipo de operación que se realizará.

Los métodos disponibles incluyen:

• GET: Se utiliza para consultar o recuperar información.

• POST: Se utiliza para enviar información o crear registros.

• PUT: Se utiliza para actualizar información.

• DELETE: Se utiliza para eliminar registros.

Ejemplo: Para consultar el estado de un pedido, selecciona GET.

5.2 URL

Ingresa la dirección del endpoint de la API que será llamado por la herramienta. El endpoint debe corresponder a la operación que deseas ejecutar.

Ejemplo: https://api.ejemplo.com/pedidos/{{input.orderId}}

En este ejemplo, la URL utiliza la variable {{input.orderId}} para insertar dinámicamente el número de pedido proporcionado por el agente. De esta manera, cada solicitud podrá consultar un pedido diferente.

⚠️ Atención:  Utiliza la URL proporcionada en la documentación de la API del sistema que deseas integrar.

5.3 Encabezados (Headers)

Los encabezados (headers) permiten enviar información adicional en la solicitud, como datos de autenticación y el formato del contenido.

Para agregar un encabezado:

1. En la sección Encabezados, haz clic en Agregar encabezado.

2. Ingresa el nombre del encabezado.

3. Ingresa el valor correspondiente.

Ejemplo de autenticación:

En este ejemplo, el token se utiliza para autenticar la comunicación con la API externa.

Los encabezados necesarios varían según la documentación y los requisitos de autenticación de cada sistema. La información confidencial, como los tokens de autenticación, se oculta después de guardarse.

5.4 Cuerpo (Body)

Este campo permite configurar la información que se enviará en el cuerpo de la solicitud. Se utiliza principalmente con métodos como POST y PUT, cuando la API requiere el envío de datos.

Ejemplo:

{
  "orderId": "{{input.orderId}}"
}

En este ejemplo, el número de pedido se envía en el cuerpo de la solicitud.

⚠️ Atención:  Las solicitudes GET no utilizan cuerpo. Para configurar un cuerpo, selecciona un método HTTP compatible y consulta la documentación de la API integrada.

5.5 Tiempo de espera (ms)

Determina cuánto tiempo esperará la plataforma la respuesta de la API antes de finalizar la solicitud. Este campo se configura en milisegundos (ms).

Las opciones disponibles son:

• Valor predeterminado: 15.000 ms (15 segundos).

• Valor máximo: 60.000 ms (60 segundos).

Ejemplo: Si configuras el tiempo de espera en 10000, la plataforma esperará hasta 10 segundos por la respuesta de la API.

Ten en cuenta el tiempo promedio de respuesta del sistema integrado al definir este valor.

5.6 Marcadores encontrados en la solicitud

Muestra las variables identificadas en la configuración.

Si no se encuentra ningún marcador, verifica que las variables estén correctamente ingresadas en la URL, los encabezados o el cuerpo de la solicitud.

💡Tip: Si necesitas utilizar información proporcionada por el cliente, configura el argumento correspondiente y utiliza la variable {{input.nombreDelArgumento}} en la solicitud.

Por último, haz clic en Guardar.

Una vez registrada, la herramienta estará disponible en la organización para asociarla a los agentes.

⚠️ Atención:  Registrar una herramienta no significa que esté disponible automáticamente para todos los agentes. Para utilizarla, debes agregarla a la configuración del agente y guardar una nueva versión.