Tratando JSON Malformado de Uso de Ferramentas e Falhas de Validação de Esquema

O uso de ferramentas é o contrato entre Claude e seu código: o modelo produz argumentos estruturados, seu código executa uma função com base neles. Na maioria das vezes, esse contrato é cumprido. Ocasionalmente, não é: argumentos que não correspondem ao esquema declarado, um campo obrigatório ausente, uma incompatibilidade de tipo e, se seu código assumir que o contrato sempre se mantém, essa única chamada de ferramenta ruim pode travar um loop de agente ou corromper seu estado várias voltas depois.

Resumo

O uso de ferramentas do Claude retorna blocos de conteúdo tool_use onde input já foi analisado em um objeto Python pelo SDK, correspondendo à forma JSON que o modelo produziu.

A falha geralmente não é sintaxe JSON inválida, o parser do SDK cuida disso, é uma incompatibilidade entre o que o modelo produziu e o que o esquema da sua ferramenta realmente exige: um campo obrigatório ausente, um tipo incorreto, um valor de enumeração que não está entre as opções permitidas.

Se não for tratado, esse tipo de incompatibilidade lança um erro profundo no seu código de execução de ferramenta com um rastreamento de pilha confuso, ou pior, não lança nenhum erro e sua ferramenta recebe silenciosamente um valor para o qual não foi construída.

A correção é uma camada de validação entre "o modelo produziu entrada de ferramenta" e "seu código de ferramenta é executado", uma que captura a incompatibilidade, a registra com detalhes suficientes para diagnóstico e repara a entrada ou falha a chamada da ferramenta de forma limpa com uma mensagem de erro estruturada que o modelo pode ver e reagir.

Este artigo constrói essa camada usando pydantic para validação de esquema, pois ele se compõe bem com o estilo JSON Schema que as definições de ferramentas já exigem.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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

Quando usar isso:

• Qualquer ferramenta cujos argumentos vêm diretamente de um bloco tool_use do Claude, antes de passá-los para sua função real.
• Loops de agente multi-turno, onde uma chamada de ferramenta ruim hoje pode corromper silenciosamente o estado usado várias voltas depois.
• Ferramentas com esquemas não triviais: enums, objetos aninhados, campos opcionais com padrões, qualquer coisa além de um único argumento de string.
• Qualquer sistema onde uma falha de ferramenta precise ser relatada de volta ao modelo de uma forma que ele possa agir, em vez de travar todo o turno.

Exemplo de Trabalho

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)

O que isso demonstra:

• Registro da entrada tool_use bruta antes da validação, para que uma chamada rejeitada ainda deixe evidências para depuração.
• Uso de pydantic para validar block.input contra a mesma forma declarada em input_schema, capturando campos ausentes, tipos incorretos e valores de enumeração inválidos em um só lugar.
• Retorno de um tool_result estruturado com is_error: True em caso de falha, para que o modelo veja exatamente o que estava errado e possa tentar novamente com argumentos corrigidos na mesma rodada.
• Manter a execução da ferramenta (create_ticket) completamente separada da validação, para que a função em si nunca precise se defender contra entradas malformadas.

Mergulho Profundo

Como Funciona

• O SDK anthropic analisa o JSON que o modelo produz para argumentos de ferramenta em um dict Python automaticamente, então você raramente vê um JSONDecodeError bruto de um bloco tool-use em si.
• O que você vê é uma incompatibilidade de esquema: o dicionário analisado não satisfaz as restrições que sua ferramenta realmente precisa, uma chave obrigatória ausente, uma string onde você esperava um inteiro, um valor de enumeração fora do conjunto permitido.
• Alimentar erros de validação de volta ao modelo como um tool_result com is_error: True fecha o ciclo, o modelo pode ver exatamente o que estava errado e muitas vezes se autocorrege em sua próxima rodada, sem nenhuma lógica de nova tentativa em nível de código.
• Engolir silenciosamente uma falha de validação (capturando a exceção e não fazendo nada) é a opção mais perigosa, porque o loop de conversação do agente continua como se a chamada da ferramenta tivesse sido bem-sucedida, e a falha real surge mais tarde como um bug de aparência não relacionada.

