Tool Runner (SDK)

Tool Runner maneja el bucle agentico, el envolvimiento de errores y la seguridad de tipos para que no tengas que hacerlo. Usa el bucle manual solo cuando necesites aprobación humana en el bucle, registro personalizado o ejecución condicional. Disponible en los SDKs de Python, TypeScript y Ruby.

El ejecutor de herramientas proporciona una solución lista para usar para ejecutar herramientas con Claude. En lugar de manejar manualmente las llamadas de herramientas, los resultados de herramientas y la gestión de conversaciones, el ejecutor de herramientas automáticamente:

• Ejecuta herramientas cuando Claude las llama
• Maneja el ciclo de solicitud/respuesta
• Gestiona el estado de la conversación
• Proporciona seguridad de tipos y validación

Usa el ejecutor de herramientas para la mayoría de las implementaciones de uso de herramientas.

Uso básico

Define herramientas usando los ayudantes del SDK, luego usa el ejecutor de herramientas para ejecutarlas.

La función de herramienta debe devolver un bloque de contenido o una matriz de bloques de contenido, incluyendo texto, imágenes o bloques de documentos. Esto permite que las herramientas devuelvan respuestas ricas y multimodales. Las cadenas devueltas se convertirán en un bloque de contenido de texto. Si deseas devolver un objeto JSON estructurado a Claude, codifícalo como una cadena JSON antes de devolverlo. Los números, booleanos u otros primitivos que no sean cadenas también deben convertirse a cadenas.

Iterando sobre el ejecutor de herramientas

El ejecutor de herramientas es iterable y produce mensajes de Claude. Esto a menudo se denomina "bucle de llamada de herramienta". En cada iteración, el ejecutor verifica si Claude solicitó un uso de herramienta. Si es así, llama a la herramienta y envía el resultado a Claude automáticamente, luego produce el siguiente mensaje de Claude para continuar tu bucle.

Puedes terminar el bucle en cualquier iteración con una declaración break. El ejecutor continuará en bucle hasta que Claude devuelva un mensaje sin un uso de herramienta.

Si no necesitas mensajes intermedios, puedes obtener el mensaje final directamente:

Uso avanzado

Dentro del bucle, puedes personalizar completamente la siguiente solicitud del ejecutor de herramientas a la API de Mensajes. El ejecutor automáticamente añade resultados de herramientas al historial de mensajes, por lo que no necesitas gestionarlos manualmente. Opcionalmente puedes inspeccionar el resultado de la herramienta para registro o depuración, y modificar los parámetros de solicitud antes de la siguiente llamada a la API.

Depuración de la ejecución de herramientas

Cuando una herramienta lanza una excepción, el ejecutor de herramientas la captura y devuelve el error a Claude como un resultado de herramienta con is_error: true. Por defecto, solo se incluye el mensaje de excepción, no el rastreo de pila completo.

Para ver rastreos de pila completos e información de depuración, establece la variable de entorno ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Cuando está habilitado, el SDK registra detalles completos de excepciones (usando el módulo logging de Python, la consola en TypeScript, o el registrador de Ruby), incluyendo el rastreo de pila completo cuando una herramienta falla.

Interceptando errores de herramientas

Por defecto, los errores de herramientas se devuelven a Claude, que puede responder apropiadamente. Sin embargo, es posible que desees detectar errores y manejarlos de manera diferente, por ejemplo, para detener la ejecución temprano o implementar manejo de errores personalizado.

Usa el método de respuesta de herramienta para interceptar resultados de herramientas y verificar errores antes de que se envíen a Claude:

Modificando resultados de herramientas

Puedes modificar resultados de herramientas antes de que se devuelvan a Claude. Esto es útil para añadir metadatos como cache_control para habilitar almacenamiento en caché de solicitudes en resultados de herramientas, o para transformar la salida de la herramienta.

Usa el método de respuesta de herramienta para obtener el resultado de la herramienta, luego modifícalo antes de que el ejecutor continúe. Si explícitamente añades el resultado modificado o lo mutas en su lugar depende del SDK; ver los comentarios de código en cada pestaña.

Transmisión en directo

Habilita la transmisión en directo para recibir eventos a medida que llegan. Cada iteración produce un objeto de transmisión que puedes iterar para eventos.

Próximos pasos

• Para control manual sobre el bucle de llamada de herramienta, ver Manejar llamadas de herramientas.
• Para ejecutar múltiples herramientas concurrentemente, ver Uso de herramientas en paralelo.
• Para el flujo de trabajo completo de uso de herramientas, ver Definir herramientas.