AI tool calling

​

Declaring tools

import { aiPlugin, defineTool } from '@botmesh/ai'
import { z } from 'zod' // optional: any schema with safeParse()

bot.plug(aiPlugin({
  provider: 'openai',
  model: 'gpt-5-mini',
  persona: 'You are the assistant of La Espiga Bakery.',
  tools: {
    search_product: {
      description: 'Search the catalog by text',
      schema: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
      handler: async ({ q }: { q: string }) => db.products.search(q),
    },
    create_order: defineTool({
      title: 'Create order', // shown to the user in the confirmation
      description: 'Create an order for the customer. items: menu keys and quantities',
      schema: z.object({
        items: z.array(z.object({ product: z.enum(['rye_bread', 'croissant']), quantity: z.number().int().min(1) })).min(1),
      }),
      confirm: true, // ask the user "yes/no" before running it
      dedupe: 'args', // never run the very same order twice in a row
      timeoutMs: 10_000,
      handler: async (args, { ctx }) => db.orders.create({ ...args, chat: ctx?.from }),
    }),
  },
}))

​

Schemas

• JSON Schema: sent to the model as is and validated with a built-in subset (type, required, properties, enum, const, items, additionalProperties: false, minimum/maximum and their exclusive forms, minLength/maxLength, minItems/maxItems).
• safeParse validators (zod and similar): the arguments are validated with safeParse() and the handler receives the parsed data. The model-facing schema comes from the validator’s toJSONSchema() when it has one (zod v4); otherwise pass jsonSchema yourself.

​

The handler context

​

The tool loop

• maxSteps (default 5) caps the model calls per turn. Tool calls requested in the last allowed step are not run (the model would never see their results): the turn replies maxStepsMessage and emits loop.max_steps.
• Several calls in the same step run one after another, in order.
• Errors go to the model, never to the user: a handler that throws, invalid arguments, an unknown tool, a timeout or a declined confirmation become failed tool results, so the model can recover or explain.
• Timeouts: toolTimeoutMs (default 15000, 0 disables) applies to every tool unless the tool sets its own timeoutMs. On expiry the handler’s signal is aborted. Each model call keeps the plugin’s timeoutMs.
• The stored chat history stays plain user/assistant text: the intermediate tool turns are not persisted.

​

Human confirmation

• A clear yes (yes, ok, sure, yes please, sí…) runs the tool.
• A clear no (no, no thanks, cancel, cancelar…) declines it and the model is told not to retry it.
• Anything else, including a yes that adds changes (yes but make it 5), does not run the tool and is not discarded: the model gets { "executed": false, "reason": "user_replied", "userReply": "…" }, so it can call the tool again with the corrected arguments (the user confirms again) or answer the question.

• No double confirmation: when the turn has a confirmer, the system prompt gets a localized note (ai.tools.confirmNote) listing the confirm: true tools and telling the model not to ask “shall I place it?” itself but to call the tool as soon as the user expresses the intent. toolConfirm.systemNote replaces it with your own text or turns it off (false).
• toolConfirm.timeout (default '2m') bounds the wait. A timeout or /reset cancels the turn silently; /reset also cancels it after the approval, so the stale turn neither replies nor writes into the history it just cleared.
• Turns of the same chat are serialized: a new message waits for a detached turn to finish. A confirmation never replaces a conversation the user started meanwhile; the turn is cancelled instead and does not reply on top of that flow.

​

Yes/No buttons

• A press resolves the confirmation exactly like typing yes or no, and the interaction is acknowledged (Telegram answerCallbackQuery, Discord’s 3-second ack). Typed answers keep working alongside the buttons, including a reply with changes that goes back to the model.
• Once answered (or timed out / cancelled), the buttons are removed by editing the message into text with the choice (→ Yes) where the provider can edit and renders native buttons (Telegram, Discord).
• A press on a confirmation that is no longer pending (answered, superseded by a newer one, timed out, /reset) is acknowledged and ignored, before any routing: each confirmation has its own button ids, so an old press never answers a newer confirmation nor a later question of a conversation.
• Channels that render native buttons but cannot edit messages (WhatsApp Cloud API, Messenger, Instagram, Gupshup, TikTok) leave the buttons on screen. There, a press on a confirmation that is no longer pending gets a short localized reply (ai.tools.confirmExpired: “That confirmation is no longer active.”); toolConfirm.expiredNotice: false drops it silently. A chat handed off to a human never gets this notice (the press is only acknowledged). Optionally, toolConfirm.answeredNotice: true also replies ai.tools.confirmAnswered (“Answer received: Yes.”) when a press answers; it is off by default because those channels already show the user’s pick as their own message. Neither notice is sent where the buttons are edited away or where the confirmation is a numbered text menu (Baileys, Evolution, WPPConnect, Twilio, email, GoHighLevel): there a later answer is just text.
• Channels without native buttons (WhatsApp via Baileys, Evolution, WPPConnect, Twilio, SMS, email, GoHighLevel…) keep the typed question with the (yes/no) hint; a later answer there is plain text, with no expired-confirmation notice.
• toolConfirm.buttons: false always asks for a typed answer. A tool’s confirmMessage is used as is in both modes. A bot.locale() override of ai.tools.confirm is reused for buttons when you don’t translate ai.tools.confirmButtons too.