Formas de Falha que Você Realmente Verá

Reparo vs. Rejeição

• Reparar quando a incompatibilidade é pequena e inequívoca, por exemplo, o modelo enviou "priority": "High" em vez de "high", um reparo de normalização de maiúsculas/minúsculas é seguro e economiza uma viagem de ida e volta.
• Rejeitar quando a incompatibilidade muda o significado, por exemplo, um campo obrigatório ausente, não há um padrão seguro para inventar e adivinhar corre o risco de executar a ferramenta com dados incorretos.
• Nunca repare descartando silenciosamente um erro de validação e prosseguindo com dados parciais ou padrão para algo que altera o efeito do mundo real da ferramenta (uma alteração de atribuição, um valor de pagamento). Rejeite esses explicitamente em vez disso.

Notas Python

# Uma passagem de reparo para o caso seguro e inequívoco: correspondência de enumeração insensível a maiúsculas/minúsculas.
# Tente reparos apenas onde a correção for inequívoca; qualquer outra coisa deve ser rejeitada.
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

Armadilhas

• Assumir que block.input sempre corresponde ao seu esquema. Nada garante estruturalmente que a chamada de ferramenta do modelo satisfaça seu input_schema, é uma forte convenção de nível de prompt, não um contrato imposto. Correção: sempre valide antes de executar, mesmo para ferramentas que "sempre" recebem argumentos simples na prática.

• Capturar o erro de validação e não fazer nada. Um erro silenciosamente engolido parece um turno bem-sucedido para o resto do loop do agente, e a falha real surge mais tarde, desconectada de sua causa. Correção: sempre repare explicitamente e registre, ou retorne um resultado de ferramenta is_error estruturado que o modelo possa ver.

• Registrar apenas que a validação falhou, não o que especificamente falhou. "Entrada de ferramenta inválida" sem os erros de nível de campo torna falhas repetidas difíceis de diagnosticar em muitas chamadas. Correção: registre e.errors() (ou detalhes de nível de campo equivalentes) em cada falha de validação, não apenas um booleano.

• Reparar incompatibilidades ambíguas em vez de rejeitá-las. Definir silenciosamente um campo obrigatório ausente para um valor adivinhado pode executar uma ferramenta com dados significativamente incorretos. Correção: repare apenas incompatibilidades inequívocas e de baixo risco (normalização de maiúsculas/minúsculas, espaços em branco); rejeite todo o resto.

• Não retornar is_error: True em um resultado de ferramenta com falha. Enviar um resultado de ferramenta de volta ao modelo sem marcá-lo como um erro pode fazer com que o modelo trate uma falha como um sucesso e continue como se a ferramenta tivesse sido executada corretamente. Correção: sempre defina is_error: True no bloco tool_result quando a chamada falhou.

• Tratar cada nome de ferramenta desconhecido como uma falha de validação. Um block.name não reconhecido é um problema diferente, um bug de roteamento ou uma definição de ferramenta desatualizada, não uma incompatibilidade de esquema. Correção: trate nomes de ferramentas desconhecidos como um ramo de falha distinto com seu próprio registro, separado da validação de esquema.

Alternativas

FAQs

Relacionados

• Entendendo Por Que os Agentes Claude Falham em Produção - onde as falhas de contrato se encaixam na taxonomia mais ampla de falhas.
• Noções Básicas de Solução de Problemas e Confiabilidade - registro de blocos tool-use antes de adicionar validação por cima.
• Estratégias de Retentativa e Backoff Exponencial para Falhas Transitórias da API Claude - padrões de resiliência para falhas de nível de transporte que ficam ao lado de falhas de contrato.
• Modelo de Análise de Causa Raiz para Falhas de Agente - documentando um incidente de tool-use após sua resolução.
• Melhores Práticas de Solução de Problemas e Confiabilidade - onde a validação de tool-use se encaixa na lista de verificação mais ampla.

Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial anthropic Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.