Saltar al contenido

Function calling explicado con un carrito de compras

En la práctica/ 13 min de lectura

Function calling con un carrito de compras: tres herramientas en Node, el ciclo tool_use y tool_result, errores con is_error y qué validar en tu código.

  • IA
  • Node.js
En este artículo (8)
  1. Qué es una herramienta en function calling
  2. Definir buscar_producto, agregar_al_carrito y calcular_envio
  3. El ciclo: el modelo pide, tu código ejecuta, el modelo responde
  4. Manejo de errores
  5. Validar lo que pide el modelo
  6. Errores comunes
  7. Preguntas frecuentes
  8. Checklist

Function calling es la forma en que un modelo de IA usa funciones de tu código. Le describes cada herramienta con un nombre, una descripción y un esquema JSON; el modelo no ejecuta nada: responde pidiendo una llamada con argumentos, tu código la ejecuta y le devuelve el resultado para que conteste al cliente.

Aquí lo armamos con un caso de tienda: un asistente con tres herramientas, buscar_producto, agregar_al_carrito y calcular_envio, en Node con TypeScript y el SDK oficial @anthropic-ai/sdk. Las formas de las peticiones y respuestas salen de la documentación de tool use de Anthropic, revisada el 19 de noviembre de 2026. El ciclo lo probamos con un cliente simulado que devuelve respuestas con esa forma, sin llamar a la API de pago. Los productos, precios, existencias y la regla de envío del ejemplo son ilustrativos.

Qué es una herramienta en function calling

Anthropic lo llama tool use y aclara que también se le dice function calling. Una herramienta es una definición que mandas en el parámetro tools de cada petición, con tres partes: un name que cumpla ^[a-zA-Z0-9_-]{1,128}$, una description en texto plano y un input_schema en JSON Schema con los parámetros que espera. No mandas código: el modelo nunca ve tu función, solo su descripción.

Cuando el modelo decide usarla, la respuesta llega con stop_reason: "tool_use" y uno o varios bloques tool_use, cada uno con un id, el name de la herramienta y un input con los argumentos. Ejecutar la función es trabajo tuyo. Hay otro tipo, las herramientas de servidor (búsqueda web, ejecución de código), que corren en la infraestructura de Anthropic; en un carrito no las necesitas, porque tus datos viven en tu base de datos.

La diferencia con un chatbot RAG es el tipo de ayuda: un chatbot RAG le da al modelo texto para leer; function calling le da acciones que tu código controla. Y si lo único que quieres es que el modelo te devuelva datos con forma fija, sin ejecutar nada, lo que buscas son salidas JSON con structured outputs, que usan el mismo mecanismo de esquema.

La documentación es clara sobre qué pesa más: una descripción detallada es "por mucho" el factor más importante. Pide al menos tres o cuatro frases por herramienta: qué hace, cuándo usarla y cuándo no, qué significa cada parámetro y qué no devuelve.

Definir buscar_producto, agregar_al_carrito y calcular_envio

Las tres herramientas cubren el recorrido de una compra hasta antes de pagar: encontrar el producto, meterlo al carrito y saber cuánto cuesta el envío. Las tres se arman con la misma función, así el esquema no se repite. Este es el fragmento con agregar_al_carrito; el archivo completo va en la guía:

// Strict schema: every field required, no extra fields.
const herramienta = (name: string, description: string, properties: Record<string, object>): Anthropic.Tool => ({
  name,
  description,
  strict: true,
  input_schema: { type: "object", properties, required: Object.keys(properties), additionalProperties: false },
});

export const tools: Anthropic.Tool[] = [
  // buscar_producto and calcular_envio are built the same way (full file in the guide)
  herramienta(
    "agregar_al_carrito",
    "Agrega un producto al carrito de la sesión actual. Necesita el sku exacto que devolvió buscar_producto y una cantidad entera de 1 a 10. Si no hay stock suficiente, devuelve un error con las unidades disponibles. El precio lo pone la tienda, no se envía.",
    {
      sku: { type: "string", description: "SKU exacto, por ejemplo TAZA-350" },
      cantidad: { type: "integer", description: "Unidades a agregar, de 1 a 10" },
    },
  ),
];
  1. herramienta devuelve el objeto que espera la API: name, description, strict e input_schema. El tipo Anthropic.Tool del SDK revisa que la forma sea correcta.
  2. strict: true activa el modo estricto, que obliga a que el input cumpla el esquema siempre: tipos correctos, campos requeridos presentes y un nombre de herramienta válido.
  3. required: Object.keys(properties) marca todos los campos como obligatorios y additionalProperties: false impide campos extra, como un precio que nadie pidió. El modo estricto exige ese false.
  4. El nombre, agregar_al_carrito, usa guiones bajos y no lleva acentos, porque la expresión regular solo admite letras, números, guion y guion bajo.
  5. La descripción dice qué hace, de dónde sale el sku (de buscar_producto), el rango de la cantidad, qué pasa sin stock y que el precio no es una entrada.
  6. Las propiedades definen dos campos: sku como texto y cantidad como entero, así no llega "2" ni "dos".

