Herramientas de IA (tool calling)

​

Declarar herramientas

import { aiPlugin, defineTool } from '@botmesh/ai'
import { z } from 'zod' // opcional: cualquier esquema con safeParse()

bot.plug(aiPlugin({
  provider: 'openai',
  model: 'gpt-5-mini',
  persona: 'Eres el asistente de Panadería La Espiga.',
  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),
    },
    crear_pedido: defineTool({
      title: 'Crear pedido', // lo ve el usuario en la confirmación
      description: 'Crea un pedido para el cliente. items: claves del menú y cantidades',
      schema: z.object({
        items: z.array(z.object({ producto: z.enum(['pan_centeno', 'croissant']), cantidad: z.number().int().min(1) })).min(1),
      }),
      confirm: true, // pregunta "sí/no" al usuario antes de ejecutarla
      dedupe: 'args', // nunca registra el mismo pedido dos veces seguidas
      timeoutMs: 10_000,
      handler: async (args, { ctx }) => db.orders.create({ ...args, chat: ctx?.from }),
    }),
  },
}))

​

Esquemas

• JSON Schema: se envía tal cual al modelo y se valida con un subconjunto propio (type, required, properties, enum, const, items, additionalProperties: false, minimum/maximum y sus formas exclusivas, minLength/maxLength, minItems/maxItems).
• Validadores con safeParse (zod y similares): los argumentos se validan con safeParse() y el handler recibe el data ya parseado. El esquema para el modelo sale de toJSONSchema() si el validador lo tiene (zod v4); si no, pasa jsonSchema a mano.

​

El contexto del handler

​

El bucle de herramientas

• maxSteps (por defecto 5) limita las llamadas al modelo por turno. Las herramientas pedidas en el último paso permitido no se ejecutan (el modelo nunca vería su resultado): el turno responde maxStepsMessage y emite loop.max_steps.
• Varias llamadas en el mismo paso se ejecutan una tras otra, en orden.
• Los errores van al modelo, nunca al usuario: un handler que lanza, argumentos inválidos, una herramienta desconocida, un timeout o una confirmación rechazada se convierten en resultados fallidos, para que el modelo se recupere o lo explique.
• Timeouts: toolTimeoutMs (por defecto 15000, 0 lo desactiva) se aplica a todas las herramientas salvo a las que fijan su propio timeoutMs. Al vencer se aborta el signal del handler. Cada llamada al modelo mantiene el timeoutMs del plugin.
• El historial guardado sigue siendo texto plano usuario/asistente: los turnos intermedios de herramientas no se persisten.

​

Confirmación humana

• Un sí claro (sí, ok, dale, sí, por favor…) ejecuta la herramienta.
• Un no claro (no, no, gracias, cancelar…) la rechaza y se le dice al modelo que no reintente.
• Cualquier otra cosa, incluido un sí que pide cambios (sí pero cambia a 5 unidades), no ejecuta la herramienta ni se descarta: el modelo recibe { "executed": false, "reason": "user_replied", "userReply": "…" } para volver a llamarla con los argumentos corregidos (el usuario confirma de nuevo) o responder la pregunta.

• Sin doble confirmación: cuando el turno tiene confirmador, el prompt de sistema lleva una nota localizada (ai.tools.confirmNote) con las herramientas confirm: true, que le pide al modelo no preguntar “¿te lo registro?” sino llamar a la herramienta en cuanto el usuario exprese la intención. toolConfirm.systemNote la cambia por tu texto o la apaga (false).
• toolConfirm.timeout (por defecto '2m') limita la espera. Un timeout o /reset cancela el turno en silencio; /reset también lo cancela después de la aprobación, así que el turno viejo no responde ni escribe en el historial recién borrado.
• Los turnos de un mismo chat se serializan: un mensaje nuevo espera a que termine un turno desacoplado. Una confirmación nunca reemplaza una conversación que el usuario haya abierto entretanto; el turno se cancela y no responde encima de ese flujo.

​

Botones Sí/No

