Manejo de Solicitudes tool_use y Devolución de Bloques tool_result

Ejecuta la herramienta solicitada y devuelve un bloque de contenido tool_result coincidente.

Resumen

Cuando stop_reason en un Message regresa como "tool_use", Claude se ha pausado a mitad de turno para pedirle a tu código que ejecute algo. Aún no ha respondido al usuario; está esperando por ti.

Tu trabajo es un traspaso fijo de cinco pasos: encontrar los bloques tool_use en response.content, ejecutar la función Python correspondiente con block.input, añadir response.content del asistente a messages de forma literal, envolver la salida de cada herramienta en un bloque tool_result indexado por tool_use_id, y llamar a messages.create nuevamente.

Esta página trata sobre cómo realizar ese traspaso de forma correcta y defensiva: leer block.input como el diccionario analizado que te da el SDK (nunca volviendo a analizar o buscando coincidencias de cadenas en JSON crudo), manejar cada bloque tool_use en un turno (no solo el primero), y reportar fallos con is_error en lugar de dejar que una excepción mate la solicitud.

Si logras este bucle correctamente una vez, se convertirá en una función pequeña y reutilizable que cada solicitud que use herramientas en tu aplicación podrá llamar.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

if response.stop_reason == "tool_use":
    messages.append({"role": "assistant", "content": response.content})
 
    tool_results = []
    for block in response.content:
        if block.type != "tool_use":
            continue
        try:
            result = execute_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
        except Exception as e:
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": str(e),
                "is_error": True,
            })
 
    messages.append({"role": "user", "content": tool_results})
 
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )

Cuándo recurrir a esto:

• Cualquier solicitud en la que hayas pasado una lista tools no vacía y necesites honrar realmente una respuesta tool_use.
• Turnos en los que Claude podría solicitar más de una herramienta a la vez; el bucle anterior las maneja todas antes de responder.
• En cualquier lugar donde una llamada a herramienta pueda fallar plausiblemente (una API inestable, una búsqueda incorrecta) y quieras que Claude vea el fallo en lugar de que tu proceso se bloquee.
• Construir una utilidad general de "ejecutar esta conversación hasta que Claude deje de pedir herramientas" que reutilizarás en todos los puntos de conexión.

Ejemplo de Trabajo

import anthropic
 
client = anthropic.Anthropic()
 
weather_tool = {
    "name": "get_weather",
    "description": "Obtener el clima actual para una ubicación. Llama a esto cuando el usuario pregunte sobre las condiciones actuales.",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "Ciudad y estado, por ejemplo, San Francisco, CA",
            }
        },
        "required": ["location"],
    },
}
 
stock_price_tool = {
    "name": "get_stock_price",
    "description": "Obtener el último precio para un símbolo de ticker de acciones.",
    "input_schema": {
        "type": "object",
        "properties": {
            "ticker": {
                "type": "string",
                "description": "Símbolo de ticker de acciones, por ejemplo, AAPL",
            }
        },
        "required": ["ticker"],
    },
}
 
tools = [weather_tool, stock_price_tool]
 
 
def get_weather(location: str) -> str:
    # Reemplaza con una llamada real a la API del clima.
    return f"72F y soleado en {location}"
 
 
def get_stock_price(ticker: str) -> str:
    # Reemplaza con una llamada real a la API de datos del mercado.
    if not ticker.isalpha():
        raise ValueError(f"'{ticker}' no es un símbolo de ticker válido")
    return f"{ticker.upper()} cotiza a $184.32"
 
 
TOOL_FUNCTIONS = {
    "get_weather": get_weather,
    "get_stock_price": get_stock_price,
}
 
 
def execute_tool(name: str, tool_input: dict) -> str:
    if name not in TOOL_FUNCTIONS:
        raise ValueError(f"Herramienta desconocida: {name}")
    return TOOL_FUNCTIONS[name](**tool_input)
 
 
def run_turn(messages: list) -> list:
    """Envía mensajes, maneja cualquier ronda de tool_use, devuelve la lista actualizada."""
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
 
    while response.stop_reason == "tool_use":
        messages.append({"role": "assistant", "content": response.content})
 
        tool_results = []
        for block in response.content:
            if block.type != "tool_use":
                continue
            try:
                result = execute_tool(block.name, block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result,
                })
            except Exception as e:
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": str(e),
                    "is_error": True,
                })
 
        messages.append({"role": "user", "content": tool_results})
 
        response = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=1024,
            tools=tools,
            messages=messages,
        )
 
    messages.append({"role": "assistant", "content": response.content})
    return messages
 
 
if __name__ == "__main__":
    conversation = [
        {
            "role": "user",
            "content": "¿Cuál es el clima en Austin, TX, y a cuánto cotiza AAPL?",
        }
    ]
 
    conversation = run_turn(conversation)
    final_text = next(
        block.text for block in conversation[-1]["content"] if block.type == "text"
    )
    print(final_text)

Lo que esto demuestra:

• Un bucle while response.stop_reason == "tool_use":, para que el manejador siga resolviendo llamadas a herramientas hasta que Claude produzca una respuesta de texto final, no solo una ronda.
• Una tabla de despacho (TOOL_FUNCTIONS) que mapea block.name a una función Python real, con execute_tool lanzando un error limpio para cualquier nombre que no reconozca.
• Dos herramientas solicitadas en la misma pregunta del usuario, ambas resueltas y devueltas juntas en un único mensaje de user que contiene tool_result.
• Un try/except alrededor de cada ejecución de herramienta, para que un símbolo de cotización incorrecto (que hace que get_stock_price lance ValueError) no bloquee la búsqueda del clima que se ejecuta junto a él.