Falta algo a propósito: minimum y maximum. El modo estricto no admite restricciones numéricas ni de longitud; si las pones, la API responde con un error 400. Por eso el límite de 1 a 10 va en la descripción, para que el modelo lo sepa, y en tu código, para que se cumpla.

tres herramientas, cada una con su input_schemabuscar_productoinput_schemaconsulta: stringtu código valida:texto no vacíoagregar_al_carritoinput_schemasku: stringcantidad: integertu código valida:sku real, 1 a 10, stockcalcular_envioinput_schemacodigo_postal: stringtu código valida:5 dígitos y carritostrict: true · required · additionalProperties: falseel modelo elige la herramienta y escribe la entradastrict no admite minimum ni maximum: el límite va en tu código

Desliza la figura para verla completa

El ciclo: el modelo pide, tu código ejecuta, el modelo responde

La documentación describe cinco pasos. Ejecutas cada herramienta que pide un bloque tool_use; en una nueva petición conservas los mensajes anteriores y agregas el content de la respuesta, sin cambios, como mensaje assistant; agregas un mensaje user con un tool_result por cada tool_use, aunque la herramienta haya fallado; envías otra vez las mismas tools; y si la respuesta vuelve a traer stop_reason: "tool_use", repites. Así se ve un intercambio, resumido:

// Respuesta del modelo (resumida)
{
  "stop_reason": "tool_use",
  "content": [
    { "type": "text", "text": "Busco las tazas." },
    { "type": "tool_use", "id": "toolu_01A", "name": "buscar_producto", "input": { "consulta": "taza" } }
  ]
}

// Tu siguiente mensaje: el resultado, con el mismo id
{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01A", "content": "[{\"sku\":\"TAZA-350\",\"precio\":189,\"disponibles\":12}]" }
  ]
}

El tool_use_id es lo que une cada resultado con su petición. Este es el ciclo completo en TypeScript, el mismo que pasó las pruebas:

const MAX_VUELTAS = 6;

export async function conversar(client: Anthropic, pregunta: string, carrito: Carrito) {
  const messages: Anthropic.MessageParam[] = [{ role: "user", content: pregunta }];

  for (let vuelta = 0; vuelta < MAX_VUELTAS; vuelta++) {
    const res = await client.messages.create({
      model: "claude-opus-5-5",
      max_tokens: 16000,
      system: SYSTEM,
      tools,
      messages,
    });

    if (res.stop_reason !== "tool_use") {
      // end_turn is the normal answer; refusal or max_tokens go back to the caller.
      const texto = res.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("\n");
      return { texto, stop: res.stop_reason, messages };
    }

    messages.push({ role: "assistant", content: res.content }); // unchanged, thinking blocks included
    const resultados: Anthropic.ToolResultBlockParam[] = [];
    for (const bloque of res.content) {
      if (bloque.type !== "tool_use") continue;
      try {
        const salida = ejecutar(bloque.name, bloque.input, carrito);
        resultados.push({ type: "tool_result", tool_use_id: bloque.id, content: salida });
      } catch (err) {
        if (!(err instanceof ToolError)) console.error(bloque.name, err); // log the real cause, don't send it
        const mensaje = err instanceof ToolError ? err.message : "Error interno de la tienda. Intenta más tarde.";
        resultados.push({ type: "tool_result", tool_use_id: bloque.id, content: mensaje, is_error: true });
      }
    }
    messages.push({ role: "user", content: resultados }); // every result, in one message
  }
  throw new Error(`Sin respuesta final después de ${MAX_VUELTAS} vueltas.`);
}
  1. conversar recibe el cliente, la pregunta y el carrito de la sesión. El carrito nunca viaja como argumento del modelo: lo pone tu servidor.
  2. El for limita las vueltas a seis. Sin límite, un modelo que reintenta una herramienta rota puede quedarse en el ciclo y gastar tokens.
  3. client.messages.create manda el modelo (claude-opus-5-5), el system, las tools y todo el historial. La API no guarda la conversación: la reenvías completa.
  4. Si stop_reason no es tool_use, la respuesta terminó: con end_turn es la respuesta normal; con refusal o max_tokens la regresas para que quien llama decida.
  5. El content del asistente entra al historial tal cual, con sus bloques de texto, de razonamiento y de herramientas.
  6. El for...of recorre los bloques: el modelo puede pedir varias herramientas en una sola respuesta, por ejemplo agregar al carrito y calcular el envío.
  7. Cada resultado lleva el tool_use_id de su bloque. Los errores van como resultado con is_error: true, no se omiten.
  8. Todos los resultados van juntos en un solo mensaje user, al final de la vuelta.