About to: Place order
• 5 × chocolate_cake
• 2 × coffee
Do you confirm? (yes/no)

​

Readable values and totals

• labels maps argument values to human labels, per argument key (also inside list items). Values without a label are shown as-is; the model and the handler keep receiving the raw keys.
• confirmLines(args) returns the lines to show instead of the arguments, inside the same localized wrapper. Use it to show what your code computed (prices, the total), so the user never confirms a number the model made up. confirmMessage still wins over both.

const MENU = { cheese_bread: { name: 'Cheese bread', price: 2500 }, coffee: { name: 'Coffee', price: 4000 } }

place_order: {
  title: 'Place order',
  labels: { product: { cheese_bread: 'Cheese bread', coffee: 'Coffee' } },
  // or, with prices and the total:
  confirmLines: ({ items }) => [
    ...items.map((i) => `• ${i.quantity} × ${MENU[i.product].name}: $${MENU[i.product].price * i.quantity}`),
    `Total: $${items.reduce((sum, i) => sum + MENU[i.product].price * i.quantity, 0)}`,
  ],
  // ...
}

About to: Place order
• 2 × Cheese bread: $5000
• 1 × Coffee: $4000
Total: $9000
Do you confirm? (yes/no)

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

bot.conversation('support', async (c, ctx) => {
  const text = await c.ask('How can I help you?')
  const answer = await ctx.tools.ai.replyInChat(chatKeyOf(ctx), text, {
    ctx,
    confirm: confirmWith(c, { timeout: '1m' }),
  })
  await ctx.reply(answer)
})

​

Repeated side effects

• Confirmation notice: when a confirm: true tool already ran in the chat with the same arguments, the prompt starts with a localized line (ai.tools.confirmRepeat): Heads-up: I already did «Place order» a moment ago (result: …). Confirming will do it again. The confirmer also receives it as previous. A call with different arguments (changing 3 → 2 units) is a new action: no notice, no previous. The result summary leaves out fields too nested to read (lists of objects).
• System prompt: the next turns list the actions already run (ai.tools.doneNote), asking the model not to repeat them unless the user asks explicitly.
• dedupe (opt-in per tool): a call with the same validated arguments as a successful run within the window is not run and not confirmed; the model gets { "executed": false, "reason": "duplicate", "previous": { "result", "secondsAgo" } }. dedupe: 'args' uses a 10-minute window; dedupe: { windowMs: 60_000 } sets your own. It also works for tools without confirm.

​

Best practices for side-effecting tools

1. Never let the model compute money. Prices, subtotals and totals are computed in your code: offer a quote tool (no confirm, no side effects) for “how much is…?”, compute the total again in the handler that stores the order, and show it in the confirmation with confirmLines (or confirmMessage). Return the computed total in the tool result so the model can repeat it instead of calculating it.
2. Validate catalog values with enum. Product keys, sizes, branches…: arguments are validated before the confirmation, so an invented product goes back to the model as an error and the user never confirms an impossible order. Pair the keys with labels (or names in confirmLines) so the user sees “Cheese bread”, not cheese_bread.
3. Give every create its update, cancel and list tools. If the model can only create, it will “fix” an order by creating another one, or say it changed something it could not. A list tool (my_orders) gives it the ids to update or cancel.
4. Use dedupe on create tools (dedupe: 'args'), so an identical order is not placed twice in a row when the model calls the tool again on its own.
5. Return an explicit { error } for unknown ids ({ error: 'No active order P-123. Check my_orders.' }), never a silent ok or null. The model reads it and tells the user; the run is not remembered as done.
6. Keep confirm: true on everything with side effects (create, update, cancel, pay, book). Read-only tools (menu, quote, list) do not need it.
7. Rely on the system note, do not fight it. With a confirmer, the system prompt tells the model which tools the system confirms, not to ask “shall I place it?” itself, not to mention the confirmation process and never to claim it did, changed, replaced or cancelled anything a tool result did not confirm (and to say so plainly when it has no tool for a request). Keep it on (toolConfirm.systemNote) unless you replace it with an equivalent text.

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