• Pulsar un botón resuelve la confirmación igual que escribir sí o no, y la interacción se reconoce (answerCallbackQuery en Telegram, el ack de 3 segundos de Discord). Las respuestas escritas siguen funcionando junto a los botones, también una respuesta con cambios, que vuelve al modelo.
• Ya respondida (o caducada / cancelada), los botones se quitan editando el mensaje a texto con la elección (→ Sí) donde el provider puede editar y pinta botones nativos (Telegram, Discord).
• Una pulsación sobre una confirmación que ya no está pendiente (respondida, sustituida por otra más nueva, caducada, /reset) se reconoce y se ignora antes de enrutar nada: cada confirmación tiene sus propios ids de botón, así que una pulsación vieja nunca responde una confirmación más nueva ni una pregunta posterior de una conversación.
• Canales que pintan botones nativos pero no editan mensajes (WhatsApp Cloud API, Messenger, Instagram, Gupshup, TikTok): los botones se quedan en pantalla. Ahí, una pulsación sobre una confirmación que ya no está pendiente recibe una respuesta corta localizada (ai.tools.confirmExpired: “Esa confirmación ya no está activa.” / “That confirmation is no longer active.”); toolConfirm.expiredNotice: false la descarta en silencio. Un chat en handoff con un humano nunca recibe este aviso (la pulsación solo se reconoce). Opcionalmente, toolConfirm.answeredNotice: true responde también ai.tools.confirmAnswered (“Respuesta recibida: Sí.” / “Answer received: Yes.”) cuando una pulsación responde; va apagado por defecto porque esos canales ya muestran la elección como mensaje del usuario. Ninguno de los dos avisos sale donde los botones se quitan editando ni donde la confirmación es un menú de texto numerado (Baileys, Evolution, WPPConnect, Twilio, email, GoHighLevel): ahí una respuesta posterior es solo texto.
• Los canales sin botones nativos (WhatsApp vía Baileys, Evolution, WPPConnect, Twilio, SMS, email, GoHighLevel…) mantienen la pregunta escrita con la coletilla (sí/no); ahí una respuesta posterior es texto normal y no hay aviso de confirmación caducada.
• toolConfirm.buttons: false pide siempre la respuesta escrita. El confirmMessage de una herramienta se usa tal cual en los dos modos. Un bot.locale() que cambia ai.tools.confirm se reutiliza para los botones si no traduces también ai.tools.confirmButtons.

Voy a: Crear pedido
• 5 × torta_chocolate
• 2 × cafe
¿Confirmas? (sí/no)

​

Valores legibles y totales

• labels traduce valores de argumentos a etiquetas humanas, por clave de argumento (también dentro de los ítems de una lista). Los valores sin etiqueta se muestran tal cual; el modelo y el handler siguen recibiendo las claves crudas.
• confirmLines(args) devuelve las líneas que se muestran en lugar de los argumentos, dentro del mismo envoltorio localizado. Úsala para mostrar lo que calculó tu código (precios, total), así el usuario nunca confirma un número que se inventó el modelo. confirmMessage sigue mandando sobre ambas.

const MENU = { pan_de_bono: { name: 'Pan de bono', price: 2500 }, cafe: { name: 'Café', price: 4000 } }

crear_pedido: {
  title: 'Crear pedido',
  labels: { producto: { pan_de_bono: 'Pan de bono', cafe: 'Café' } },
  // o, con precios y total:
  confirmLines: ({ items }) => [
    ...items.map((i) => `• ${i.cantidad} × ${MENU[i.producto].name}: $${MENU[i.producto].price * i.cantidad}`),
    `Total: $${items.reduce((sum, i) => sum + MENU[i.producto].price * i.cantidad, 0)}`,
  ],
  // ...
}

Voy a: Crear pedido
• 2 × Pan de bono: $5000
• 1 × Café: $4000
Total: $9000
¿Confirmas? (sí/no)

import { chatKeyOf, confirmWith } from '@botmesh/ai'

bot.conversation('soporte', async (c, ctx) => {
  const texto = await c.ask('¿En qué te ayudo?')
  const respuesta = await ctx.tools.ai.replyInChat(chatKeyOf(ctx), texto, {
    ctx,
    confirm: confirmWith(c, { timeout: '1m' }),
  })
  await ctx.reply(respuesta)
})

​

Efectos secundarios repetidos

• Aviso en la confirmación: si una herramienta confirm: true ya se ejecutó en el chat con los mismos argumentos, la pregunta empieza con una línea localizada (ai.tools.confirmRepeat): Ojo: ya hice «Crear pedido» hace un momento (resultado: …). Si confirmas, se hará otra vez. El confirmador la recibe también como previous. Una llamada con argumentos distintos (cambiar 3 → 2 unidades) es una acción nueva: sin aviso ni previous. El resumen del resultado omite los campos demasiado anidados para leerse (listas de objetos).
• Prompt de sistema: los turnos siguientes listan las acciones ya hechas (ai.tools.doneNote) y le piden al modelo no repetirlas salvo que el usuario lo pida explícitamente.
• dedupe (opcional por herramienta): una llamada con los mismos argumentos validados que una ejecución correcta dentro de la ventana no se ejecuta ni se confirma; el modelo recibe { "executed": false, "reason": "duplicate", "previous": { "result", "secondsAgo" } }. dedupe: 'args' usa una ventana de 10 minutos; dedupe: { windowMs: 60_000 } fija la tuya. También sirve para herramientas sin confirm.

​

Buenas prácticas para herramientas con efectos

