Tool calling en 40 líneas: el bucle que define a un agente de IA

La idea, en una frase

Un agente de IA no necesita un framework, una base de datos vectorial ni un módulo de planificación. Necesita un bucle: el modelo nunca ejecuta nada; emite un bloque tool_use con un nombre y argumentos en JSON, tu código corre la función real, y vuelve a pegarle el resultado a la conversación. Según la lección 2 de Buttercup (publicada el 15 de septiembre de 2026), esa es la distancia completa entre un modelo que escribe sobre el clima y un programa que sale a comprobarlo.

La consecuencia operativa es enorme: la mayor parte del trabajo duro no es programar el bucle, sino redactar bien las descripciones de las herramientas (son prompts, no documentación) y vigilar el tamaño de cada respuesta, porque todo lo que entra al array se reenvía en cada vuelta.

Las cuatro estaciones del bucle

El artículo lo reduce a un diagrama de cuatro estaciones que se recorre hasta que el modelo responde con texto plano:

🤖 La IA no es solo para leer sobre ella

En la comunidad la aplicamos: automatización, agentes IA y herramientas reales para emprender, no solo para informarte.

👥 Aplicarla en la comunidad

Mensajes: el array con el historial y la lista de herramientas.
Modelo: devuelve texto o un bloque tool_use.
Tu código: ejecuta la función real (fetch, disco, base de datos).
Resultado: un tool_result con el mismo tool_use_id que el modelo emitió.

El "agente terminó" no es un evento mágico: es la condición stop_reason !== "tool_use". Lo demás es marketing. Y el único punto donde algo realmente ocurre es la estación 3, que es tu código, no el modelo.

El código: 40 líneas, en JavaScript y Python

El artículo entrega programas completos y ejecutables. En JavaScript (requiere npm i @anthropic-ai/sdk y una ANTHROPIC_API_KEY):

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();

function getWeather({ city }) {
  const readings = { Paris: "18°C, light rain", Tokyo: "27°C, clear" };
  return readings[city] ?? `no reading for ${city}`;
}

const tools = [{
  name: "get_weather",
  description: "Current weather for one city. Use this for any question " +
               "about temperature, rain, or conditions right now.",
  input_schema: {
    type: "object",
    properties: { city: { type: "string" } },
    required: ["city"],
  },
}];

const messages = [{ role: "user", content: "Do I need an umbrella in Paris?" }];

while (true) {
  const reply = await client.messages.create({
    model: "claude-opus-5", tools, messages,
  });
  messages.push({ role: "assistant", content: reply.content });

  if (reply.stop_reason !== "tool_use") {
    console.log(reply.content.filter(b => b.type === "text").map(b => b.text).join(""));
    break;
  }

  const results = reply.content
    .filter(b => b.type === "tool_use")
    .map(b => ({
      type: "tool_result",
      tool_use_id: b.id,
      content: String(getWeather(b.input)),
    }));

  messages.push({ role: "user", content: results });
}

La versión en Python usa tool_runner y @beta_tool, pero la lógica es idéntica. La rareza que más confunde al principio: los resultados vuelven con role: "user" aunque vengan de tu código. Así está hecho el protocolo.

La trampa de los tokens que nadie te cuenta

Esta es la parte que la mayoría de tutoriales esconde y Buttercup hace explícita con números.

Cada request reenvía todo el array de mensajes. Una corrida de cinco pasos termina con un historial de 4,2k tokens, pero sumando lo que se envió en cada vuelta se pagan 10,3k tokens de input: 2,5× el tamaño de lo que construiste.

Llevado al extremo: una herramienta read_file que devuelve 8k tokens en la vuelta 2 de un agente de 10 pasos se reenvía en las ocho requests siguientes: +64k tokens de input por corrida. A los US$5 por millón de tokens de input que publicó Anthropic para Claude Opus 5 en julio de 2026 (precio confirmado por ZDNet, CNBC y Android Headlines), eso son US$0,32 adicionales por ejecución. Si corres ese agente mil veces al día, ese único read_file mal podado cuesta US$320 diarios.

