Construcción de un Bucle de Uso de Herramientas de Múltiples Turnos

Repite los intercambios de tool_use y tool_result hasta que Claude devuelva un end_turn.

Resumen

La API de Mensajes no tiene estado: cada llamada es una solicitud nueva sin memoria de turnos anteriores, excepto lo que envías en messages. Cuando Claude decide que se necesita una herramienta, no ejecuta la herramienta él mismo. Deja de generar, devuelve un bloque tool_use que describe lo que quiere llamar y devuelve el control a tu código.

Tu trabajo es ejecutar la herramienta, empaquetar el resultado como un bloque tool_result y enviar toda la conversación de vuelta. Claude luego pide otra llamada a la herramienta o produce su respuesta final. Muchas tareas reales (buscar algo, luego actuar sobre lo encontrado, luego verificar el resultado) requieren varios de estos viajes de ida y vuelta antes de que Claude termine.

Esta ida y vuelta es el "bucle agéntico": llama a la API, inspecciona stop_reason, ejecuta herramientas si se le solicita, anexa resultados, llama de nuevo. Termina cuando response.stop_reason == "end_turn". Si te equivocas en el bucle (pierdes contenido, olvidas una stop_reason o omites el guardia de iteración), obtendrás un error en la siguiente llamada o un agente que se ejecutará indefinidamente.

Esta página construye ese bucle manualmente en Python con el SDK oficial de anthropic, y luego muestra el atajo de nivel superior Tool Runner una vez que se entiende la versión manual.

Receta

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

import anthropic
 
client = anthropic.Anthropic()
messages = [{"role": "user", "content": user_input}]
 
while True:
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )
 
    if response.stop_reason == "end_turn":
        break
 
    if response.stop_reason == "pause_turn":
        messages.append({"role": "assistant", "content": response.content})
        continue
 
    tool_use_blocks = [b for b in response.content if b.type == "tool_use"]
    messages.append({"role": "assistant", "content": response.content})
 
    tool_results = []
    for block in tool_use_blocks:
        result = execute_tool(block.name, block.input)
        tool_results.append({
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": result,
        })
    messages.append({"role": "user", "content": tool_results})
 
final_text = "".join(b.text for b in response.content if b.type == "text")

Cuándo usar esto:

• Claude necesita llamar a una o más herramientas antes de poder dar una respuesta final (búsquedas, cálculos, efectos secundarios).
• La tarea puede requerir varios pasos dependientes: por ejemplo, buscar, luego obtener un registro específico, luego resumir.
• Estás construyendo un agente que se ejecuta sin supervisión y debe continuar hasta que Claude haya terminado realmente, no solo después de una llamada a la herramienta.
• Quieres control total sobre cómo se ejecutan las herramientas (concurrencia, reintentos, sandboxing) en lugar de delegar eso a un framework.

Ejemplo de Trabajo

import json
import anthropic
 
client = anthropic.Anthropic()
 
tools = [
    {
        "name": "get_weather",
        "description": "Obtener el clima actual de una ciudad.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "Nombre de la ciudad, p. ej. 'Denver'"},
            },
            "required": ["city"],
        },
    },
    {
        "name": "convert_temperature",
        "description": "Convertir una temperatura entre Celsius y Fahrenheit.",
        "input_schema": {
            "type": "object",
            "properties": {
                "value": {"type": "number"},
                "from_unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["value", "from_unit"],
        },
    },
]
 
 
def get_weather(city: str) -> str:
    # Sustituto de una llamada real a la API del clima.
    fake_data = {"Denver": 8.0, "Miami": 29.0}
    celsius = fake_data.get(city, 20.0)
    return json.dumps({"city": city, "celsius": celsius})
 
 
def convert_temperature(value: float, from_unit: str) -> str:
    if from_unit == "celsius":
        result = value * 9 / 5 + 32
        return json.dumps({"fahrenheit": round(result, 1)})
    result = (value - 32) * 5 / 9
    return json.dumps({"celsius": round(result, 1)})
 
 