1. Nunca dejes que el modelo calcule dinero. Precios, subtotales y totales se calculan en tu código: ofrece una herramienta de cotización (sin confirm, sin efectos) para el “¿cuánto cuesta…?”, vuelve a calcular el total en el handler que guarda el pedido y muéstralo en la confirmación con confirmLines (o confirmMessage). Devuelve el total calculado en el resultado para que el modelo lo repita en vez de calcularlo.
2. Valida los valores de catálogo con enum. Claves de producto, tamaños, sedes…: los argumentos se validan antes de la confirmación, así que un producto inventado vuelve al modelo como error y el usuario nunca confirma un pedido imposible. Acompaña las claves con labels (o nombres en confirmLines) para que el usuario vea “Pan de bono” y no pan_de_bono.
3. Cada herramienta de crear trae las de cambiar, cancelar y listar. Si el modelo solo puede crear, “corrige” un pedido creando otro o dice que cambió algo que no podía cambiar. Una herramienta de listado (mis_pedidos) le da los ids para cambiar o cancelar.
4. Usa dedupe en las de crear (dedupe: 'args'), para que un pedido idéntico no se registre dos veces seguidas cuando el modelo vuelve a llamar la herramienta por su cuenta.
5. Devuelve un { error } explícito para ids desconocidos ({ error: 'No existe un pedido activo P-123. Consulta mis_pedidos.' }), nunca un ok o null silencioso. El modelo lo lee y se lo dice al usuario; la ejecución no se recuerda como hecha.
6. Mantén confirm: true en todo lo que tenga efectos (crear, cambiar, cancelar, pagar, reservar). Las de solo lectura (menú, cotizar, listar) no lo necesitan.
7. Apóyate en la nota de sistema, no la pelees. Con un confirmador, el prompt de sistema le dice al modelo qué herramientas confirma el sistema, que no pregunte “¿te lo registro?” él mismo, que no mencione el proceso de confirmación y que nunca diga que hizo, cambió, reemplazó o canceló algo que ningún resultado de herramienta confirmó (y que lo diga con claridad cuando no tiene herramienta para lo que le piden). Déjala activa (toolConfirm.systemNote) salvo que la reemplaces por un texto equivalente.

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

const MENU = {
  pan_de_bono: { name: 'Pan de bono', price: 2500 },
  croissant: { name: 'Croissant', price: 5000 },
  cafe: { name: 'Café', price: 4000 },
} as const
type Product = keyof typeof MENU
type Item = { producto: Product; cantidad: number }
type Order = { id: string; items: Item[]; total: number; estado: 'confirmado' | 'cancelado' }

const PRODUCTS = Object.keys(MENU)
const ITEMS = {
  type: 'array',
  minItems: 1,
  items: {
    type: 'object',
    properties: {
      producto: { type: 'string', enum: PRODUCTS }, // solo productos reales
      cantidad: { type: 'integer', minimum: 1, maximum: 50 },
    },
    required: ['producto', 'cantidad'],
    additionalProperties: false,
  },
}
const ORDER_ID = { type: 'string', description: 'Id del pedido (mis_pedidos)' }

// El dinero se calcula aquí, nunca en el modelo.
const money = (n: number) => '$' + n.toLocaleString('es-CO')
const quote = (items: Item[]) => {
  const lines = items.map((i) => ({ ...i, nombre: MENU[i.producto].name, subtotal: MENU[i.producto].price * i.cantidad }))
  return { items: lines, total: lines.reduce((sum, l) => sum + l.subtotal, 0) }
}
const quoteLines = (items: Item[]) => {
  const q = quote(items)
  return [...q.items.map((l) => `• ${l.cantidad} × ${l.nombre}: ${money(l.subtotal)}`), `Total: ${money(q.total)}`]
}

const orders = new Map<string, Order[]>() // por chat; en producción, ctx.user o tu base de datos
const ordersOf = (chat = '') => {
  if (!orders.has(chat)) orders.set(chat, [])
  return orders.get(chat)!
}
const active = (chat: string | undefined, id: string) => ordersOf(chat).find((o) => o.id === id && o.estado !== 'cancelado')
const noOrder = (id: string) => ({ error: `No existe un pedido activo ${id}. Consulta mis_pedidos.` })

