Cargando

¿Qué es el uso de herramientas?

Lección 58 min
Cargando

¿Qué es el uso de herramientas?

Tus flujos de trabajo existentes dependen de muchas tecnologías diferentes: software de gestión de proyectos, bases de datos, archivos. Claude no puede simplemente verificar estas cosas por sí mismo. En su lugar, depende de herramientas, que le dan a Claude acceso a datos y acciones externos.

Qué es una herramienta

En pocas palabras, una herramienta es una función que defines y expones a Claude. Describes lo que hace y qué entradas toma, y Claude decide cuándo llamarla.

Esto es lo fundamental que debes interiorizar: Claude no ejecuta la herramienta, tu código sí lo hace. El flujo se ve así:

  1. Claude solicita una llamada a la herramienta.
  2. Tu código ejecuta la función.
  3. El resultado vuelve a Claude, y continúa.

Cómo se definen las herramientas

Las herramientas son esquemas JSON con tres partes: un nombre, una descripción y un esquema de entrada. Se las pasas a Claude en el cuerpo de la solicitud como un array tools.

La descripción es lo que Claude lee para decidir si llama a la herramienta. Si escribes una descripción vaga, obtienes un mal uso de herramientas. Esta es la razón número uno por la que los agentes fallan o no toman las herramientas que tienen disponibles. Sé específico.

Así es como se ve la definición de una herramienta:

json
{
  "name": "lookup_building_code",
  "description": "Look up a specific building code section by its identifier. Returns the full text of that code section.",
  "input_schema": {
    "type": "object",
    "properties": {
      "section": {
        "type": "string",
        "description": "The building code section to look up"
      }
    },
    "required": ["section"]
  }
}

Entonces, ¿qué pasa cuando usamos esto? Digamos que le enviamos a un agente un informe de cumplimiento. En el primer turno, Claude responde con stop_reason: "tool_use": esa es nuestra señal. Así es como se ve esa respuesta:

Una respuesta de la API con stop_reason establecido en tool_use, que contiene un bloque de contenido tool_use que nombra la herramienta y la entrada con la que Claude quiere llamarla

Nuestro bucle llama a lookup_building_code con el parámetro que Claude solicitó, y luego devuelve el resultado como un resultado de herramienta: un mensaje de usuario que contiene un bloque tool_result vinculado al id de la llamada a la herramienta:

Un mensaje de usuario que contiene un bloque tool_result con el tool_use_id y el texto del código de construcción consultado como su contenido

Y Claude continúa. En ese punto, podemos seguir llamando a herramientas y devolviendo resultados a Claude hasta que tenga lo que necesita.

Múltiples herramientas: dejar que Claude elija

Una herramienta es útil, pero la parte interesante es darle a Claude múltiples herramientas y observar cómo elige cuál usar, en qué orden.

Imagina este escenario: estás preparando el equipaje para un viaje de tres días a Denver, y quieres tanto el clima de hoy como el pronóstico de los próximos días. Así que declaramos dos herramientas en lugar de una:

typescript
const tools = [
  {
    name: "get_weather",
    description: "Get today's current weather for a city.",
    input_schema: {
      type: "object",
      properties: {
        city: { type: "string", description: "The city to check" }
      },
      required: ["city"]
    }
  },
  {
    name: "get_forecast",
    description: "Get the weather forecast for the next few days for a city.",
    input_schema: {
      type: "object",
      properties: {
        city: { type: "string", description: "The city to check" }
      },
      required: ["city"]
    }
  }
];

El bucle es idéntico a los bucles de agente que ya hemos visto. La única pieza nueva es una función runTool que distribuye según el nombre de la herramienta con una declaración switch: este bloque de código es simplemente donde tu código realmente se ejecuta. También añade dos búsquedas fijas y el mensaje inicial para que puedas ejecutarlo, y usa el client de "Tu primera llamada a la API":

typescript
// Dos búsquedas codificadas. En una app real, estas llamarían a un servicio meteorológico.
const getWeather = (city) => `${city} today: 34F, snow flurries`;
const getForecast = (city) => `${city}, next three days: 38F, 45F, and 52F, sunny`;

const messages = [
  {
    role: "user",
    content:
      "I'm packing for a three-day trip to Denver. What's the weather today and over the next few days?",
  },
];

function runTool(name, input) {
  switch (name) {
    case "get_weather":
      return getWeather(input.city);
    case "get_forecast":
      return getForecast(input.city);
  }
}

while (true) {
  const response = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages,
    tools,
  });

  if (response.stop_reason !== "tool_use") {
    // Claude terminó — esta es la respuesta final
    for (const block of response.content) {
      if (block.type === "text") console.log(block.text);
    }
    break;
  }

  messages.push({ role: "assistant", content: response.content });

  const toolResults = response.content
    .filter((block) => block.type === "tool_use")
    .map((block) => ({
      type: "tool_result",
      tool_use_id: block.id,
      content: runTool(block.name, block.input),
    }));

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

Y ese es todo el patrón. ¿Quieres una tercera herramienta? Añádela al array, añade un caso al switch, y listo.

