Manejo de JSON malformado para uso de herramientas y fallos de validación de esquemas

El uso de herramientas es el contrato entre Claude y tu código: el modelo produce argumentos estructurados, tu código ejecuta una función contra ellos. La mayoría de las veces ese contrato se cumple. Ocasionalmente no es así, argumentos que no coinciden con el esquema declarado, falta un campo requerido, una discrepancia de tipo, y si tu código asume que el contrato siempre se cumple, esa única llamada a herramienta incorrecta puede bloquear un bucle de agente o corromper su estado varias vueltas después.

Resumen

El uso de herramientas de Claude devuelve bloques de contenido tool_use donde input ya ha sido analizado en un objeto Python por el SDK, coincidiendo con la forma JSON que produjo el modelo.

El fallo no suele ser sintaxis JSON inválida, el análisis del SDK se encarga de eso, es una discrepancia entre lo que produjo el modelo y lo que realmente requiere el esquema de tu herramienta: falta un campo requerido, un tipo incorrecto, un valor de enumeración que no está entre las opciones permitidas.

Si no se maneja, este tipo de discrepancia provoca un error profundo dentro de tu código de ejecución de herramientas con un rastreo de pila confuso, o peor aún, no provoca ningún error y tu herramienta recibe silenciosamente un valor para el que no fue construida.

La solución es una capa de validación entre "el modelo produjo la entrada de la herramienta" y "tu código de herramienta se ejecuta", una que captura la discrepancia, la registra con suficiente detalle para diagnosticarla, y repara la entrada o falla la llamada a la herramienta limpiamente con un mensaje de error estructurado que el modelo pueda ver y al que pueda reaccionar.

Este artículo construye esa capa utilizando pydantic para la validación de esquemas, ya que se compone bien con el estilo JSON Schema que ya requieren las definiciones de herramientas.

Receta

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

from pydantic import BaseModel, ValidationError
 
class SearchArgs(BaseModel):
    query: str
    max_results: int = 10
 
def validate_tool_input(raw_input: dict) -> SearchArgs | None:
    try:
        return SearchArgs.model_validate(raw_input)
    except ValidationError as e:
        print("invalid tool input:", e)
        return None

Cuándo usar esto:

• Cualquier herramienta cuyos argumentos provengan directamente de un bloque tool_use de Claude, antes de pasarlos a tu función real.
• Bucles de agente multivuelta, donde una llamada a herramienta incorrecta hoy puede corromper silenciosamente el estado utilizado varias vueltas después.
• Herramientas con esquemas no triviales: enumeraciones, objetos anidados, campos opcionales con valores predeterminados, cualquier cosa más allá de un único argumento de cadena.
• Cualquier sistema donde un fallo de herramienta deba ser reportado de vuelta al modelo de una manera en que pueda actuar, en lugar de bloquear todo el turno.

Ejemplo de trabajo

import json
import logging
from typing import Literal
 
import anthropic
from pydantic import BaseModel, ValidationError, Field
 
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("tool_use_validation")
 
client = anthropic.Anthropic()
 
 
class CreateTicketArgs(BaseModel):
    title: str
    priority: Literal["low", "medium", "high"]
    assignee: str | None = Field(default=None)
 
 
TOOLS = [
    {
        "name": "create_ticket",
        "description": "Create a support ticket.",
        "input_schema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "priority": {"type": "string", "enum": ["low", "medium", "high"]},
                "assignee": {"type": "string"},
            },
            "required": ["title", "priority"],
        },
    }
]
 
 
def create_ticket(args: CreateTicketArgs) -> str:
    return f"Created ticket '{args.title}' (priority={args.priority})"
 
 
def handle_tool_use(block: anthropic.types.ToolUseBlock) -> dict:
    """Validate a tool_use block's input before executing the tool.
    Returns a tool_result content block, success or structured error,
    ready to send back to the model."""
    logger.info("tool_use.raw", extra={"tool": block.name, "raw_input": json.dumps(block.input)})
 
    if block.name != "create_ticket":
        return {
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": f"Unknown tool: {block.name}",
            "is_error": True,
        }
 
    try:
        args = CreateTicketArgs.model_validate(block.input)
    except ValidationError as e:
        logger.warning("tool_use.invalid", extra={"tool": block.name, "errors": e.errors()})
        error_summary = "; ".join(
            f"{err['loc']}: {err['msg']}" for err in e.errors()
        )
        return {
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": f"Invalid arguments for create_ticket: {error_summary}",
            "is_error": True,
        }
 
    result = create_ticket(args)
    logger.info("tool_use.success", extra={"tool": block.name})
    return {
        "type": "tool_result",
        "tool_use_id": block.id,
        "content": result,
    }
 
 
if __name__ == "__main__":
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=512,
        tools=TOOLS,
        messages=[{"role": "user", "content": "Create a high priority ticket titled 'Payments down'."}],
    )
    for block in response.content:
        if block.type == "tool_use":
            result = handle_tool_use(block)
            print(result)

Lo que esto demuestra:

• Registro de la entrada tool_use sin procesar antes de la validación, de modo que una llamada rechazada aún deje evidencia para la depuración.
• Uso de pydantic para validar block.input contra la misma forma declarada en input_schema, capturando campos faltantes, tipos incorrectos y valores de enumeración inválidos en un solo lugar.
• Devolución de un tool_result estructurado con is_error: True en caso de fallo, para que el modelo vea exactamente qué salió mal y pueda reintentar con argumentos corregidos en el mismo turno.
• Mantener la ejecución de la herramienta (create_ticket) completamente separada de la validación, para que la función en sí misma nunca tenga que defenderse contra entradas malformadas.

Inmersión profunda

Cómo funciona

• El SDK de anthropic analiza el JSON que el modelo produce para los argumentos de la herramienta en un dict de Python automáticamente, por lo que rara vez verá un JSONDecodeError sin procesar de un bloque tool-use en sí.
• Lo que sí verá es una discrepancia de esquema: el diccionario analizado no satisface las restricciones que su herramienta realmente necesita, falta una clave requerida, una cadena donde esperaba un entero, un valor de enumeración fuera del conjunto permitido.
• Devolver los errores de validación al modelo como un tool_result con is_error: True cierra el bucle, el modelo puede ver exactamente qué salió mal y a menudo se autocorrige en su próximo turno, sin ninguna lógica de reintento a nivel de código.
• Ignorar silenciosamente un fallo de validación (capturando la excepción y sin hacer nada) es la opción más peligrosa, porque la conversación del agente continúa como si la llamada a la herramienta hubiera tenido éxito, y el fallo real aparece más tarde como un error que no está relacionado.

Formas de fallo que realmente verá

Reparar vs. Rechazar

• Reparar cuando la discrepancia es pequeña y no ambigua, por ejemplo, el modelo envió "priority": "High" en lugar de "high", una reparación de normalización de mayúsculas/minúsculas es segura y ahorra un viaje de ida y vuelta.
• Rechazar cuando la discrepancia cambia el significado, por ejemplo, falta un campo requerido, no hay un valor predeterminado seguro para inventar y adivinar corre el riesgo de ejecutar la herramienta con datos incorrectos.
• Nunca repare omitiendo silenciosamente un fallo de validación y procediendo con datos parciales o predeterminados para algo que cambia el efecto real de la herramienta (un cambio de asignatario, un monto de pago). Rechace esos explícitamente en su lugar.

Notas de Python

# Un pase de reparación para el caso seguro y no ambiguo: coincidencia de enumeración insensible a mayúsculas/minúsculas.
# Intente reparaciones solo donde la corrección sea inequívoca; cualquier otra cosa debe ser rechazada.
def repair_enum_case(raw_input: dict, field: str, allowed: list[str]) -> dict:
    value = raw_input.get(field)
    if isinstance(value, str):
        lowered = value.lower()
        if lowered in allowed:
            raw_input[field] = lowered
    return raw_input

Trampas

• Asumir que block.input siempre coincide con tu esquema. Nada garantiza estructuralmente que la llamada a la herramienta del modelo satisfaga tu input_schema, es una fuerte convención a nivel de prompt, no un contrato aplicado. Solución: siempre valide antes de ejecutar, incluso para herramientas que "siempre" reciben argumentos simples en la práctica.

• Capturar el error de validación y no hacer nada. Un error omitido silenciosamente parece un turno exitoso para el resto del bucle del agente, y el fallo real aparece más tarde, desconectado de su causa. Solución: siempre repare explícitamente y regístrelo, o devuelva un resultado de herramienta estructurado is_error que el modelo pueda ver.

• Registrar solo que la validación falló, no qué falló específicamente. "Entrada de herramienta inválida" sin los errores a nivel de campo hace que los fallos repetidos sean difíciles de diagnosticar en muchas llamadas. Solución: registre e.errors() (o detalles a nivel de campo equivalentes) en cada fallo de validación, no solo un booleano.

• Reparar discrepancias ambiguas en lugar de rechazarlas. Asignar silenciosamente un valor predeterminado a un campo requerido faltante puede ejecutar una herramienta con datos significativamente incorrectos. Solución: repare solo discrepancias inequívocas y de bajo riesgo (normalización de mayúsculas/minúsculas, espacios en blanco); rechace todo lo demás.

• No devolver is_error: True en un resultado de herramienta fallido. Devolver un resultado de herramienta al modelo sin marcarlo como un error puede hacer que el modelo trate un fallo como un éxito y continúe como si la herramienta se hubiera ejecutado correctamente. Solución: siempre establezca is_error: True en el bloque tool_result cuando la llamada falló.

• Tratar cada nombre de herramienta desconocido como un fallo de validación. Un block.name no reconocido es un problema diferente, un error de enrutamiento o una definición de herramienta obsoleta, no una discrepancia de esquema. Solución: maneje los nombres de herramientas desconocidos como una rama distinta con su propio registro, separada de la validación de esquemas.

Alternativas

Preguntas frecuentes

Relacionado

• Understanding Why Claude Agents Fail in Production - dónde encajan los fallos de contrato en la taxonomía general de fallos.
• Troubleshooting & Reliability Basics - registro de bloques tool-use antes de agregar validación encima.
• Retry and Exponential Backoff Strategies for Transient Claude API Failures - patrones de resiliencia para fallos a nivel de transporte que se encuentran junto con fallos de contrato.
• Root-Cause-Analysis Template for Agent Failures - documentación de un incidente de tool-use una vez resuelto.
• Troubleshooting & Reliability Best Practices - dónde encaja la validación de tool-use en la lista de verificación general.

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