Plugin de IA

• un autoresponder para cada mensaje de texto que tus comandos, triggers y flows no manejaron, con historial por chat;
• ctx.tools.ai, un cliente que llamas desde tus propios handlers, flows y conversaciones;
• opcionalmente, herramientas, memoria a largo plazo y RAG y streaming.

​

Quickstart (autoresponder)

pnpm add @botmesh/ai @anthropic-ai/sdk

import { Bot } from '@botmesh/core'
import { BaileysProvider } from '@botmesh/baileys'
import { aiPlugin } from '@botmesh/ai'

const bot = new Bot({ provider: new BaileysProvider({ session: 'mi-bot' }), lang: 'es' })

// Persona acotada al negocio (ver "Política de IA de WhatsApp" abajo).
const persona = [
  'Eres el asistente de atención al cliente de Panadería La Espiga.',
  'Solo respondes sobre sus productos, precios, horarios (lun-sáb 7:00-20:00), pedidos y encargos.',
  'Si te piden algo ajeno a la panadería, di con amabilidad que solo puedes ayudar con eso',
  'y ofrece pasar la conversación a una persona. Responde breve y en español; no inventes datos.',
].join(' ')

bot.plug(aiPlugin({
  provider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  persona,
}))

await bot.start()

• Un autoresponder catch-all (bot.onMessage) que contesta cualquier mensaje de texto que ningún comando, trigger o conversación haya consumido. Guarda en el store del bot una ventana de historial por chat (20 mensajes por defecto, context.maxMessages).
• Un comando /reset que borra el historial de IA del chat y cancela su conversación activa (se desactiva con resetCommand: false).

​

Política de IA de WhatsApp (desde el 15-01-2026)

• Escribe una persona acotada a tu negocio (qué vendes, horarios, políticas) que rechace con amabilidad lo que no tenga que ver con él, como en el quickstart.
• Ofrece una salida hacia una persona (handoff) y no presentes el bot como un asistente “para todo”.
• La regla viene de los términos de la Cloud API oficial (@botmesh/meta). Baileys es un cliente no oficial de WhatsApp Web y también está sujeto a los términos de WhatsApp.

​

Elegir proveedor

​

Anthropic (por defecto)

bot.plug(aiPlugin({
  provider: 'anthropic',                     // opcional, es el de por defecto
  apiKey: process.env.ANTHROPIC_API_KEY,     // o deja que el SDK lea ANTHROPIC_API_KEY
  model: 'claude-sonnet-5-5',                // por defecto: claude-opus-5-5
}))

​

OpenAI

bot.plug(aiPlugin({
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-5.1',   // obligatorio: OpenAI no trae modelo por defecto
}))

aiPlugin({ provider: 'openai', baseUrl: 'https://mi-proxy.example/v1', model: 'gpt-5.1', maxTokensField: 'max_completion_tokens' })

​

Gemini

bot.plug(aiPlugin({
  provider: 'gemini',
  apiKey: process.env.GEMINI_API_KEY,  // o define GEMINI_API_KEY / GOOGLE_API_KEY y omítela
  // model: 'gemini-3.8-flash',        // por defecto
}))

import { GoogleGenAI } from '@google/genai'
import { GeminiProvider, aiPlugin, fromGoogleGenAI } from '@botmesh/ai'

const ai = new GoogleGenAI({ vertexai: true, project: 'mi-proyecto', location: 'global' })
bot.plug(aiPlugin({ instance: new GeminiProvider(fromGoogleGenAI(ai), { model: 'gemini-3.8-flash' }) }))

​

Ollama (local o en la nube)

ollama pull llama3.1      # una vez
ollama serve              # si la app de escritorio no lo tiene ya en marcha

bot.plug(aiPlugin({
  provider: 'ollama',
  model: 'llama3.1',                   // obligatorio: Ollama no trae modelo por defecto
  // baseUrl: 'http://localhost:11434', // por defecto; cámbialo si el servidor está en otro host
}))