Ejecuta esto, y verás a Claude llamar a get_weather y luego a get_forecast, a veces en el mismo turno, a veces uno después del otro. Luego responde: empaca capas, espera ráfagas de nieve hoy, y que va calentando durante la semana.

Ahora fíjate en cómo eligió Claude. Leyó las descripciones, relacionó tu prompt con "el clima de hoy" y "los próximos días", y eligió la herramienta correcta para cada uno. Por eso las descripciones de tus herramientas realmente importan.

El ejecutor de herramientas: evita el código repetitivo

Probablemente ya hayas detectado dos señales de alerta en lo que acabamos de escribir:

  • Eso es mucho código para dos búsquedas simples.
  • En una base de código real, no quieres escribir a mano esquemas JSON para cada función que tengas. Es como escribir tu código dos veces.

Ahí es donde entra el ejecutor de herramientas. Se distribuye en beta en los SDKs de Claude: TypeScript, Python, Ruby, C#, Go, Java y PHP. Defines cada herramienta una vez, y el ejecutor gestiona internamente todo el bucle de uso de herramientas / resultado de herramienta.

En TypeScript, el asistente recomendado del ejecutor, betaZodTool(), describe cada herramienta con un esquema corto escrito en Zod, una biblioteca de TypeScript para declarar y validar la forma de los datos. El asistente necesita Zod 3.25.0 o posterior, lo cual obtienes con una instalación nueva:

bash
npm install zod

Tu código se reduce a esto: describe la herramienta, envía el prompt, espera el resultado. Aquí está la misma demostración del clima con dos herramientas, conectada a través del ejecutor de herramientas:

typescript
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";

// Envuelve las mismas dos búsquedas que ejecutamos a mano, cada una con un schema Zod breve
const weatherTool = betaZodTool({
  name: "get_weather",
  description: "Get today's current weather for a city.",
  inputSchema: z.object({
    city: z.string().describe("The city to check"),
  }),
  run: async ({ city }) => getWeather(city),
});

const forecastTool = betaZodTool({
  name: "get_forecast",
  description: "Get the weather forecast for the next few days for a city.",
  inputSchema: z.object({
    city: z.string().describe("The city to check"),
  }),
  run: async ({ city }) => getForecast(city),
});

const runner = client.beta.messages.toolRunner({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content:
        "I'm packing for a three-day trip to Denver. What's the weather today and over the next few days?",
    },
  ],
  tools: [weatherTool, forecastTool],
});

// Espera al runner para obtener el mensaje final tras resolverse todo el ida y vuelta de herramientas
const finalMessage = await runner;
for (const block of finalMessage.content) {
  if (block.type === "text") console.log(block.text);
}

El mismo escenario, con una fracción del código:

  • Sin bucle while, sin switch de stop reason, sin empujar manualmente resultados de herramientas de vuelta a los mensajes: el ejecutor se encarga de todo eso.
  • Sin esquemas JSON escritos a mano, solo un esquema Zod corto por herramienta, que también valida la entrada que envía Claude.
  • Cada función run envuelve la misma búsqueda que ejecutamos a mano hace un momento.
  • Esperar al ejecutor devuelve el mensaje final del asistente una vez que todo se ha resuelto.

Ejecútalo, y obtienes la misma respuesta.

Las herramientas reales envuelven tu código existente

En la vida real, tus herramientas no serían datos de clima fijos. Envolverían funciones reales que ya tienes en tu aplicación.

Toma un agente de revisión de cumplimiento: sus herramientas son envoltorios delgados alrededor de las funciones lookup_building_code y search_building_code que ya existen en la base de código. Con el ejecutor de herramientas, envuelves cada una de esas funciones en una definición de herramienta corta con su propio esquema Zod, y el agente cita secciones específicas del código en cada hallazgo que escribe:

Una aplicación de revisión de cumplimiento que muestra un informe estructural junto con los hallazgos del agente, donde cada elemento marcado cita la sección específica del código de construcción que verificó

Resumen

  • Las herramientas le dan a Claude acceso a tus sistemas. Una herramienta es una función que defines y expones; Claude decide cuándo llamarla, y tu código la ejecuta.
  • Las herramientas son esquemas JSON con un nombre, una descripción y un esquema de entrada, pasados en la solicitud como un array tools.
  • Escribe descripciones específicas. Las descripciones vagas son la razón número uno por la que los agentes fallan.
  • stop_reason: "tool_use" es tu señal para ejecutar la herramienta y devolver el resultado como un resultado de herramienta.
  • Para múltiples herramientas, distribuye según el nombre de la herramienta. Añadir una herramienta significa añadirla al array y añadir un caso.
  • El ejecutor de herramientas del SDK (disponible en beta en todos los SDKs de Claude) gestiona todo el bucle, y en TypeScript cada herramienta es una definición corta con un esquema Zod. O puedes ejecutar el bucle tú mismo.
  • Tú ejecutas, o delegas el bucle. En el extremo más lejano de ese espectro, los agentes gestionados delegan el agente completo a Anthropic.