Análisis Profundo

Cómo Funciona

• response.stop_reason == "tool_use" significa que Claude dejó de generar específicamente para devolverte el control; no es un estado de error ni la respuesta final.
• response.content es una lista de bloques de contenido. Un turno tool_use puede contener un bloque text inicial (Claude "pensando en voz alta") más uno o más bloques tool_use; siempre filtra por block.type == "tool_use" en lugar de asumir una forma fija.
• Cada bloque tool_use lleva .id (un identificador único para esta llamada específica), .name (qué herramienta), y .input (los argumentos, ya analizados en un diccionario Python que coincide con tu input_schema).
• El mensaje del asistente que añades a messages debe ser response.content exactamente como se devolvió, no una reconstrucción; es lo que preserva el id del bloque tool_use para que el tool_result de seguimiento pueda referenciarlo correctamente.
• Los bloques tool_result siempre viven dentro de un mensaje de rol user, nunca de un rol assistant, aunque nada de ellos fue escrito por un humano.

Estructuración del Contenido de tool_result

Notas de Python

# Nunca busques coincidencias de cadenas en JSON crudo para averiguar qué pidió Claude.
# Los modelos de la familia Claude 4 pueden escapar Unicode o barras diagonales de manera diferente
# entre respuestas, por lo que la coincidencia de texto crudo con block.input es frágil.
# Usa siempre el diccionario ya analizado del SDK:
 
for block in response.content:
    if block.type == "tool_use":
        # block.input es un diccionario; indexalo directamente, no uses json.loads()
        location = block.input["location"]

Parámetros y Valores de Retorno

Errores Comunes

• Coincidir con texto JSON crudo en lugar de block.input. Algunos equipos intentan usar expresiones regulares o coincidencia de cadenas de la llamada a la herramienta antes de analizarla. Los modelos de la familia Claude 4 pueden variar cómo escapan el Unicode o las barras diagonales en el JSON generado, por lo que esto falla intermitentemente. Solución: siempre lee block.input; el SDK ya lo ha analizado en un diccionario Python para ti.
• Añadir solo el texto, no el response.content completo, como turno del asistente. Si extraes response.content[0].text y lo insertas como cadena en messages, el id del bloque tool_use se pierde y la siguiente solicitud falla la validación. Solución: añade response.content literalmente: messages.append({"role": "assistant", "content": response.content}).
• Dividir múltiples bloques tool_result en mensajes de usuario separados. Cuando Claude solicita dos herramientas en un turno, enviar dos mensajes de user de seguimiento (uno por resultado) en lugar de un mensaje con dos bloques produce una conversación mal formada. Solución: recopila cada tool_result en una sola lista y envíalos juntos: messages.append({"role": "user", "content": tool_results}).
• Dejar un bloque tool_use sin respuesta. Si Claude solicita tres herramientas y tú solo devuelves dos bloques tool_result (por ejemplo, porque el tercero falló silenciosamente y tragaste la excepción), la siguiente llamada a messages.create rechaza la solicitud. Solución: envuelve cada llamada a herramienta en try/except y siempre añade un tool_result; en caso de fallo, establece is_error: True en lugar de omitirlo.
• Olvidar is_error en una llamada a herramienta fallida. Devolver la cadena de la excepción como content ordinario sin is_error: True hace que Claude trate una pila de llamadas o un mensaje de error como datos legítimos, que luego puede repetir al usuario como si fuera una respuesta real. Solución: siempre establece "is_error": True cuando la herramienta lanzó una excepción o devolvió un estado de fallo.
• No manejar un block.name no reconocido. Si Claude llama a un nombre de herramienta para el que tu código de despacho no tiene una rama, una cadena if/elif sin protección se cae y no hace nada o lanza un KeyError no manejado. Solución: haz que el caso de "herramienta desconocida" sea una rama explícita que devuelva un tool_result con is_error: True, como lo hace execute_tool en el Ejemplo de Trabajo anterior.
• Pasar un objeto no serializable como content. Devolver una instancia de clase personalizada, un datetime o un objeto de fila de base de datos directamente como tool_result["content"] falla cuando se serializa la solicitud. Solución: convierte la salida de la herramienta a una cadena o una estructura simple serializable en JSON antes de construir el bloque tool_result.

Alternativas

Preguntas Frecuentes

try:
    result = execute_tool(block.name, block.input)
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": block.id,
        "content": result,
    })
except Exception as e:
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": block.id,
        "content": str(e),
        "is_error": True,
    })

Relacionado

• Conceptos básicos de uso de herramientas - el tutorial completo de 10 ejemplos del cual se extrae la ronda de esta página.
• Definición de esquemas de herramientas con name, description e input_schema - escritura del input_schema que produce valores block.input confiables.
• Construcción de un bucle de uso de herramientas multi-turno - generalización del bucle while que se muestra aquí en una utilidad reutilizable.
• Ejecución de llamadas a herramientas paralelas en un solo turno - más sobre el procesamiento por lotes de múltiples bloques tool_result juntos.

Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de modelos, versiones de SDK y precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.