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

[maiki]

Me estoy iniciando en la creación de herramientas para personas de IA en Discourse, en parte para poder centrarme en ello; ¡esto parece muy útil dada la cantidad de APIs útiles y públicas que existen!

Por ejemplo, estoy obteniendo resultados como:

Comprensión de la toma de decisiones a través de estrategias de póker IA

maiki:

Crea una ficha informativa para Breath of the Wild.

gpt-4o:

Aquí tienes una ficha informativa para “The Legend of Zelda: Breath of the Wild”:

---

Título: The Legend of Zelda: Breath of the Wild
Desarrollador: Nintendo
Editor: Nintendo
Fecha de lanzamiento: 3 de marzo de 2017
Plataformas: Nintendo Switch, Wii U
Género: Acción-aventura
Modo: Un jugador

Sinopsis:
Ambientado en un vasto mundo abierto, los jugadores controlan a Link, que despierta de un profundo letargo para derrotar a Calamity Ganon y salvar el reino de Hyrule. El juego es elogiado por su entorno inmersivo, que permite a los jugadores explorar e interactuar libremente con el mundo y sus sistemas.

Premios:
El juego ha ganado numerosos premios, incluyendo varios galardones al Juego del Año, por su diseño innovador, su mundo expansivo y su jugabilidad encantadora.

Más información: Entrada de Wikidata

---

“Breath of the Wild” es conocido por redefinir los juegos de mundo abierto y ofrecer una experiencia cautivadora que fomenta la exploración y el descubrimiento.

maiki:

Lo mismo para Animal Crossing: New Horizons.

gpt-4o:

Aquí tienes una ficha informativa para “Animal Crossing: New Horizons”:

---

Título: Animal Crossing: New Horizons
Desarrollador: Nintendo
Editor: Nintendo
Fecha de lanzamiento: 20 de marzo de 2020
Plataforma: Nintendo Switch
Género: Simulación social
Modo: Un jugador, Multijugador

Sinopsis:
En este encantador juego de simulación social, los jugadores asumen el papel de un personaje personalizable que se muda a una isla desierta tras comprar un paquete de Tom Nook. El juego permite la exploración en tiempo real, la recolección de recursos, la creación y la personalización, fomentando una experiencia de juego comunitaria y relajante.

Premios:
El juego fue aclamado por su libertad creativa y el momento de su lanzamiento, recibiendo galardones al Juego del Año y por sus contribuciones a los juegos sociales durante la pandemia mundial.

Más información: Entrada de Wikidata

---

“Animal Crossing: New Horizons” se convirtió en un fenómeno cultural, celebrado por sus atractivas funciones sociales y su jugabilidad para aliviar el estrés en tiempos difíciles.

maiki:

A Long Way from Chicago

gpt-4o:

Aquí tienes una ficha informativa para el libro “A Long Way from Chicago”:

---

Título: A Long Way from Chicago
Autor: Richard Peck
Año de publicación: 1998
Género: Ficción histórica, Juvenil
ISBN: 978-0141303529

Sinopsis:
Esta novela, galardonada con el Newbery Honor, es una colección de cuentos que narran las visitas anuales de verano de Joey y su hermana Mary Alice desde Chicago a un pueblo rural de Illinois para visitar a su extravagante abuela Dowdel a finales de los años 20 y 30. Cada capítulo presenta un episodio divertido y conmovedor que imparte lecciones de vida en el contexto de la Gran Depresión.

Premios:
El libro fue galardonado con el Newbery Honor en 1999 y es celebrado por su humor, profundidad y representación de la vida rural estadounidense a principios del siglo XX.

Más información: Entrada de Wikidata

---

Este libro es apreciado por su narrativa nostálgica y conmovedora, que captura la esencia de los lazos familiares y los tiempos más sencillos.

maiki:

Thinking in Bets

gpt-4o:

Anteriormente encontré la entrada de Wikidata para “Thinking in Bets”, pero no puedo recuperar más detalles específicos directamente de Wikidata en este momento. Sin embargo, aquí tienes una breve ficha basada en la información disponible:

---

Título: Thinking in Bets: Making Smarter Decisions When You Don’t Have All the Facts
Autor: Annie Duke
Año de publicación: 2018
Género: No ficción, Toma de decisiones, Psicología
ISBN: 978-0735216358

Sinopsis:
El libro utiliza ideas del póker para ayudar a los lectores a comprender la toma de decisiones bajo incertidumbre. Annie Duke, combinando sus experiencias como jugadora de póker profesional y psicóloga cognitiva, ofrece un marco para tomar decisiones más inteligentes, evaluar resultados y adoptar una mentalidad probabilística.

Más información: Entrada de Wikidata

---

Para obtener información detallada, puedes considerar consultar recursos o bases de datos adicionales relacionados con publicaciones de libros.

---

De acuerdo, eso está bien, pero noté esta descripción…

@Discourse

Descripción: La descripción de la herramienta tal como se presenta al LLM

…y me pregunto: ¿debería estar creando mis prompts refiriéndome directamente a esas herramientas, para un uso eficiente?

Mi enfoque general para escribir prompts es refinar con el tiempo y luego fijar un patrón de comportamiento que deseo que las herramientas de IA adopten. Sin embargo, si pudiera agregar instrucciones específicas sobre, por ejemplo, cuándo buscar una entidad de Wikidata y cuándo listar todas las afirmaciones de una entidad en particular (dos APIs diferentes), entonces siento que podría refinar todo el flujo de trabajo para que fluya como lo intento…

[MachineScholar]

Efectivamente, explicar claramente la herramienta y proporcionar ejemplos en el prompt del sistema es beneficioso.

[MachineScholar]

¿Es posible en una herramienta personalizada insertar la clave API y el proyecto de OpenAI desde la configuración del administrador?

[sam (Sam Saffron)]

Puedes hacer llamadas REST desde una herramienta personalizada y especificar todas las cabeceras.

[MachineScholar]

Me acabo de dar cuenta, lol… disculpa la metedura de pata.

[tpetrov (Toni Petrov)]

He subido algunos documentos a una persona, generó los embeddings y ahora puede realizar búsquedas semánticas sobre ellos. Pero en algunos casos, la búsqueda semántica no es ideal, por lo que me gustaría mejorarla y tener una búsqueda híbrida, por ejemplo, mantener lo que ya está ahí y añadir búsqueda por palabras clave. En este momento, si quisiera hacer eso, tendría que escribir una herramienta personalizada, ¿verdad?
Sé que podría simplemente publicar los documentos como temas y entonces funcionaría directamente con la búsqueda nativa de Discourse, pero actualmente no es una opción.

[jorge-gbs (Jorge Fernandez)]

Estoy viendo un error de esquema de herramienta al agregar una herramienta personalizada con un parámetro de matriz. Error al iniciar la conversación:

{
“error”: {
“code”: 400,
“message”: “* GenerateContentRequest.tools[0].function_declarations[3].parameters.properties[properties].items: falta el campo.\n”,
“status”: “INVALID_ARGUMENT”
}
}

Lo que intenté:

• Creé una herramienta personalizada con un parámetro llamado properties de tipo array.
• La interfaz de usuario de la lista de parámetros no permite especificar items.
• Exporté/importé un JSON de herramienta completo que incluye items: { type: “string” } para properties.
• Después de importar, el error persiste tan pronto como la herramienta se habilita para una personalidad. Si elimino la herramienta, el bot funciona.

Esperado:

La interfaz de usuario de la lista de parámetros debería permitir definir tipos de elementos de matriz, o la importación debería respetar items para que el esquema se valide.

¿Alguien ha visto esto? ¿Existe una limitación conocida o una ruta de interfaz de usuario requerida para definir parámetros de matriz?