Bot de IA - Herramientas personalizadas

[Discourse]

Esta guía explica cómo crear, configurar e integrar herramientas de IA personalizadas dentro del plugin Discourse AI, permitiendo a los administradores extender las capacidades del bot con funciones de JavaScript definidas por el usuario.

Nivel de usuario requerido: Administrador

Las herramientas son funcionalidades programables que el bot de IA puede utilizar para realizar tareas específicas o recuperar información más allá de las simples respuestas basadas en texto. Estas herramientas son scripts o integraciones que permiten al bot interactuar con API externas, manipular datos o ejecutar funciones adicionales para extender sus capacidades.

Resumen

Esta documentación cubre:

• Creación de una nueva herramienta de IA personalizada
• Configuración de parámetros y scripts de herramientas
• API disponibles para scripts de herramientas
• Integración de herramientas personalizadas con personas de IA
• Pruebas y solución de problemas de herramientas personalizadas

Creación de una nueva herramienta de IA personalizada

Para crear una nueva herramienta de IA:

1. Navegue a Panel de administración > Plugins > Discourse AI > Herramientas
2. Haga clic en “Nueva herramienta” (puede usar ajustes preestablecidos existentes para aprender sobre las opciones)
3. Rellene los siguientes campos:
   • Nombre: El nombre de la herramienta tal como se presenta al LLM
   • Descripción: La descripción de la herramienta tal como se presenta al LLM
   • Resumen: Resumen de lo que hace la herramienta para ayudar a los usuarios (se muestra en detalles)
   • Parámetros: Defina las entradas que necesita su herramienta tal como se presentan al LLM
   • Script: El código JavaScript que impulsa su herramienta
4. Haga clic en “Guardar”

Configuración de scripts de herramientas

API disponibles

Sus scripts de herramientas tienen acceso a las siguientes API:

1. Solicitudes HTTP:

   http.get(url, options)
   http.post(url, options)
   http.put(url, options)
   http.patch(url, options)
   http.delete(url, options)
   

   Úselas para interactuar con servicios externos. Puede usar options para especificar encabezados HTTP y cuerpo:

   http.get(url, { headers: { "Authorization": "Bearer key" } })
   http.post(url, { headers: { "Content-Type": "application/json" }, body: { key: "value" } })
   http.patch(url, { headers: { "Authorization": "Bearer key" }, body: "some body" })
   http.delete(url, { headers: { "Authorization": "Bearer key" } })
   http.put(url, { headers: { "Authorization": "Bearer key" }, body: "some body" })
   

   Todos los métodos HTTP devuelven { status: number, body: string }.

2. Integración con LLM (Modelo de Lenguaje):

   llm.truncate(text, length)
   

   Recorta el texto a una longitud de token especificada basada en el tokenizador del LLM configurado.

   llm.generate(prompt, options)
   

   Genera texto utilizando el LLM configurado. El prompt puede ser una cadena simple o un objeto estructurado como { messages: [{ type: "system", content: "..." }, { type: "user", content: "..." }] }. Las opciones incluyen json: true para solicitar y analizar automáticamente la salida JSON, así como temperature, top_p, max_tokens y stop_sequences.

3. Integración de carga personalizada (RAG)

   index.search(query, { filenames: ["file.pdf"], limit: 10 })
   

   Busca fragmentos de documentos RAG indexados adjuntos a esta herramienta. Devuelve Array<{ fragment: string, metadata: string | null }> ordenados por relevancia. El límite predeterminado es 10, máximo 200.

   index.getFile(filename)
   

   Recupera el contenido completo de un archivo RAG cargado por su nombre de archivo exacto. Devuelve el texto completo o null si no se encuentra.

