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)
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" },
},
),
];
herramientadevuelve el objeto que espera la API:name,description,stricteinput_schema. El tipoAnthropic.Tooldel SDK revisa que la forma sea correcta.strict: trueactiva el modo estricto, que obliga a que elinputcumpla el esquema siempre: tipos correctos, campos requeridos presentes y un nombre de herramienta válido.required: Object.keys(properties)marca todos los campos como obligatorios yadditionalProperties: falseimpide campos extra, como un precio que nadie pidió. El modo estricto exige esefalse.- 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. - La descripción dice qué hace, de dónde sale el
sku(debuscar_producto), el rango de la cantidad, qué pasa sin stock y que el precio no es una entrada. - Las propiedades definen dos campos:
skucomo texto ycantidadcomo 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.
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.`);
}
conversarrecibe el cliente, la pregunta y el carrito de la sesión. El carrito nunca viaja como argumento del modelo: lo pone tu servidor.- El
forlimita las vueltas a seis. Sin límite, un modelo que reintenta una herramienta rota puede quedarse en el ciclo y gastar tokens. client.messages.createmanda el modelo (claude-opus-5-5), elsystem, lastoolsy todo el historial. La API no guarda la conversación: la reenvías completa.- Si
stop_reasonno estool_use, la respuesta terminó: conend_turnes la respuesta normal; conrefusalomax_tokensla regresas para que quien llama decida. - El
contentdel asistente entra al historial tal cual, con sus bloques de texto, de razonamiento y de herramientas. - El
for...ofrecorre los bloques: el modelo puede pedir varias herramientas en una sola respuesta, por ejemplo agregar al carrito y calcular el envío. - Cada resultado lleva el
tool_use_idde su bloque. Los errores van como resultado conis_error: true, no se omiten. - Todos los resultados van juntos en un solo mensaje
user, al final de la vuelta.
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_choice | Qué hace | Claude Opus 5.5 |
|---|---|---|
{"type": "auto"} | El modelo decide; es el valor por defecto con tools | Sí |
{"type": "none"} | No usa herramientas | Sí |
{"type": "any"} | Obliga a usar alguna herramienta | No: error 400 |
{"type": "tool", "name": "..."} | Obliga a usar esa herramienta | No: 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) });
}
- Busca el producto en el catálogo con el
skuque mandó el modelo. Si no existe, el error le dice cómo conseguir uno real. - Comprueba que la cantidad sea un entero de 1 a 10, el límite que el esquema estricto no puede expresar.
- 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.
- Guarda la cantidad y devuelve el subtotal calculado con el precio del catálogo, nunca con un precio que venga 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
skuni el rango de la cantidad, y el modelo lo adivina. - Confiar en
strictpara las reglas de negocio. Garantiza tipos y campos, no que el producto exista ni que haya stock. - Poner
minimumomaximumen 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_resultvan juntos en el siguiente mensajeuser, primero. - Omitir el resultado de una herramienta que falló. Cada
tool_usenecesita sutool_result, conis_error: truesi falló. - Usar
tool_choice: anyen Claude Opus 5.5. Devuelve 400. Usaautoy 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,requiredyadditionalProperties: false. - Los límites numéricos están en la descripción y en tu código, no en el esquema.
- El
contentdel asistente vuelve al historial sin cambios. - Cada
tool_userecibe untool_resultcon su id, todos en un solo mensaje. - Los errores corregibles van con
is_error: truey un mensaje que dice qué hacer. - El ciclo tiene un tope de vueltas y maneja
refusalymax_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

Publicado el 19 de noviembre de 2026