Funciones del asistente de IA

Solicitud Directa al Modelo

ai_request(prompt, text, response_schema=null, think_mode=false, ai_assistant_id=null)

Envía una solicitud a un modelo de IA y devuelve la respuesta generada.

Parámetros

Ejemplos

Usando un Asistente de IA por ID

ai_request(prompt, text, 0, 0, 123)

En este ejemplo, la función carga toda la configuración del Asistente de IA con ID 123, por lo que no es necesario especificar el proveedor, modelo, clave API u otra configuración manualmente.

Pasando la Configuración del Modelo Manualmente

aio_request(
    prompt,
    text,
    0,
    0,
    {
        "provider": "openai",
        "api_key": "#{openai_key}",
        "model": "gpt-5-mini"
    }
)

En este caso, se utiliza la configuración proporcionada en lugar de un Asistente de IA.

Tenga en Cuenta

En las expresiones, las variables se escriben usando solo sus nombres, sin #{}.

La respuesta se devuelve como texto plano, por lo que se puede enviar directamente al cliente o almacenar en una variable.

El método espera pacientemente la respuesta del modelo, por lo que incluso las solicitudes de larga duración, como esquemas grandes o textos extensos, se completarán sin interrupción.

Cuando necesite datos estructurados en lugar de texto libre, como una categoría, una respuesta sí/no o campos extraídos, pase un esquema de respuesta como tercer argumento.

No es necesario crear esquemas desde cero. Use una plantilla ya preparada y renombre los campos según sea necesario.

local result = ai_request('Determine la categoría de la solicitud.', question, {
    "type": "object",
    "properties": {
        "category": {
            "type": "string",
            "enum": ["complaint", "question", "order"]
        }
    },
    "required": ["category"]
})
category = get(result, 'category')

local result = ai_request('¿El cliente ha aceptado realizar la compra?', question, {
    "type": "object",
    "properties": {
        "agree": {
            "type": "boolean"
        }
    },
    "required": ["agree"]
})

agree = get(result, 'agree')

local result = ai_request('Extraiga el nombre y el número de teléfono del mensaje.', question, {
    "type": "object",
    "properties": {
        "name": {
            "type": "string"
        },
        "phone": {
            "type": "string"
        }
    },
    "required": ["name", "phone"]
})

client_name = get(result, 'name')
client_phone = get(result, 'phone')

La respuesta basada en esquema se devuelve como una cadena JSON. Los campos individuales se pueden recuperar usando el método estándar get().

Tenga en Cuenta

En los ejemplos, result se declara usando local. Esto significa que la respuesta sin procesar de la IA no se guardará en el registro; solo se almacenarán allí los campos requeridos.

Modo de Razonamiento

El modo de razonamiento se puede habilitar usando el cuarto argumento. En este modo, el modelo primero piensa en la tarea y luego proporciona una respuesta.

Es útil para solicitudes complejas que implican análisis, cálculos o lógica de varios pasos. La respuesta tardará notablemente más, por lo que el modo de razonamiento está deshabilitado de forma predeterminada.

answer = ai_request(
    'Resuelva el problema del cliente y explique la solución.',
    question,
    '',
    true
)

Cuando no se requiere un esquema de respuesta, pase una cadena vacía '' como tercer argumento, como se muestra en el ejemplo.

Cómo eliminar el historial de chat con el asistente de IA

clear_assistant_chat_history() - esta función elimina el historial de chat del cliente con el asistente. No toma parámetros.

Ejemplo

1. La configuración del bloque del constructor

2. La configuración de la pestaña Asistente de IA

Cómo enviar una pregunta al asistente de IA

aio_context_answer(replica, prompt, ai_assistant_id, use_history, send_answer)

Parámetros:

Más detalles sobre el parámetro send_answer:

La configuración del asistente incluye parámetros que se pueden configurar en caso de que la respuesta del bot tarde mucho tiempo

En una conversación estándar con el asistente (no a través de una función), si la respuesta tarda más del límite especificado (por ejemplo, 20 segundos), se notifica al cliente de la demora. La respuesta del asistente se envía al chat tan pronto como se genera.

Para solicitudes realizadas a través de una función en la calculadora, si el asistente tarda demasiado en responder, se incluye un mensaje de demora en el resultado de la función. Este parámetro permite que la respuesta del asistente se envíe por separado una vez que esté lista.

Cómo enseñar a un bot a analizar su propia experiencia y generar botones

