Claude API 400 «tool_use ids were found without tool_result blocks» — la regla de orden

La invariante, expresada una vez

Cada bloque tool_use de un turno assistant necesita exactamente un bloque tool_result en el mensaje user inmediatamente siguiente, con el mismo tool_use_id. Si hay varios bloques tool_use en un turno, ese único mensaje siguiente necesita varios bloques tool_result. No puede haber nada entre ambos turnos.

Responda siempre, incluso cuando falle la herramienta

El modelo gestiona perfectamente una herramienta fallida; no puede gestionar una ausente. Devolver el error como tool_result mantiene válida la conversación y normalmente permite una recuperación razonable en lugar de un 400.

results = []
for block in (b for b in resp.content if b.type == "tool_use"):
    try:
        out = run_tool(block.name, block.input)
        results.append({
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": str(out),
        })
    except Exception as e:
        # A failed tool still owes the model an answer.
        results.append({
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": f"Tool failed: {e}",
            "is_error": True,
        })

messages.append({"role": "assistant", "content": resp.content})
messages.append({"role": "user", "content": results})

Valide los dos últimos turnos antes de enviar

Una docena de líneas de aserciones detecta el problema en el punto de llamada, en lugar de recibir un 400 de la red: recorra los ids tool_use del turno assistant y confirme que el siguiente turno user responde a todos.

def check_pairs(messages):
    for i, m in enumerate(messages):
        if m["role"] != "assistant" or not isinstance(m.get("content"), list):
            continue
        ids = {b.get("id") for b in m["content"]
               if isinstance(b, dict) and b.get("type") == "tool_use"}
        if not ids:
            continue
        nxt = messages[i + 1] if i + 1 < len(messages) else None
        answered = {b.get("tool_use_id") for b in (nxt or {}).get("content", [])
                    if isinstance(b, dict) and b.get("type") == "tool_result"}
        missing = ids - answered
        assert not missing, f"message {i}: unanswered tool_use {missing}"

Recorte el historial en los límites de los intercambios

El recorte de la ventana de contexto por número de mensajes acabará separando un tool_use de su tool_result. Trate la pareja como una unidad indivisible al decidir qué eliminar.

¿Puedo simplemente eliminar el turno tool_use en lugar de responderlo?

Sí, si elimina el turno assistant completo. Lo que no es válido es conservar tool_use y omitir su tool_result.

¿El endpoint compatible con OpenAI tiene la misma regla?

Se requiere la misma correspondencia, con otra sintaxis: tool_calls en el mensaje assistant y después un mensaje role: "tool" por cada llamada, con tool_call_id.

¿Cuesta algo una solicitud rechazada?

En Kunavo, no. Las solicitudes fallidas se registran con coste cero y nunca llegan a una llamada ascendente facturada.