def execute_tool(name: str, tool_input: dict) -> str:
    if name == "get_weather":
        return get_weather(tool_input["city"])
    if name == "convert_temperature":
        return convert_temperature(tool_input["value"], tool_input["from_unit"])
    return json.dumps({"error": f"herramienta desconocida: {name}"})
 
 
def run_agent(user_input: str, max_iterations: int = 12) -> str:
    messages = [{"role": "user", "content": user_input}]
    response = None
 
    for _ in range(max_iterations):
        response = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=4096,
            tools=tools,
            messages=messages,
        )
 
        if response.stop_reason == "end_turn":
            break
 
        if response.stop_reason == "pause_turn":
            messages.append({"role": "assistant", "content": response.content})
            continue
 
        if response.stop_reason == "max_tokens":
            raise RuntimeError("Respuesta truncada en max_tokens; aumenta el límite.")
 
        if response.stop_reason == "refusal":
            raise RuntimeError(f"Claude rechazó la solicitud: {response.stop_reason}")
 
        tool_use_blocks = [b for b in response.content if b.type == "tool_use"]
        messages.append({"role": "assistant", "content": response.content})
 
        if not tool_use_blocks:
            # No hay llamadas a herramientas ni end_turn - nada más que hacer de forma segura.
            break
 
        tool_results = []
        for block in tool_use_blocks:
            result = execute_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
        messages.append({"role": "user", "content": tool_results})
    else:
        raise RuntimeError("Se excedió max_iterations sin alcanzar end_turn.")
 
    return "".join(b.text for b in response.content if b.type == "text")
 
 
if __name__ == "__main__":
    answer = run_agent(
        "¿Cuál es el clima en Denver ahora mismo, en Fahrenheit?"
    )
    print(answer)

Lo que esto demuestra:

• Un bucle acotado (for _ in range(max_iterations)) que siempre termina, con un RuntimeError lanzado a través de la cláusula for...else si Claude nunca alcanza end_turn.
• Se anexa el response.content completo, no solo el texto extraído, como el turno del asistente para que los bloques tool_use que Claude emitió sean visibles en la próxima llamada.
• Un tool_result emparejado por tool_use_id por cada bloque tool_use, agrupado en un solo mensaje user por turno (requerido cuando Claude solicita llamadas a herramientas en paralelo).
• Manejo explícito para pause_turn, max_tokens y refusal junto con las dos rutas de "seguir en bucle" (tool_use y end_turn).
• Un único despachador execute_tool que mantiene el enrutamiento de herramientas en un solo lugar en lugar de cadenas if/elif dispersas cerca de la llamada a la API.

Inmersión Profunda

Cómo Funciona

• Cada llamada a client.messages.create() es independiente. La API no tiene estado de sesión: todo lo que Claude "recuerda" es lo que incluiste en messages en esa llamada.
• Cuando Claude quiere una herramienta, deja de generar salida y devuelve bloques de contenido: algunos text (raro a mitad de bucle, pero posible), uno o más bloques tool_use, y una stop_reason.
• Tu código ejecuta la(s) herramienta(s) solicitada(s) localmente (o a través de un conector) e informa de vuelta con bloques tool_result, emparejados con la llamada original a través de tool_use_id.
• La siguiente llamada a messages.create() reenvía toda la conversación creciente: el turno original del usuario, el turno del asistente de Claude con bloques tool_use, tu turno user con bloques tool_result, para que Claude tenga el contexto completo para continuar o concluir.
• El bucle no es una llamada única de "llamar a la herramienta, obtener respuesta"; Claude puede encadenar varias llamadas a herramientas (buscar algo, luego actuar sobre ello, luego verificar) antes de tener suficiente información para responder, por lo que el bucle, no una sola solicitud/respuesta, es el modelo mental correcto.

Valores de stop_reason y Qué Hacer

Forma del Mensaje en Cada Paso

# Después del turno 1 (Claude solicita una llamada a herramienta):
messages == [
    {"role": "user", "content": "What's the weather in Denver?"},
    {"role": "assistant", "content": [ToolUseBlock(id="toolu_01...", name="get_weather", input={"city": "Denver"})]},
]
 