const bot = new Bot({ provider, lang: 'es' })
bot.plug(aiPlugin({
  provider: 'anthropic',
  persona: 'Eres el asistente de Panadería La Espiga. Usa ver_menu para los productos y cotizar_pedido para cualquier precio o total; nunca calcules importes tú.',
  tools: {
    ver_menu: {
      description: 'Lista el menú: clave, nombre y precio.',
      handler: () => Object.entries(MENU).map(([clave, p]) => ({ clave, nombre: p.name, precio: p.price })),
    },
    cotizar_pedido: {
      description: 'Calcula precios, subtotales y total de una lista de productos sin registrar nada.',
      schema: { type: 'object', properties: { items: ITEMS }, required: ['items'] },
      handler: ({ items }: { items: Item[] }) => quote(items),
    },
    mis_pedidos: {
      description: 'Lista los pedidos del cliente con id, productos, total y estado.',
      handler: (_args: unknown, { ctx }) => ordersOf(ctx?.from),
    },
    crear_pedido: {
      title: 'Crear pedido',
      description: 'Registra un pedido nuevo. items: claves del menú y cantidades.',
      schema: { type: 'object', properties: { items: ITEMS }, required: ['items'] },
      confirm: true,
      dedupe: 'args',
      confirmLines: ({ items }: { items: Item[] }) => quoteLines(items),
      handler: ({ items }: { items: Item[] }, { ctx }) => {
        const order: Order = { id: 'P-' + Date.now().toString(36).toUpperCase(), ...quote(items), estado: 'confirmado' }
        ordersOf(ctx?.from).push(order)
        return order // el modelo repite este total, no lo calcula
      },
    },
    actualizar_pedido: {
      title: 'Cambiar pedido',
      description: 'Reemplaza los productos de un pedido existente (por id) con la nueva lista completa.',
      schema: { type: 'object', properties: { id: ORDER_ID, items: ITEMS }, required: ['id', 'items'] },
      confirm: true,
      confirmLines: ({ id, items }: { id: string; items: Item[] }) => [`• Pedido: ${id}`, ...quoteLines(items)],
      handler: ({ id, items }: { id: string; items: Item[] }, { ctx }) => {
        const order = active(ctx?.from, id)
        if (!order) return noOrder(id)
        return Object.assign(order, quote(items))
      },
    },
    cancelar_pedido: {
      title: 'Cancelar pedido',
      description: 'Cancela un pedido existente por id.',
      schema: { type: 'object', properties: { id: ORDER_ID }, required: ['id'] },
      confirm: true,
      handler: ({ id }: { id: string }, { ctx }) => {
        const order = active(ctx?.from, id)
        if (!order) return noOrder(id)
        order.estado = 'cancelado'
        return { id, estado: 'cancelado' }
      },
    },
  },
}))

​

Eventos de auditoría

import type { AIToolEvent } from '@botmesh/ai'

bot.on('ai.tool', (e: AIToolEvent) => {
  audit.write({ type: e.type, tool: e.tool, step: e.step, chat: e.chatKey, ms: e.durationMs })
})

​

Proveedores

​

Usar herramientas desde tu código

const r = await ctx.tools.ai.runTools(
  { messages: [{ role: 'user', content: ctx.body }] },
  { ctx },
)
r.text            // respuesta final
r.steps           // llamadas al modelo realizadas
r.toolResults     // cada resultado de herramienta, en orden
r.maxStepsReached // true si el bucle se detuvo en maxSteps
r.truncatedToolCalls // llamadas no ejecutadas porque la respuesta se cortó por el tope de tokens

import { resolveProvider, runToolLoop } from '@botmesh/ai'

const provider = await resolveProvider({ provider: 'anthropic' })
const r = await runToolLoop({
  tools,
  generate: (input) => provider.generate(input),
  base: { system: 'Eres un asistente de inventario.' },
  messages: [{ role: 'user', content: '¿Queda pan de centeno?' }],
  maxSteps: 3,
  onEvent: (e) => console.log(e.type),
})

​

Testing

import { AIClient, ContextManager } from '@botmesh/ai'
import { MockAIProvider } from '@botmesh/ai/testing'
import { MemoryStore } from '@botmesh/core'

const mock = new MockAIProvider({
  reply: (input) => input.messages.at(-1)?.role === 'tool'
    ? 'Tenemos pan de centeno.'
    : { toolCalls: [{ name: 'buscar_producto', args: { q: 'centeno' } }] },
})

const buscados: string[] = []
const client = new AIClient(mock, new ContextManager(new MemoryStore()), {
  tools: {
    buscar_producto: {
      description: 'Busca en el catálogo',
      schema: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
      handler: ({ q }: { q: string }) => { buscados.push(q); return ['pan de centeno'] },
    },
  },
})

expect(await client.ask('¿tienen centeno?')).toBe('Tenemos pan de centeno.')
expect(buscados).toEqual(['centeno'])

​

Siguientes pasos

• Plugin de IA — proveedores y la referencia completa de aiPlugin
• Memoria y RAG — hechos por usuario y respuestas con tus documentos
• Flujos conversacionales — el runtime que aloja las confirmaciones
• Ejemplo: asistente de panadería — estas prácticas en un bot de WhatsApp ejecutable (Baileys o Twilio)