Cómo funciona el uso de herramientas

Esta página explica los conceptos detrás del uso de herramientas: dónde se ejecutan las herramientas, cómo funciona el bucle agéntico y cuándo el uso de herramientas es el enfoque correcto. Para orientación práctica, comienza con el tutorial o la guía de implementación.

El contrato de uso de herramientas

El uso de herramientas es un contrato entre tu aplicación y el modelo. Tú especificas qué operaciones están disponibles y qué forma tienen sus entradas y salidas; Claude decide cuándo y cómo llamarlas. El modelo nunca ejecuta nada por sí solo. Emite una solicitud estructurada, tu código (o los servidores de Anthropic) ejecuta la operación, y el resultado vuelve a fluir hacia la conversación.

Este contrato hace que el modelo se comporte menos como un generador de texto y más como una función que llamas. Los ingenieros con experiencia en APIs clásicas pueden integrar el uso de herramientas de la misma manera que lo harían con cualquier otra interfaz tipada: define el esquema, maneja el callback, devuelve un resultado. La diferencia es que quien llama al otro lado es un modelo de lenguaje que elige qué función invocar según la conversación.

Dónde se ejecutan las herramientas

El eje principal en el que difieren las herramientas es dónde se ejecuta el código. Cada herramienta cae en uno de tres grupos, y el grupo determina de qué es responsable tu aplicación.

Herramientas definidas por el usuario (ejecutadas por el cliente)

Tú escribes el esquema, tú ejecutas el código, tú devuelves los resultados. Este es el evento principal: la gran mayoría del tráfico de uso de herramientas son herramientas definidas por el usuario que llaman a lógica específica de la aplicación.

Cuando Claude decide usar una de tus herramientas, la respuesta de la API contiene un bloque tool_use con el nombre de la herramienta y un objeto JSON de argumentos. Tu aplicación extrae esos argumentos, ejecuta la operación (una consulta a la base de datos, una llamada HTTP, una escritura de archivo, lo que sea que haga la herramienta), y envía la salida de vuelta en un bloque tool_result en la siguiente solicitud. Claude nunca ve tu implementación; solo ve el esquema que proporcionaste y el resultado que devolviste.

Herramientas con esquema de Anthropic (ejecutadas por el cliente)

Para un puñado de operaciones comunes (ejecutar comandos de shell, editar archivos, controlar un navegador, gestionar memoria de bloc de notas), Anthropic publica el esquema de la herramienta y tu aplicación maneja la ejecución. Las herramientas en esta categoría son bash, text_editor, computer y memory.

El modelo de ejecución es idéntico al de las herramientas definidas por el usuario: la respuesta contiene un bloque tool_use, tu código ejecuta la operación, y envías de vuelta un tool_result. La razón para usar una herramienta con esquema de Anthropic en lugar de definir tu propio equivalente es que estos esquemas están entrenados. Claude ha sido optimizado en miles de trayectorias exitosas que usan exactamente estas firmas de herramientas, por lo que las llama de manera más confiable y se recupera de los errores con más gracia que con una herramienta personalizada que haga lo mismo. El esquema es la interfaz que el modelo ya espera.

Herramientas ejecutadas por el servidor

Para web_search, web_fetch, code_execution y tool_search, Anthropic ejecuta el código. Tú habilitas la herramienta en tu solicitud y el servidor maneja todo lo demás. Nunca construyes un bloque tool_result para estas herramientas porque el bucle del lado del servidor ejecuta la operación y devuelve la salida al modelo antes de que la respuesta te llegue.

La respuesta que recibes contiene bloques server_tool_use que muestran qué se ejecutó y qué devolvió, pero para cuando los ves, la ejecución ya está completa. El trabajo de tu aplicación es habilitar la herramienta y leer la respuesta final, no participar en el bucle de ejecución.

El bucle agéntico (herramientas del cliente)