const MENU = {
  cheese_bread: { name: 'Cheese bread', price: 2500 },
  croissant: { name: 'Croissant', price: 5000 },
  coffee: { name: 'Coffee', price: 4000 },
} as const
type Product = keyof typeof MENU
type Item = { product: Product; quantity: number }
type Order = { id: string; items: Item[]; total: number; status: 'confirmed' | 'cancelled' }

const PRODUCTS = Object.keys(MENU)
const ITEMS = {
  type: 'array',
  minItems: 1,
  items: {
    type: 'object',
    properties: {
      product: { type: 'string', enum: PRODUCTS }, // only real products
      quantity: { type: 'integer', minimum: 1, maximum: 50 },
    },
    required: ['product', 'quantity'],
    additionalProperties: false,
  },
}
const ORDER_ID = { type: 'string', description: 'Order id (from my_orders)' }

// Money is computed here, never by the model.
const money = (n: number) => '$' + n.toLocaleString('en-US')
const quote = (items: Item[]) => {
  const lines = items.map((i) => ({ ...i, name: MENU[i.product].name, subtotal: MENU[i.product].price * i.quantity }))
  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.quantity} × ${l.name}: ${money(l.subtotal)}`), `Total: ${money(q.total)}`]
}

const orders = new Map<string, Order[]>() // per chat; use ctx.user or your DB in production
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.status !== 'cancelled')
const noOrder = (id: string) => ({ error: `No active order ${id}. Check my_orders.` })

const bot = new Bot({ provider })
bot.plug(aiPlugin({
  provider: 'anthropic',
  persona: 'You are the assistant of La Espiga Bakery. Use show_menu for products and quote_order for any price or total; never calculate amounts yourself.',
  tools: {
    show_menu: {
      description: 'List the menu: key, name and price.',
      handler: () => Object.entries(MENU).map(([key, p]) => ({ key, name: p.name, price: p.price })),
    },
    quote_order: {
      description: 'Compute prices, subtotals and the total of a list of products without placing anything.',
      schema: { type: 'object', properties: { items: ITEMS }, required: ['items'] },
      handler: ({ items }: { items: Item[] }) => quote(items),
    },
    my_orders: {
      description: "List the customer's orders with id, items, total and status.",
      handler: (_args: unknown, { ctx }) => ordersOf(ctx?.from),
    },
    place_order: {
      title: 'Place order',
      description: 'Place a new order. items: menu keys and quantities.',
      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), status: 'confirmed' }
        ordersOf(ctx?.from).push(order)
        return order // the model repeats this total, it does not compute it
      },
    },
    update_order: {
      title: 'Change order',
      description: 'Replace the items of an existing order (by id) with the complete new list.',
      schema: { type: 'object', properties: { id: ORDER_ID, items: ITEMS }, required: ['id', 'items'] },
      confirm: true,
      confirmLines: ({ id, items }: { id: string; items: Item[] }) => [`• Order: ${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))
      },
    },
    cancel_order: {
      title: 'Cancel order',
      description: 'Cancel an existing order by 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.status = 'cancelled'
        return { id, status: 'cancelled' }
      },
    },
  },
}))

​

Audit events

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 })
})

​

Providers

​

Using tools from your code

const r = await ctx.tools.ai.runTools(
  { messages: [{ role: 'user', content: ctx.body }] },
  { ctx },
)
r.text            // final answer
r.steps           // model calls made
r.toolResults     // every tool result, in order
r.maxStepsReached // true when the loop stopped at maxSteps
r.truncatedToolCalls // calls not run because the reply was cut off by the token cap

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

const provider = await resolveProvider({ provider: 'anthropic' })
const r = await runToolLoop({
  tools,
  generate: (input) => provider.generate(input),
  base: { system: 'You are a stock assistant.' },
  messages: [{ role: 'user', content: 'Is there rye bread left?' }],
  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'
    ? 'We have rye bread.'
    : { toolCalls: [{ name: 'search_product', args: { q: 'rye' } }] },
})

const searched: string[] = []
const client = new AIClient(mock, new ContextManager(new MemoryStore()), {
  tools: {
    search_product: {
      description: 'Search the catalog',
      schema: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
      handler: ({ q }: { q: string }) => { searched.push(q); return ['rye bread'] },
    },
  },
})

expect(await client.ask('do you have rye?')).toBe('We have rye bread.')
expect(searched).toEqual(['rye'])

​

Next steps

• AI plugin — providers and the full aiPlugin reference
• AI memory & RAG — per-user facts and answers from your documents
• Conversation flows — the runtime that hosts confirmations
• Bakery AI assistant example — these practices in a runnable WhatsApp bot (Baileys or Twilio)