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 ciclo agéntico y cuándo el uso de herramientas es el enfoque correcto. Para obtener orientación práctica, comienza con el tutorial o la guía de implementación.



El contrato del 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í mismo. Emite una solicitud estructurada, tu código (o los servidores de Anthropic) ejecuta 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 invocas. 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: definir el esquema, manejar el callback, devolver un resultado. La diferencia es que quien llama desde el otro lado es un modelo de lenguaje que elige qué función invocar en función de 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 una de tres categorías, y la categoría determina de qué es responsable tu aplicación.



Herramientas definidas por el usuario (ejecutadas en el cliente)

Tú escribes el esquema, tú ejecutas el código, tú devuelves los resultados. Este es el caso principal: la gran mayoría del tráfico de uso de herramientas corresponde a herramientas definidas por el usuario que invocan 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 en el cliente)

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

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 incorporados en el entrenamiento. Claude ha sido optimizado con 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 errores con más elegancia que con una herramienta personalizada que haga lo mismo. El esquema es la interfaz que el modelo ya espera.



Herramientas ejecutadas en 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 se encarga de todo lo demás. Nunca construyes un bloque tool_result para estas herramientas. Cuando un turno llama únicamente a herramientas de servidor, el ciclo del lado del servidor ejecuta la operación y envía la salida de vuelta al modelo antes de que la respuesta te llegue, a menos que el ciclo se detenga antes de terminar, lo más habitual porque se pausa.

La respuesta que recibes contiene bloques server_tool_use que muestran qué se ejecutó y qué se devolvió. En el caso común, la ejecución ya está completa cuando los ves, y el trabajo de tu aplicación es habilitar la herramienta y leer la respuesta final en lugar de participar en el ciclo de ejecución; las principales excepciones son un ciclo pausado (pause_turn) y un turno que también llama a una herramienta de cliente.



El ciclo agéntico (herramientas de cliente)

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

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

1. Envía una solicitud con tu arreglo 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 así: mientras stop_reason == "tool_use", ejecuta las herramientas y continúa la conversación. El ciclo 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 conocer la mecánica de construir solicitudes, manejar llamadas a herramientas en paralelo y formatear resultados, consulta Manejar llamadas a herramientas.



El ciclo del lado del servidor

Las herramientas ejecutadas en el servidor ejecutan su propio ciclo 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 regrese 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 ciclo interno tiene un límite de iteraciones. Si el modelo sigue iterando cuando alcanza el límite, la respuesta regresa 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 permitir que el modelo continúe donde lo dejó. Consulta Herramientas de servidor para ver el patrón de continuación.

El ciclo también te devuelve el control antes de que se ejecute una herramienta de servidor si Claude llama a esa herramienta de servidor y a una herramienta de cliente en el mismo grupo de llamadas a herramientas en paralelo. La respuesta entonces regresa con stop_reason: "tool_use" y un bloque server_tool_use que aún no tiene bloque de resultado; la API lo ejecuta después de que devuelvas los resultados de la herramienta de cliente. Consulta Motivos de parada y respaldo para conocer el contrato exacto.



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 realizarlas.
• Datos actualizados 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 texto libre que casualmente contiene 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 herramienta. Analizar texto libre para recuperar una 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 con su entrenamiento. La generación de resúmenes, la traducción y las preguntas de conocimiento general no necesitan un viaje de ida y vuelta de herramienta.
• La interacción es una pregunta y respuesta de un solo turno sin efectos secundarios. Si no hay nada que ejecutar, no hay nada que una herramienta pueda hacer.
• La "latency" (latencia) de la llamada a herramienta dominaría una respuesta trivial. Cada llamada a herramienta es al menos un viaje de ida y vuelta adicional; para tareas ligeras, la sobrecarga puede superar el trabajo en sí.



Elegir entre enfoques



Próximos pasos