Las herramientas ejecutadas por el cliente (tanto las definidas por el usuario como las de esquema de Anthropic) requieren que tu aplicación conduzca un bucle. El modelo no puede ejecutar tu código, por lo que cada llamada a una herramienta es un viaje de ida y vuelta: el modelo pregunta, tú ejecutas, tú informas, el modelo continúa.

La forma canónica es un bucle while con clave en stop_reason:

1. Envía una solicitud con tu array tools y el mensaje del usuario.
2. Claude responde con stop_reason: "tool_use" y uno o más bloques tool_use.
3. Ejecuta cada herramienta. Formatea las salidas como bloques tool_result.
4. Envía una nueva solicitud que contenga los mensajes originales, la respuesta del asistente y un mensaje de usuario con los bloques tool_result.
5. Repite desde el paso 2 mientras stop_reason sea "tool_use".

En la práctica esto se lee como: mientras stop_reason == "tool_use", ejecuta las herramientas y continúa la conversación. El bucle termina con cualquier otro motivo de parada ("end_turn", "max_tokens", "stop_sequence" o "refusal"), lo que significa que Claude ha producido una respuesta final o se ha detenido por otra razón que tu aplicación debe manejar.

Para la mecánica de construcción de solicitudes, manejo de llamadas paralelas a herramientas y formateo de resultados, consulta Manejar llamadas a herramientas.

El bucle del lado del servidor

Las herramientas ejecutadas por el servidor ejecutan su propio bucle dentro de la infraestructura de Anthropic. Una sola solicitud de tu aplicación podría desencadenar varias búsquedas web o ejecuciones de código antes de que llegue una respuesta. El modelo busca, lee resultados, decide buscar de nuevo e itera hasta que tiene lo que necesita, todo sin que tu aplicación participe.

Este bucle interno tiene un límite de iteraciones. Si el modelo sigue iterando cuando alcanza el límite, la respuesta vuelve con stop_reason: "pause_turn" en lugar de "end_turn". Un turno pausado significa que el trabajo no está terminado; reenvía la conversación (incluida la respuesta pausada) para que el modelo continúe donde lo dejó. Consulta Herramientas del servidor para el patrón de continuación.

Cuándo usar herramientas (y cuándo no)

El uso de herramientas es adecuado cuando la tarea requiere algo que el modelo no puede hacer solo con texto:

• Acciones con efectos secundarios. Enviar un correo electrónico, escribir un archivo, actualizar un registro. El modelo puede describir estas acciones, pero solo una herramienta puede realizarlas.
• Datos frescos o externos. Precios actuales, el clima de hoy, el contenido de una base de datos. Cualquier cosa fuera de los datos de entrenamiento o específica de tu sistema necesita una herramienta para obtenerla.
• Salidas estructuradas con forma garantizada. Cuando necesitas un objeto JSON con campos específicos en lugar de prosa que resulta contener la información, un esquema de herramienta impone la forma.
• Llamadas a sistemas existentes. Bases de datos, APIs internas, sistemas de archivos. El uso de herramientas es el puente entre las solicitudes en lenguaje natural y los sistemas que las satisfacen.

La señal de que deberías estar usando herramientas: si estás escribiendo una expresión regular para extraer una decisión de la salida del modelo, esa decisión debería haber sido una llamada a una herramienta. Analizar texto de forma libre para recuperar intención estructurada es una señal de que la estructura pertenece al esquema.

El uso de herramientas no es adecuado cuando:

• El modelo puede responder solo con el entrenamiento. La resumización, la traducción y las preguntas de conocimiento general no necesitan un viaje de ida y vuelta con una herramienta.
• La interacción es una pregunta y respuesta de un solo disparo sin efectos secundarios. Si no hay nada que ejecutar, no hay nada que una herramienta pueda hacer.
• La latencia de llamada a herramientas dominaría una respuesta trivial. Cada llamada a una herramienta es al menos un viaje de ida y vuelta adicional; para tareas ligeras, la sobrecarga puede superar el trabajo.

Elegir entre enfoques

Próximos pasos