La regla de oro que rescata la lección: poda el resultado, no el prompt. El prompt se envía una vez. El resultado del tool se reenvía en cada vuelta posterior.

Dos arreglos que ya están a mano:

Devolver menos: rangos de líneas en vez de archivos completos, conteos en vez de dumps, las 20 filas que coinciden en vez de toda la tabla.
Activar cache_control: los prefijos repetidos facturan a ~0,1× la tarifa de input, contra una prima de 1,25× la única vez que se escribe. En la segunda request sobre el mismo prefijo ya estás ganando dinero. Esa es exactamente la palanca que Anthropic introdujo con Claude Opus 5: según ZDNet, en julio de 2026 la nueva versión permite intercambiar herramientas a mitad de conversación sin invalidar el caché del prompt, algo que ningún modelo anterior podía hacer.

Cuatro reglas que te ahorran un fin de semana

El artículo las enumera como checklist y, en conjunto, son la diferencia entre un prototipo y un agente en producción:

Responder a todas las llamadas, incluso si fallan. Si tu función lanza, captura la excepción y devuélvela como tool_result con is_error: true. El modelo lee el error y reintenta. Una respuesta faltante rompe el protocolo en la siguiente request, y eso es lo que produce los stack traces confusos.
Devolver todos los resultados en un solo mensaje. Si el modelo pidió tres herramientas en paralelo, responde con tres tool_result en un único role: "user". Dividirlos en mensajes sucesivos enseña al modelo a dejar de pedir en paralelo, y tu agente se vuelve tres veces más lento sin que los logs acusen a nadie.
Appendear la respuesta completa, no un string rearmado. messages.push({ ..., content: reply.content }). Los bloques que descartes los extrañarás en el siguiente turno, sin error que lo señale.
Poner un tope al bucle. while (true) sirve para una lección; en producción, cuenta las vueltas y corta en 20. Un modelo con una descripción mal leída llama a la herramienta cuarenta veces seguidas, y cada llamada carga todo el array. El contador son cuatro líneas; el límite es la diferencia entre un bug y una factura.

¿Qué significa esto para tu startup?

Si estás construyendo un agente sobre Claude o cualquier API compatible, esta lección te deja tres regalos:

El "agente" no es una librería, es un bucle. Antes de adoptar LangChain, Agno, Vercel AI SDK o el tool_runner de Anthropic, escribe el bucle a mano una vez. Te toma 30 minutos y elimina el 80% de las sorpresas cuando el framework "hace cosas raras" entre turnos. Los hooks entre vueltas (aprobaciones, logs, reescritura de argumentos, contadores propios) son lo único que justifica un runner.
Tu mayor palanca de costo no es el modelo, es el tamaño de las respuestas. Un solo read_file que devuelve 8k tokens sin podar puede multiplicar tu factura por 10× a escala. Audita todas tus herramientas con la pregunta: "¿puedo devolver 100 tokens en vez de 10.000?". Cambia sumarios por conteos, archivos enteros por líneas, JSON dumps por tablas filtradas. Y donde el prefijo se repite (system prompt, definiciones de herramientas, historial de identidad), activa cache_control.
La descripción de la herramienta es tu prompt, no tu documentación. Si el modelo mal-usa una herramienta, la respuesta casi nunca es reentrenar nada: es reescribir una frase. Invierte ahí las horas que pensabas invertir en el framework.

Acción concreta 1: agarra una de las herramientas que ya tienes en producción, mídela con el panel de uso de Anthropic, y pregunta cuántos tokens de input generó en el último día. Si la mediana supera los 2k tokens por llamada y se reusa más de 5 turnos, ya tienes un candidato a podar.

Acción concreta 2: implementa el patrón del artículo en tu propio stack — aunque sea en un script de 40 líneas — y rompelo a propósito. Quita una herramienta del array, pídela igual, y observa cómo el modelo improvisa. Esa media hora te enseña más sobre tool calling que un mes de leer documentación.