el ciclo de function calling: el modelo pide, tu código ejecutatu códigoAPI de Claude1 · messages + tools2 · stop_reason "tool_use" + tool_use4 · tool_result con su tool_use_id5 · stop_reason "end_turn" + texto3 · tu código ejecuta buscar_producto()el modelo no ejecuta nada: devuelve una peticiónsi la respuesta vuelve a ser tool_use, repite los pasos 2 a 4

Desliza la figura para verla completa

Por defecto el modelo decide si llama una herramienta o contesta directo. Eso lo controla tool_choice, y en los modelos nuevos cambió:

tool_choiceQué haceClaude Opus 5.5
{"type": "auto"}El modelo decide; es el valor por defecto con toolsSí
{"type": "none"}No usa herramientasSí
{"type": "any"}Obliga a usar alguna herramientaNo: error 400
{"type": "tool", "name": "..."}Obliga a usar esa herramientaNo: error 400

Según la página de definir herramientas, forzar con any o tool devuelve 400 en Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2 y 5.1 y Claude Mythos 5.2 y 5.1; Claude Opus 5 y modelos anteriores lo aceptan. La alternativa que propone es auto con strict: true e instrucciones en el prompt. Con auto también puedes poner disable_parallel_tool_use: true para que pida como máximo una herramienta por respuesta.

Manejo de errores

Hay tres tipos de error y cada uno se maneja distinto. El primero es el que el modelo puede arreglar: un sku que no existe, una cantidad fuera de rango, un código postal de cuatro dígitos. Ese vuelve como tool_result con is_error: true y un mensaje que diga qué falló y qué hacer, como pide la documentación de manejo de llamadas: no "falló", sino "El sku INVENTADO-1 no existe. Usa buscar_producto para obtenerlo.". El modelo puede volver a llamar la herramienta con la entrada corregida, y por eso el ciclo tiene un tope de vueltas.

El segundo es un fallo tuyo: la base de datos no responde o hay un bug. Al modelo le mandas un mensaje genérico con is_error: true y el detalle real va a tus logs. Un stack trace en el tool_result no le sirve al modelo y puede terminar en la respuesta al cliente.

El tercero es de formato y lo devuelve la API como 400. Los bloques tool_result tienen que ir en el mensaje que sigue al del tool_use, sin mensajes en medio, y van primero en el arreglo content; si agregas texto, va después. Si falta un resultado verás un error como "tool_use ids were found without tool_result blocks immediately after". Los errores de red, de límite (429) o del servidor los reintenta el SDK: por defecto maxRetries es 2, y si se agotan lanza errores con tipo, como Anthropic.RateLimitError.

Validar lo que pide el modelo

En los tipos del SDK, input es unknown, y así hay que tratarlo: como entrada de un usuario. El modo estricto garantiza la forma, pero no las reglas de tu negocio. Un sku con formato perfecto puede no existir, y un entero válido puede ser 50 cuando solo quedan 3. Este es el caso de agregar_al_carrito dentro de la función que ejecuta las herramientas:

// inside ejecutar(nombre, input, carrito), after: const args = campos(input);
case "agregar_al_carrito": {
  const producto = CATALOGO.find((p) => p.sku === args.sku);
  if (!producto) throw new ToolError(`El sku ${String(args.sku)} no existe. Usa buscar_producto para obtenerlo.`);
  const cantidad = args.cantidad;
  if (typeof cantidad !== "number" || !Number.isInteger(cantidad) || cantidad < 1 || cantidad > MAX_POR_PRODUCTO) {
    throw new ToolError(`La cantidad debe ser un entero de 1 a ${MAX_POR_PRODUCTO}.`);
  }
  const total = (carrito.get(producto.sku) ?? 0) + cantidad;
  if (total > producto.stock) throw new ToolError(`Solo hay ${producto.stock} unidades de ${producto.sku}.`);
  carrito.set(producto.sku, total);
  return JSON.stringify({ sku: producto.sku, cantidad: total, subtotal: subtotal(carrito) });
}
  1. Busca el producto en el catálogo con el sku que mandó el modelo. Si no existe, el error le dice cómo conseguir uno real.
  2. Comprueba que la cantidad sea un entero de 1 a 10, el límite que el esquema estricto no puede expresar.
  3. Suma lo que ya había en el carrito y lo compara con el stock, para que dos llamadas de 8 no metan 16 unidades de algo que tiene 12.
  4. Guarda la cantidad y devuelve el subtotal calculado con el precio del catálogo, nunca con un precio que venga del modelo.
