Tratando Requisições de tool_use e Retornando Blocos tool_result

Execute a ferramenta solicitada e retorne um bloco de conteúdo tool_result correspondente.

Resumo

Quando stop_reason em uma Message retorna "tool_use", Claude pausou no meio da vez para pedir que seu código execute algo. Ele ainda não respondeu ao usuário - está esperando por você.

Seu trabalho é um processo fixo de cinco etapas: encontrar os blocos tool_use em response.content, executar a função Python correspondente com block.input, anexar o response.content do assistente de volta a messages literalmente, envolver a saída de cada ferramenta em um bloco tool_result com a chave tool_use_id, e chamar messages.create novamente.

Esta página trata de realizar essa transição corretamente e de forma defensiva - lendo block.input como o dicionário analisado que o SDK fornece (nunca analisando novamente ou correspondendo strings de JSON bruto), tratando cada bloco tool_use em uma vez (não apenas o primeiro), e relatando falhas com is_error em vez de deixar uma exceção encerrar a requisição.

Acertar este loop uma vez o transforma em uma função pequena e reutilizável que todas as requisições que usam ferramentas em sua aplicação podem chamar.

Receita

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

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,
    )

Quando usar isso:

• Qualquer requisição onde você passou uma lista tools não vazia e precisa realmente honrar uma resposta tool_use.
• Vezes em que Claude pode solicitar mais de uma ferramenta por vez - o loop acima lida com todas elas antes de responder.
• Em qualquer lugar onde uma chamada de ferramenta possa falhar plausivelmente (uma API instável, uma consulta incorreta) e você queira que Claude veja a falha em vez de seu processo travar.
• Construindo um helper de propósito geral "execute esta conversa até que Claude pare de pedir ferramentas" que você reutilizará em vários endpoints.

Exemplo Funcional

import anthropic
 
client = anthropic.Anthropic()
 
weather_tool = {
    "name": "get_weather",
    "description": "Obtém o clima atual para um local. Chame isso quando o usuário perguntar sobre condições atuais.",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "Cidade e estado, por exemplo, São Paulo, SP",
            }
        },
        "required": ["location"],
    },
}
 
stock_price_tool = {
    "name": "get_stock_price",
    "description": "Obtém o preço mais recente para um símbolo de ticker de ação.",
    "input_schema": {
        "type": "object",
        "properties": {
            "ticker": {
                "type": "string",
                "description": "Símbolo do ticker da ação, por exemplo, PETR4",
            }
        },
        "required": ["ticker"],
    },
}
 
tools = [weather_tool, stock_price_tool]
 
 
def get_weather(location: str) -> str:
    # Substitua por uma chamada real de API de clima.
    return f"72F e ensolarado em {location}"
 
 
def get_stock_price(ticker: str) -> str:
    # Substitua por uma chamada real de API de dados de mercado.
    if not ticker.isalpha():
        raise ValueError(f"'{ticker}' não é um símbolo de ticker válido")
    return f"{ticker.upper()} está sendo negociado a R$ 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"Ferramenta desconhecida: {name}")
    return TOOL_FUNCTIONS[name](**tool_input)
 
 
def run_turn(messages: list) -> list:
    """Envia mensagens, lida com qualquer ciclo de ida e volta de tool_use, retorna a lista atualizada."""
    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": "Qual o clima em São Paulo, SP, e qual o preço de AAPL?",
        }
    ]
 
    conversation = run_turn(conversation)
    final_text = next(
        block.text for block in conversation[-1]["content"] if block.type == "text"
    )
    print(final_text)

O que isso demonstra:

• Um loop while response.stop_reason == "tool_use":, para que o manipulador continue resolvendo chamadas de ferramentas até que Claude produza uma resposta de texto final, não apenas uma única viagem de ida e volta.
• Uma tabela de despacho (TOOL_FUNCTIONS) que mapeia block.name a uma função Python real, com execute_tool levantando um erro limpo para qualquer nome que não reconheça.
• Duas ferramentas solicitadas na mesma pergunta do usuário, ambas resolvidas e retornadas juntas em uma única mensagem user contendo tool_result.
• Um try/except em torno de cada execução de ferramenta, para que um símbolo incorreto (get_stock_price levantando ValueError) não derrube a consulta de clima executada ao lado dela.

Mergulho Profundo

Como Funciona

