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. 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) ejecutan la operación, y el resultado fluye de vuelta a 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 API 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 la devolución de llamada, devuelve un resultado. La diferencia es que quien llama al otro lado es un modelo de lenguaje que elige qué función invocar basándose en la conversación.

Dónde se ejecutan las herramientas

El eje principal a lo largo del cual 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)

Escribes el esquema, ejecutas el código, 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 de base de datos, una llamada HTTP, una escritura de archivo, lo que haga la herramienta), y envía el resultado 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 de 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 devuelves un tool_result. La razón para usar una herramienta de esquema de Anthropic en lugar de definir la tuya propia equivalente es que estos esquemas están entrenados. Claude ha sido optimizado en miles de trayectorias exitosas que usan estas firmas de herramientas exactas, por lo que las llama de manera más confiable y se recupera de errores de manera más elegante que lo haría con una herramienta personalizada que hace 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. 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 alimenta el resultado de vuelta al modelo antes de que la respuesta te llegue.

La respuesta que recibes contiene bloques server_tool_use mostrando qué se ejecutó y qué volvió, pero en el momento en que 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 de cliente)

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

La forma canónica es un bucle while basado 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 los resultados como bloques tool_result.
4. Envía una nueva solicitud que contenga los mensajes originales, la respuesta del asistente, y un mensaje del 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 se cierra en 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 construir solicitudes, manejar llamadas de herramientas paralelas y formatear resultados, consulta Manejar llamadas de herramientas.

El bucle del lado del servidor

Las herramientas ejecutadas por el servidor ejecutan su propio bucle dentro de la infraestructura de Anthropic. Una única solicitud de tu aplicación podría desencadenar varias búsquedas web o ejecuciones de código antes de que vuelva 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 iteración. 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 (incluyendo la respuesta pausada) para permitir que el modelo continúe donde lo dejó. Consulta Herramientas de servidor para el patrón de continuación.

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

El uso de herramientas encaja 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 ejecutarlas.
• 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 simplemente contiene la información, un esquema de herramienta impone la forma.
• Llamar a sistemas existentes. Bases de datos, APIs internas, sistemas de archivos. El uso de herramientas es el puente entre solicitudes en lenguaje natural y los sistemas que las cumplen.

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 de 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 encaja cuando:

• El modelo puede responder solo del entrenamiento. Resumen, traducción y preguntas de conocimiento general no necesitan un viaje de herramienta.
• La interacción es Q&A de una sola vez sin efectos secundarios. Si no hay nada que ejecutar, no hay nada para que una herramienta haga.
• La latencia de llamada de herramienta dominaría una respuesta trivial. Cada llamada de herramienta es al menos un viaje redondo extra; para tareas ligeras la sobrecarga puede exceder el trabajo.

Elegir entre enfoques

Próximos pasos