• Las herramientas necesitan un modelo entrenado para ellas (Llama 3.1+, Qwen 3, Mistral y los demás marcados tools en la biblioteca de Ollama).
• Sin tope de salida por defecto: maxTokens se envía como options.num_predict solo si lo fijas, para que un modelo que piensa no se corte a mitad del razonamiento.
• Modelos en la nube a través de tu Ollama local: inicia sesión una vez (ollama signin) y usa el nombre de un modelo en la nube (los que terminan en -cloud, como gpt-oss:120b-cloud) con la misma configuración. Ollama reenvía la petición a su nube; tu bot sigue hablando con localhost.
• La API en la nube de Ollama directamente (sin servidor local), o un Ollama detrás de un proxy con autenticación: pon apiKey y se envía como Authorization: Bearer <clave> (nunca va al log ni a un mensaje de error):
  bot.plug(aiPlugin({
    provider: 'ollama',
    baseUrl: 'https://ollama.com',
    model: 'gpt-oss:120b',
    apiKey: process.env.OLLAMA_API_KEY,
    persona,
  }))
  

​

Presets

bot.plug(aiPlugin({ provider: 'deepseek' }))  // DEEPSEEK_API_KEY, modelo deepseek-chat
bot.plug(aiPlugin({ provider: 'groq', model: 'llama-3.3-70b-versatile' }))

​

Versiones de SDK soportadas

​

Usar la IA desde tu código: ctx.tools.ai

bot.plug(aiPlugin({
  provider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  autoReply: false,
}))

bot.conversation('reclamo', async (c, ctx) => {
  await ctx.reply('📝 Cuéntanos qué pasó con tu pedido:')
  const texto = await c.waitText()
  const resumen = await ctx.tools.ai.ask(
    `Resume en 3 líneas este reclamo de un cliente para el equipo de soporte: ${texto}`,
  )
  await ctx.reply(`✅ Registramos tu reclamo:\n${resumen}`)
})

​

Pensamiento (Anthropic)

aiPlugin({ provider: 'anthropic', model: 'claude-haiku-4-5', thinking: { budgetTokens: 2048 } })

• 'adaptive' envía siempre pensamiento adaptativo; 'off' no envía nunca el parámetro (los modelos que siempre piensan, como Claude Opus 5.5, lo siguen haciendo: baja effort en su lugar).
• { budgetTokens } (un entero positivo; cualquier otro valor lanza un RangeError al construir la configuración) activa el pensamiento con presupuesto (budget_tokens, elevado al mínimo de 1024) en los modelos sin pensamiento adaptativo (Haiku 4.5, Sonnet 4.5, Opus 4.5 y anteriores). Los modelos adaptativos reciben pensamiento adaptativo: Opus / Sonnet 4.6 aún aceptan presupuestos pero los marcan como obsoletos, y Opus 4.7+, Sonnet 5+, Haiku 5+, Fable y Mythos los rechazan. Si maxTokens no deja sitio para la respuesta, pasa a ser budgetTokens + maxTokens.
• Si aun así la API rechaza la petición con un 400 que menciona thinking (o effort), la llamada se reintenta una vez sin ese parámetro y el modelo queda recordado, así que las siguientes llamadas ya no lo envían. anthropicModelSupport(model) expone las reglas.

​

Herramientas, memoria, RAG y streaming

bot.plug(aiPlugin({
  provider: 'openai',
  model: 'gpt-5-mini',
  tools: {
    buscar_producto: {
      description: 'Busca productos del catálogo por texto',
      schema: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
      handler: async ({ q }: { q: string }) => db.products.search(q),
    },
  },
}))

import { createRag } from '@botmesh/rag'

bot.plug(aiPlugin({
  provider: 'openai',
  model: 'gpt-5-mini',
  memory: { autoExtract: true, ttl: '90d' },
  rag: { retriever: createRag({ documents: ['./docs/faq.md'] }), appendSources: true },
}))