# Después de que ejecutas la herramienta y anexas el resultado:
messages == [
    {"role": "user", "content": "What's the weather in Denver?"},
    {"role": "assistant", "content": [ToolUseBlock(...)]},
    {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_01...", "content": "..."}]},
]

Notas de Python

# Prefiere un diccionario de distribución sobre largas cadenas if/elif a medida que aumenta el número de herramientas:
TOOL_HANDLERS = {
    "get_weather": lambda i: get_weather(i["city"]),
    "convert_temperature": lambda i: convert_temperature(i["value"], i["from_unit"]),
}
 
def execute_tool(name: str, tool_input: dict) -> str:
    handler = TOOL_HANDLERS.get(name)
    if handler is None:
        return json.dumps({"error": f"herramienta desconocida: {name}"})
    try:
        return handler(tool_input)
    except Exception as exc:
        # Informar fallos a Claude como datos, no como un proceso caído.
        return json.dumps({"error": str(exc)})

Parámetros y Valores de Retorno

Trampas

• Anexar solo el texto extraído, no response.content. Si envías {"role": "assistant", "content": final_text} en lugar de los bloques de contenido crudos, la próxima solicitud de Claude pierde los bloques tool_use que tu mensaje tool_result debe responder, y la API rechazará el mensaje tool_result de seguimiento porque no coincide con una llamada a herramienta anterior. Solución: siempre anexa response.content sin modificar como el turno del asistente.
• Sin límite de iteración. Un bucle que solo sale en end_turn se ejecutará indefinidamente si una herramienta sigue devolviendo datos ambiguos o el modelo se queda atascado solicitando la misma llamada. Solución: envuelve el bucle en for _ in range(max_iterations) (10-15 es un valor predeterminado razonable) y lanza/registra un tiempo de espera cuando se agote.
• Tratar pause_turn como un turno normal de tool_use. Enviar un nuevo mensaje de usuario "Continuar" después de pause_turn (en lugar de reenviar el turno del asistente pausado tal cual) confunde el estado de la herramienta del lado del servidor reanudada. Solución: anexa response.content y llama a la API nuevamente de inmediato, sin mensaje de usuario adicional.
• tool_use_id faltante o incorrecto. Cada tool_result debe hacer referencia al id del bloque tool_use al que responde; omitir un bloque (p. ej., cuando Claude solicita dos llamadas paralelas pero solo manejas una) deja a la API esperando una llamada a herramienta no resuelta. Solución: itera sobre todos los bloques tool_use en la respuesta y produce exactamente un tool_result por bloque, agrupado en un solo mensaje user.
• Dejar que una excepción de herramienta bloquee el bucle. Una excepción no capturada dentro de execute_tool mata toda la solicitud en lugar de darle a Claude la oportunidad de recuperarse (p. ej., reintentar con argumentos diferentes). Solución: captura las excepciones por herramienta y devuélvelas como contenido de tool_result (p. ej., {"error": "..."}) para que Claude pueda reaccionar.
• Ignorar max_tokens como razón de parada. Tratar max_tokens como end_turn envía silenciosamente una respuesta truncada al usuario. Solución: compruébalo explícitamente y lanza max_tokens en la siguiente llamada o cambia a streaming.
• Reintentar ciegamente en refusal. Repetir el mismo prompt después de una negativa de seguridad desperdicia llamadas y no cambiará el resultado. Solución: inspecciona stop_details, ajusta la solicitud o escala a un humano en lugar de reintentar textualmente.

Alternativas

Preguntas Frecuentes

Relacionado

• Manejo de Solicitudes tool_use y Devolución de Bloques tool_result - la mecánica de un solo turno que este bucle repite en cada iteración.
• Ejecución de Llamadas a Herramientas Paralelas en un Solo Turno - cómo manejar múltiples bloques tool_use devueltos en un turno.
• Conceptos Básicos de Uso de Herramientas - los conceptos fundamentales (herramientas, tool_choice, esquemas) sobre los que se basa esta página.
• Mejores Prácticas - guía más amplia para un uso de herramientas confiable y listo para producción.

Versiones de la Pila: Escrito contra la línea de modelos de 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 los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.