Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
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 Define 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 tú 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: definir el esquema, manejar el callback, devolver un resultado. La diferencia es que quien llama del otro lado es un modelo de lenguaje que elige qué función llamar según la conversación.
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.
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 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.
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 maneja 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 tú 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 de lo que lo haría con una herramienta personalizada que hace lo mismo. El esquema es la interfaz que el modelo ya espera.
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 se encarga de todo lo demás. Nunca construyes un bloque tool_result para estas herramientas. Cuando un turno llama solo a herramientas del servidor, el bucle del lado del servidor ejecuta la operación y devuelve la salida al modelo antes de que la respuesta te llegue, a menos que el bucle se detenga antes de terminar, más a menudo porque se 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 para 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 pausado (pause_turn) y un turno que también llama a una herramienta 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 dirija 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 pide, tú ejecutas, tú reportas de vuelta, el modelo continúa.
La forma canónica es un bucle while basado en stop_reason:
tools y el mensaje del usuario.stop_reason: "tool_use" y uno o más bloques tool_use.tool_result.tool_result.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 otra razón 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 debería manejar.
Para la mecánica de construir solicitudes, manejar llamadas a herramientas en paralelo y formatear resultados, consulta Maneja llamadas a herramientas.
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 regrese una respuesta. El modelo busca, lee resultados, determina si debe 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 todavía está 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 (incluyendo la respuesta pausada) para permitir que el modelo continúe donde lo dejó. Consulta Herramientas del servidor para el patrón de continuación.
El bucle también te devuelve el control antes de que se ejecute una herramienta del servidor si Claude llama a esa herramienta del servidor y a una herramienta del 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 del cliente. Consulta Razones de parada y respaldo para el contrato exacto.
El uso de herramientas encaja cuando la tarea requiere algo que el modelo no puede hacer solo a partir de texto:
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 una herramienta. Analizar texto de forma 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:
| Enfoque | Cuándo usarlo | Qué esperar | Más información |
|---|---|---|---|
| Herramientas del cliente definidas por el usuario | Lógica de negocio personalizada, API internas, datos propietarios | Tú manejas la ejecución y el bucle agéntico | Define herramientas |
| Herramientas del cliente con esquema de Anthropic | Operaciones de desarrollo estándar (bash, edición de archivos, control del navegador) | Tú manejas la ejecución; Claude llama a la herramienta de manera confiable porque el esquema está incorporado en el entrenamiento | Referencia de herramientas |
| Herramientas ejecutadas por el servidor | Búsqueda web, sandbox de código, obtención de contenido web | Anthropic maneja la ejecución; tú lees los resultados en lugar de producirlos | Herramientas del servidor |
Construye un agente paso a paso desde una sola llamada a una herramienta hasta producción.
Especificación del esquema, descripciones y tool_choice.
Directorio de herramientas proporcionadas por Anthropic.
Was this page helpful?