​

Formato por canal

​

Notas de voz

​

Idioma de las respuestas integradas

import { Bot } from '@botmesh/core'

const bot = new Bot({ provider, lang: 'es' })

​

/reset y slashCommandsPlugin

bot.plug(slashCommandsPlugin, { greeting: '🤖 ¡Hola!' })
bot.plug(aiPlugin({ apiKey: process.env.ANTHROPIC_API_KEY })) // su /reset gana

​

Coste y latencia

• Responde lo obvio sin IA. Los comandos, los triggers de bot.when() y los flows van antes que el autoresponder; las preguntas frecuentes, menús y saludos que resuelvas ahí nunca llegan al modelo.
• Elige el modelo según la tarea. Para atención al cliente suele bastar un modelo pequeño; dale a la extracción de memoria en segundo plano uno más barato (memory: { autoExtract: { model: '...' } }).
• Limita la salida. maxTokens acota cada respuesta (incluye los tokens de pensamiento de los modelos de razonamiento); en Anthropic, effort: 'low' piensa menos.
• Envía menos historial. Cada turno reenvía la ventana del chat: baja context.maxMessages para intercambios cortos. Con RAG, menos pasajes y más pequeños (topK, chunkSize) acortan el prompt.
• Acota el bucle de herramientas. Cada paso es una llamada al modelo: mantén maxSteps bajo y describe bien las herramientas para que el modelo acierte a la primera.
• No hables de más en grupos. groupMode: 'mentions' en el Bot hace que solo responda en grupos cuando lo mencionan.
• Que se sienta más rápido. stream: true muestra la respuesta mientras se escribe; humanizeTyping (activo por defecto) muestra “escribiendo…” mientras tanto.
• Protege tu cuota. El rate limiting limita cuántos mensajes puede colar un chat, y timeoutMs acota cada llamada.
• Mide. Con trazas, cada llamada al modelo es un span con su modelo y su consumo de tokens.

​

Errores y solución de problemas

​

Config completa de aiPlugin(config)

​

Testing

import { aiPlugin } from '@botmesh/ai'
import { MockAIProvider } from '@botmesh/ai/testing'
import { createTestBot } from '@botmesh/core/testing'

const { bot, chat } = await createTestBot({ lang: 'es' })
bot.plug(aiPlugin({ instance: new MockAIProvider({ reply: 'Abrimos a las 7.' }) }))

await chat.send('¿a qué hora abren?')
await chat.expectReply('Abrimos a las 7.')

import { AIClient, ContextManager, type ConvStore, type AIMessage } from '@botmesh/ai'
import { MockAIProvider } from '@botmesh/ai/testing'

const memory = new Map<string, AIMessage[]>()
const store: ConvStore = {
  async getConversation(k) { return memory.get(k) },
  async setConversation(k, m) { memory.set(k, m) },
  async clearConversation(k) { memory.delete(k) },
}

const client = new AIClient(new MockAIProvider({ reply: 'respuesta simulada' }), new ContextManager(store))

const respuesta = await client.ask('¿qué hora es?')
// respuesta === 'respuesta simulada'

​

Limitaciones

• El historial es una ventana fija de mensajes (context.maxMessages); los turnos antiguos se descartan, no se resumen.
• Una persona por plugin: un bot que necesite varias las elige en sus propios handlers con ctx.tools.ai.generate({ system, messages }).
• El autoresponder solo contesta texto (ver Notas de voz).

​

Siguientes pasos

• Herramientas de IA — deja que el modelo llame a funciones de tu bot
• Memoria y RAG — hechos por usuario y respuestas con tus documentos
• Respuestas en streaming — ctx.stream() por canal
• Voz — transcribe notas de voz y responde con audio
• Handoff — pasa el chat a una persona
• Plugins — cómo funciona bot.plug() en general