MessagesHerramientas

Cómo funciona el uso de herramientas

Copy page



Comprende el bucle de uso de herramientas, dónde se ejecutan las herramientas y cuándo usar herramientas en lugar de prosa.

Esta página explica los conceptos detrás del "tool use" (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 una guía práctica, comienza con el tutorial Construye un agente que usa herramientas o la guía Definir herramientas.

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 determina 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 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: 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 llamar basándose en 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 más común: 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 llama a 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 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 escritorio o 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, computer y browser.

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 forma 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 solo a herramientas de servidor, el bucle del lado del servidor ejecuta la operación y alimenta la salida de vuelta al modelo antes de que la respuesta te llegue, a menos que el bucle se detenga antes de terminar, con mayor frecuencia porque hace una pausa.

La respuesta que recibes contiene bloques server_tool_use que muestran qué se ejecutó y qué se obtuvo. 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 bucle de ejecución; las principales excepciones son un bucle en pausa (pause_turn) y un turno que también llama a una herramienta de cliente.

El bucle 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 conduzca un bucle. 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, 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 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 construir solicitudes, manejar llamadas a herramientas en paralelo y formatear resultados, consulta Manejar llamadas a herramientas.

El bucle del lado del servidor

Las herramientas ejecutadas en 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 los resultados, determina si debe buscar de nuevo e itera hasta tener 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 llega con stop_reason: "pause_turn" en lugar de "end_turn". Un turno en pausa significa que el trabajo no ha terminado; vuelve a enviar la conversación (incluida la respuesta en pausa) para que el modelo continúe donde se quedó. Consulta Herramientas de servidor para ver el patrón de continuación.

El bucle 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 llega 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 ver el contrato exacto.

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 a partir de 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 recientes 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 casualmente contenga 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 las solicitudes en lenguaje natural y los sistemas que las satisfacen.

Una señal clara 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 es adecuado cuando:

• El modelo puede responder solo con su entrenamiento. El resumen, 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 única sin efectos secundarios. Si no hay nada que ejecutar, no hay nada que una herramienta pueda hacer.
• La latencia de las llamadas a herramientas 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.

Elegir entre enfoques

Próximos pasos