quién hace qué en una llamada a una herramientapasomodelotu códigoelegir qué herramienta llamarescribir la entrada (sku, cantidad)comprobar que el sku existe y hay stockponer el precio y el totalejecutar la función y guardar el carritoleer tool_result y contestar al clientecobrar no es una herramienta: el cliente paga en el checkoutel modelo decide y escribe; tu código compruebaprecios, stock y carrito salen de tu base de datos, no del modelo

Desliza la figura para verla completa

Fuera del código de cada herramienta, cuatro reglas de diseño. Primero, no aceptes del modelo nada que tu servidor ya sabe: precio, descuento, identificador del carrito o del cliente salen de la sesión y de la base de datos. Segundo, no le des herramientas que cobren o confirmen pedidos; el cliente paga en el checkout, con un clic suyo. Tercero, trata como no confiable lo que devuelven tus herramientas si viene de terceros, como reseñas o descripciones de proveedores: Anthropic advierte que ese contenido puede traer instrucciones escondidas y recomienda mantenerlo dentro de los bloques tool_result. Cuarto, revisar el stock al agregar no lo aparta: si dos personas compran la última unidad, el problema es el de la sobreventa de inventario, y se resuelve al pagar. Si el asistente es público, ponle además un límite de peticiones por sesión.

Errores comunes

  • Descripciones de una línea. "Agrega al carrito" no dice de dónde sale el sku ni el rango de la cantidad, y el modelo lo adivina.
  • Confiar en strict para las reglas de negocio. Garantiza tipos y campos, no que el producto exista ni que haya stock.
  • Poner minimum o maximum en un esquema estricto. La API responde 400; el límite va en tu código.
  • Mandar los resultados en varios mensajes o con texto antes. Todos los tool_result van juntos en el siguiente mensaje user, primero.
  • Omitir el resultado de una herramienta que falló. Cada tool_use necesita su tool_result, con is_error: true si falló.
  • Usar tool_choice: any en Claude Opus 5.5. Devuelve 400. Usa auto y dilo en el prompt.
  • Un ciclo sin tope. Ponle un número máximo de vueltas.

Preguntas frecuentes

¿Function calling y tool use son lo mismo?

Sí. Anthropic usa "tool use" y dice que también se le llama function calling. Otras APIs usan roles especiales como tool o function; en la de Claude, los bloques tool_use y tool_result viajan dentro de los mensajes assistant y user.

¿Puedo obligar al modelo a llamar una herramienta?

Depende del modelo. En Claude Opus 5 y anteriores sí, con tool_choice en any o tool. En Claude Opus 5.5, Sonnet 5.5 y los Fable y Mythos 5.1 y 5.2 eso devuelve 400: usa auto, pide la herramienta en el prompt y revisa si llegó un bloque tool_use.

¿Tengo que escribir el ciclo a mano?

No. El SDK trae un tool runner que ejecuta tus funciones y manda los resultados por ti. Escribirlo a mano una vez sirve para entender qué pasa y para controlar límites, logs y errores a tu manera; el ciclo de arriba ocupa unas 40 líneas.

¿Cuánto cuestan las herramientas en tokens?

Las definiciones, los bloques tool_use y los tool_result cuentan como tokens normales. Además, al mandar tools la API agrega un prompt de sistema propio: según la documentación, 286 tokens en Claude Opus 5.5 con auto o none. Descripciones largas cuestan algo más, pero son lo que más mejora las llamadas.

Checklist

  • Cada herramienta tiene un nombre válido y una descripción de tres o cuatro frases.
  • Los esquemas llevan strict: true, required y additionalProperties: false.
  • Los límites numéricos están en la descripción y en tu código, no en el esquema.
  • El content del asistente vuelve al historial sin cambios.
  • Cada tool_use recibe un tool_result con su id, todos en un solo mensaje.
  • Los errores corregibles van con is_error: true y un mensaje que dice qué hacer.
  • El ciclo tiene un tope de vueltas y maneja refusal y max_tokens.
  • Precio, carrito y cliente salen de tu servidor, nunca del modelo.
  • Ninguna herramienta cobra ni confirma pedidos.

Con esto el modelo puede operar el carrito sin tocar nada que no deba. Si después quieres que conteste dudas con tus políticas de envío y devoluciones, el siguiente paso es darle tus documentos con RAG.

¿Viste esto en Instagram? Comenta TOOLS en el Reel y te mando la guía.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 19 de noviembre de 2026

← Blog