4. Soporte de carga

   upload.create(filename, base_64_content)
   

   Crea una nueva carga. Devuelve { id: number, url: string, short_url: string }.

   upload.getUrl(shortUrl)
   

   Dado una URL corta (ej. upload://12345), devuelve la URL completa amigable con CDN.

   upload.getBase64(uploadIdOrShortUrl, maxPixels)
   

   Obtiene el contenido codificado en base64 de una carga existente. Acepta un ID de carga (número) o una URL corta (cadena). Parámetro opcional maxPixels para el redimensionamiento automático de imágenes (predeterminado: 10,000,000).

5. Control de la cadena de ejecución

   chain.setCustomRaw(raw)
   

   Establece el contenido sin formato final de la publicación del bot y detiene la cadena de ejecución de la herramienta. Útil para herramientas que generan directamente la respuesta completa (por ejemplo, herramientas de generación de imágenes).

6. Gestión de secretos

   secrets.get(alias)
   

   Devuelve el valor de la credencial vinculada al alias dado. Los alias se definen en la configuración de contratos secretos de la herramienta y se vinculan a Secretos de IA en el panel de administración. Lanza un error si el alias no está declarado, no está enlazado o falta la credencial.

   const apiKey = secrets.get("my_api_key");
   

7. Integración de Discourse

   Las herramientas pueden interactuar directamente con los datos de Discourse:

   discourse.baseUrl              // La URL base del sitio
   discourse.search(params)       // Realizar una búsqueda en Discourse
   discourse.getPost(post_id)     // Obtener detalles de la publicación (incluye contenido sin formato)
   discourse.getTopic(topic_id)   // Obtener detalles del tema (etiquetas, categoría, etc.)
   discourse.getUser(id_or_username)  // Obtener detalles del usuario
   discourse.createTopic(params)  // Crear un nuevo tema
   discourse.createPost(params)   // Crear una nueva publicación/respuesta
   discourse.editPost(post_id, raw, options)    // Editar el contenido de una publicación
   discourse.editTopic(topic_id, updates, options) // Editar propiedades del tema (etiquetas, categoría, visibilidad)
   discourse.createChatMessage(params) // Enviar un mensaje de chat
   discourse.createStagedUser(params)  // Crear un usuario provisional
   discourse.getAgent(name)       // Obtener otro agente de IA (con el método respondTo)
   discourse.updateAgent(name, updates) // Actualizar la configuración de un agente de IA
   discourse.getCustomField(type, id, key)      // Leer campo personalizado en publicación/tema/usuario
   discourse.setCustomField(type, id, key, value) // Establecer campo personalizado en publicación/tema/usuario
   

8. Objeto de contexto

   El objeto context proporciona información sobre dónde se está ejecutando la herramienta:

   • Contexto de conversación del bot: context.post_id, context.topic_id, context.private_message, context.participants, context.username, context.user_id
   • Contexto de chat: context.message_id, context.channel_id, context.username
   • Contexto de automatización: context.post_id, context.topic_id, context.username, context.user_id, context.feature_name, context.feature_context
   • Propiedades comunes: context.site_url, context.site_title, context.site_description

Funciones requeridas

Su script debe implementar:

• invoke(params): La función principal que se ejecuta cuando se llama a la herramienta

Opcionalmente, puede implementar:

• details(): Devuelve una cadena (puede incluir HTML básico) que describe la ejecución de la herramienta, que se muestra en la interfaz de chat
• customSystemMessage(): Se llama durante el ensamblaje del prompt (no durante la invocación de la herramienta). Devuelve una cadena que se añade al prompt del sistema, o null/undefined para omitir. Tiene acceso a los objetos context, discourse e index.

Ejemplo de script:

function invoke(params) {
  let result = http.get("https://api.example.com/data?query=" + params.query);
  return JSON.parse(result.body);
}

function details() {
  return "Datos obtenidos de la API de ejemplo";
}

Limitaciones y seguridad

• Tiempo de espera de ejecución: Tiempo de espera predeterminado de 2000 ms de tiempo de procesamiento de script. El temporizador se pausa durante las solicitudes HTTP externas (http.*) y las llamadas al LLM (llm.generate), por lo que solo cuenta el tiempo de procesamiento del script.
• Memoria: Límite máximo de 10 MB de heap de V8
• Solicitudes HTTP: Máximo de 20 solicitudes por ejecución de herramienta
• Entorno aislado (Sandboxed): Los scripts se ejecutan en un entorno V8 JavaScript restringido (a través de MiniRacer). Sin acceso a variables globales del navegador, al sistema de archivos del host o a bibliotecas del lado del servidor. Las solicitudes de red se retransmiten a través del backend de Discourse.

Pruebas de su herramienta

Debe probar cualquier herramienta que cree para asegurarse de que los resultados que se proporcionarán al LLM coincidan con sus expectativas.

Integración de herramientas con personas de IA

Para añadir su herramienta personalizada a una Persona de IA:

1. Vaya a Panel de administración > Plugins > Discourse AI > Personas
2. Edite una persona existente o cree una nueva
3. En la sección “Herramientas”, verá sus herramientas personalizadas enumeradas junto con las herramientas integradas
4. Seleccione su herramienta personalizada para añadirla a la persona

Herramientas personalizadas en acción

Una vez que proporcione la herramienta personalizada a su LLM, puede usarla para mejorar la conversación.

Solución de problemas

Si su herramienta no funciona como se esperaba:

1. Utilice la interfaz de prueba para asegurarse de que se comporta como se espera para sus entradas.
2. Asegúrese de que su grupo esté en ai_bot_debugging_allowed_groups. Los miembros de este grupo tienen acceso completo a las transcripciones del bot; puede ver los registros de IA allí.
3. Si algo inesperado está sucediendo, visite https://NOMBRE_DEL_SITIO/logs para verificar si hay errores.

Recursos adicionales

Discourse AI - AI bot

AI bot - Agents