• response.stop_reason == "tool_use" significa que Claude parou de gerar especificamente para devolver o controle a você - não é um estado de erro nem a resposta final.
• response.content é uma lista de blocos de conteúdo. Uma vez tool_use pode conter um bloco text inicial (Claude "pensando alto") mais um ou mais blocos tool_use - sempre filtre por block.type == "tool_use" em vez de assumir uma forma fixa.
• Cada bloco tool_use carrega .id (um identificador único para esta chamada específica), .name (qual ferramenta) e .input (os argumentos, já analisados em um dicionário Python que corresponde ao seu input_schema).
• A mensagem do assistente que você anexa a messages deve ser response.content exatamente como retornado, não uma reconstrução - é o que preserva o id do bloco tool_use para que o tool_result subsequente possa referenciá-lo corretamente.
• Os blocos tool_result sempre vivem dentro de uma mensagem de role user, nunca de assistant, mesmo que nada sobre eles tenha sido digitado por um humano.

Estruturando Conteúdo de tool_result

Notas Python

# Nunca corresponda strings de JSON bruto para descobrir o que Claude pediu.
# Os modelos da família Claude 4 podem escapar Unicode ou barras invertidas de forma diferente
# entre as respostas, então a correspondência de texto bruto em block.input é frágil.
# Sempre use o dicionário já analisado do SDK:
 
for block in response.content:
    if block.type == "tool_use":
        # block.input é um dicionário - acesse-o diretamente, não use json.loads()
        location = block.input["location"]

Parâmetros e Valores de Retorno

Armadilhas

• Correspondência de texto JSON bruto em vez de block.input. Algumas equipes tentam usar regex ou correspondência de strings da chamada da ferramenta antes de analisá-la. Os modelos da família Claude 4 podem variar como escapam Unicode ou barras invertidas em JSON gerado, então essa abordagem falha intermitentemente. Correção: sempre leia block.input - o SDK já o analisou em um dicionário Python para você.
• Anexar apenas o texto, não o response.content completo, como a vez do assistente. Se você extrair response.content[0].text e empurrar apenas essa string de volta para messages, o id do bloco tool_use é perdido e a próxima requisição falha na validação. Correção: anexe response.content literalmente: messages.append({"role": "assistant", "content": response.content}).
• Dividir múltiplos blocos tool_result em mensagens de usuário separadas. Quando Claude solicita duas ferramentas em uma vez, enviar duas mensagens de user de acompanhamento (uma por resultado) em vez de uma mensagem com dois blocos produz uma conversa malformada. Correção: colete todos os tool_result em uma lista e envie-os juntos: messages.append({"role": "user", "content": tool_results}).
• Deixar um bloco tool_use sem resposta. Se Claude solicitar três ferramentas e você retornar apenas dois blocos tool_result (por exemplo, porque o terceiro falhou silenciosamente e você engoliu a exceção), a próxima chamada messages.create rejeitará a requisição. Correção: envolva cada chamada de ferramenta em try/except e sempre anexe um tool_result - em caso de falha, defina is_error: True em vez de pular.
• Esquecer is_error em uma chamada de ferramenta falha. Retornar a string da exceção como content comum sem is_error: True faz com que Claude trate um stack trace ou mensagem de erro como dados legítimos, que ele então pode repetir ao usuário como se fosse uma resposta real. Correção: sempre defina "is_error": True quando a ferramenta levantou uma exceção ou retornou um status de falha.
• Não tratar um block.name não reconhecido. Se Claude chamar um nome de ferramenta para o qual seu código de despacho não tem um ramo, uma cadeia if/elif sem guarda cairá e não fará nada ou levantará um KeyError não tratado. Correção: faça o caso de "ferramenta desconhecida" um ramo explícito que retorna um tool_result com is_error: True, como execute_tool faz no Exemplo Funcional acima.
• Passar um objeto não serializável como content. Retornar uma instância de classe personalizada, um datetime ou um objeto de linha de banco de dados diretamente como tool_result["content"] falha quando a requisição é serializada. Correção: converta a saída da ferramenta para uma string ou estrutura serializável JSON simples antes de construir o bloco tool_result.

Alternativas

FAQs

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

• Noções Básicas de Uso de Ferramentas - o tutorial completo com 10 exemplos do qual o ciclo de ida e volta desta página é extraído
• Definindo Esquemas de Ferramentas com name, description e input_schema - escrevendo o input_schema que produz valores block.input confiáveis
• Construindo um Loop de Uso de Ferramentas Multi-Turno - generalizando o loop while mostrado aqui em um helper reutilizável
• Executando Chamadas de Ferramentas Paralelas em uma Única Vez - mais sobre o agrupamento de vários blocos tool_result juntos

Versões da Stack: Escrito contra a linha de modelos Claude atual a partir de ~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, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.