Usemos las funciones clean_assistant_chat_history() y ai_context_answer(replica, prompt) en el siguiente ejemplo. También es necesario acceder al componente de la calculadora dentro del constructor de embudos.

Este ejemplo ilustra cómo los parámetros replica y prompt se pueden usar de manera efectiva en la práctica.

Es necesario crear un bloque en el constructor que contenga un campo vacío con las variables incrustadas #{replica_rec2} y #{ai_answer_rec}, que representan la primera y segunda respuesta del asistente en un solo mensaje a enviar.

Ahora, defina dos funciones directamente en la calculadora.

Use una variable con una función incrustada en la configuración avanzada del botón (vea el ejemplo anterior) para generar botones dinámicamente según el valor del parámetro.

La información sobre los servicios es recuperada por el bot de la variable service_info, que contiene una función incrustada — get_info_for_booking() — para leer los datos del servicio. Anteriormente se demostró un ejemplo de cómo usar esta función.

Aquí está el resultado.

Ejemplo de código:

clear_assistant_chat_history()

replica_rec2 = ai_context_answer(question, 'ANSWER THE QUESTIONS', 3)

prompt = 'Un desarrollador se dirige a usted ahora mismo, haga todo lo que pida \n . Debe colocar cada botón en una nueva línea.'

ai_answer_rec = ai_context_answer("Muestre los botones para el último mensaje.", prompt)

Ejemplo: llamar al asistente dentro del constructor de embudos

Para llamar al asistente desde un bloque, use la función ai_context_answer(replica, prompt, ai_assistant_id, use_history), donde debe especificar solo dos parámetros: el parámetro replica obligatorio y el prompt opcional.

Ahora, creemos el primer bloque, "Verificación de condición primaria", donde debe especificar la condición de activación del bloque (puede ser cualquier condición que requiera).

A continuación, abra la calculadora en el mismo bloque, donde debe definir una variable y asignarle el valor devuelto por su función.

Defina la variable question y asígnele el valor de cualquier pregunta del usuario.

A continuación, cree la variable replica1 y asígnele el valor devuelto por su función ai_context_answer(replica, prompt). En esta función, reemplace replica con la variable question y establezca el parámetro prompt en "Responda cualquier pregunta del usuario."

Incruste la variable que contiene la función en el mensaje del bloque.

Luego cree un segundo bloque y conéctelo con una flecha, estableciendo un temporizador de 2 segundos en la conexión.

En el segundo bloque, debe usar la misma función con los mismos parámetros — ai_context_answer(replica, prompt).

Abra la calculadora en el segundo bloque y defina la segunda variable llamada replica2.

En el parámetro prompt, proporcione instrucciones para el asistente: debe contar cuántos sustantivos había en su mensaje anterior.

En el parámetro replica, proporcione el mensaje del asistente: "¿Cuántos sustantivos había en su mensaje anterior?"

Luego incruste la variable replica2 en el mensaje del segundo bloque.

La configuración del bloque está completa.

Si el asistente no está habilitado, vaya a la pestaña "Asistente de IA" y habilite el asistente seleccionando el rol "deshabilitado":

Ahora, probemos nuestro asistente en la ventana de prueba del bot.

El bot ha funcionado correctamente.

Cómo trabajar con Google Sheets

get_info_from_table(sheet_id, number_sheet, sheet_json_keys, start_row, end_row, start_col, end_col) - Esta función está destinada a leer datos de una hoja de cálculo.

Ejemplo de notación de parámetros:

Tenga en cuenta

Los parámetros para especificar el rango de filas y columnas (start_row, end_row, start_col, end_col) permiten al asistente leer los datos de la hoja de cálculo comenzando desde la ubicación deseada dentro de la tabla.

El comportamiento de la función para la especificación parcial del rango es el siguiente:

• Si solo se define el inicio: el asistente recuperará todos los datos desde ese punto de inicio en adelante, sin límite superior en la dirección especificada.
• Si solo se define el final: el asistente leerá los datos desde el principio de la hoja hasta ese punto final especificado.

Ejemplo:

La llamada get_info_from_table('<<spreadsheet id>>', 2, None, 2, 5, 'a', 'd') recupera todos los datos desde la fila 2, columna 2 (B), hasta la fila 5, y entre las columnas A y D.

Tenga en cuenta

Para optimizar el rendimiento y la fiabilidad, recomendamos almacenar en caché todos los datos de su Hoja de Cálculo de Google en variables del proyecto al trabajar con ella.

Beneficios clave:

1. Rendimiento mejorado: acelera significativamente el tiempo de respuesta del chatbot al acceder a variables locales en lugar de consultar la hoja de cálculo externa para cada solicitud.
2. Fiabilidad mejorada: minimiza los errores relacionados con la latencia de la red, las cuotas de API o los permisos de acceso a la hoja de cálculo.
3. Consistencia de datos: almacenar datos en la configuración del proyecto garantiza que todos los usuarios reciban acceso simultáneo y consistente al mismo conjunto de datos, evitando discrepancias durante las actualizaciones.

Ejemplo de uso

Puede leer más sobre la función get_info_from_table en el artículo "Hojas de Cálculo de Google para Asistente de IA".

Cómo gestionar reservas en línea

get_info_for_booking(slot_interval, company_id) - La función está diseñada para leer datos de servicio del sistema de reservas en línea configurado.

Acepta parámetros opcionales:

1. slot_interval (opcional) - un intervalo en minutos entre los espacios de tiempo disponibles. Formato esperado: un número entero divisible por 5. Valor por defecto: 60 (minutos).
2. company_id (opcional) - un identificador de sucursal. Formato esperado: un número entero o una matriz de números enteros. Cuando se proporciona este parámetro, solo se devolverán los datos de la(s) sucursal(es) especificada(s).
   
   Ejemplo: 50142, "50142", o "[50142, 66352]"

No se recomienda establecer un valor muy pequeño (por ejemplo, menos de 30), ya que el asistente generará demasiados espacios de tiempo.

Ejemplo de uso

Primero, debe preparar un bloque que actualice la información sobre todos los servicios después de que se hayan configurado los ajustes de la sucursal en la sección "Servicios".

Este bloque debe declararse antes de que el asistente comience a trabajar, para asegurar que la IA no genere respuestas aleatorias.

A continuación, active el bloque en la ventana de prueba del bot para actualizar la variable:

Después de eso, la variable especificada que contiene los datos del servicio de reservas en línea aparecerá en la sección de variables del proyecto dentro de "Configuración del proyecto".

Esta variable almacena los valores del servicio que el bot de IA utilizará en sus operaciones. La variable service_info será accesible para todos los clientes del proyecto.

A continuación, procedamos a configurar el siguiente bloque.

Este bloque cumple las siguientes funciones:

a) se llama en la configuración del asistente para generar un registro utilizando variables relacionadas con el servicio;

b) crea una reserva de cliente;

c) actualiza las variables del proyecto después de una reserva, elimina los espacios de tiempo que ya no están disponibles en el horario.

Si el bot está configurado correctamente, después de recibir todos los datos del cliente, la IA enviará la información al bloque especificado. En ese bloque, el cliente será reservado para el servicio utilizando la función create_booking_by_name(!service_name, !date, !date_time, company_id).

Los valores recopilados por el bot se pasan como parámetros a create_booking_by_name(!service_name, !date, !date_time, company_id).

La función create_booking_by_name(service_name, date, date_time, company_id) crea una reserva en el sistema utilizando los datos proporcionados por el asistente de IA. Acepta tres parámetros obligatorios para la creación de la reserva:

Dado que la información sobre los espacios disponibles ya no estará actualizada, se utiliza la misma variable con su función incorporada para actualizar las fechas y horas disponibles para la reserva.

Tenga en cuenta

Si hay algún cambio en el horario, el personal o los servicios, ejecute el bloque que contiene la variable del proyecto con la función incorporada en modo de prueba (ver Fig. Bloque 1).

Lea cómo configurar un bot de IA para reservas en línea se explicó en el artículo del mismo nombre.

Recuperar reserva de la tabla

get_records_from_table(table_id, start_row, count, start_col, end_col) - recuperar reserva de la tabla

Si solo se especifica el inicio del rango de filas o columnas, se recuperarán todos los datos desde ese punto en adelante sin un límite superior en el rango. Del mismo modo, puede omitir el inicio y especificar solo el final del rango.

Ejemplo (Calculadora)

Si necesita recuperar registros de la tabla, abra la sección "Calculadora" en la configuración del bloque e ingrese la función con los parámetros requeridos.

Para pasar parámetros como una variable del proyecto, anteponga al nombre de la variable que contiene la función el prefijo project.

Aquí está el ejemplo de la tabla.

El bot responderá de la siguiente manera.