Escolhendo um modelo

Recomendamos usar o modelo Claude Sonnet (4.5) ou Claude Opus (4.1) mais recente para ferramentas complexas e consultas ambíguas; eles lidam melhor com múltiplas ferramentas e buscam esclarecimentos quando necessário. Use modelos Claude Haiku para ferramentas diretas, mas observe que eles podem inferir parâmetros ausentes.
Se estiver usando Claude com uso de ferramentas e pensamento estendido, consulte nosso guia aqui para mais informações.

Especificando ferramentas do cliente

As ferramentas do cliente (tanto definidas pela Anthropic quanto definidas pelo usuário) são especificadas no parâmetro de nível superior tools da solicitação da API. Cada definição de ferramenta inclui:
ParâmetroDescrição
nameO nome da ferramenta. Deve corresponder à regex ^[a-zA-Z0-9_-]{1,64}$.
descriptionUma descrição detalhada em texto simples do que a ferramenta faz, quando deve ser usada e como se comporta.
input_schemaUm objeto JSON Schema que define os parâmetros esperados para a ferramenta.
JSON
{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}
Esta ferramenta, chamada get_weather, espera um objeto de entrada com uma string location obrigatória e uma string unit opcional que deve ser “celsius” ou “fahrenheit”.

Prompt do sistema de uso de ferramentas

Quando você chama a API Claude com o parâmetro tools, construímos um prompt do sistema especial a partir das definições de ferramentas, configuração de ferramentas e qualquer prompt do sistema especificado pelo usuário. O prompt construído é projetado para instruir o modelo a usar as ferramentas especificadas e fornecer o contexto necessário para que a ferramenta funcione corretamente:
In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

Melhores práticas para definições de ferramentas

Para obter o melhor desempenho do Claude ao usar ferramentas, siga estas diretrizes:
  • Forneça descrições extremamente detalhadas. Este é de longe o fator mais importante no desempenho da ferramenta. Suas descrições devem explicar cada detalhe sobre a ferramenta, incluindo:
    • O que a ferramenta faz
    • Quando deve ser usada (e quando não deve)
    • O que cada parâmetro significa e como afeta o comportamento da ferramenta
    • Quaisquer ressalvas ou limitações importantes, como quais informações a ferramenta não retorna se o nome da ferramenta for pouco claro. Quanto mais contexto você puder fornecer ao Claude sobre suas ferramentas, melhor ele será em decidir quando e como usá-las. Procure por pelo menos 3-4 frases por descrição de ferramenta, mais se a ferramenta for complexa.
  • Priorize descrições sobre exemplos. Embora você possa incluir exemplos de como usar uma ferramenta em sua descrição ou no prompt acompanhante, isso é menos importante do que ter uma explicação clara e abrangente do propósito e parâmetros da ferramenta. Adicione exemplos apenas depois de ter desenvolvido completamente a descrição.
JSON
{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}
JSON
{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}
A boa descrição explica claramente o que a ferramenta faz, quando usá-la, quais dados ela retorna e o que o parâmetro ticker significa. A descrição ruim é muito breve e deixa Claude com muitas questões em aberto sobre o comportamento e uso da ferramenta.

Executor de ferramentas (beta)

O executor de ferramentas fornece uma solução pronta para executar ferramentas com Claude. Em vez de lidar manualmente com chamadas de ferramentas, resultados de ferramentas e gerenciamento de conversas, o executor de ferramentas automaticamente:
  • Executa ferramentas quando Claude as chama
  • Lida com o ciclo de solicitação/resposta
  • Gerencia o estado da conversa
  • Fornece segurança de tipo e validação
Recomendamos que você use o executor de ferramentas para a maioria das implementações de uso de ferramentas.
O executor de ferramentas está atualmente em beta e disponível apenas nos SDKs Python e TypeScript.

Uso básico

Use o decorador @beta_tool para definir ferramentas e client.beta.messages.tool_runner() para executá-las.
Se estiver usando o cliente assíncrono, substitua @beta_tool por @beta_async_tool e defina a função com async def.
import anthropic
import json
from anthropic import beta_tool

# Initialize client
client = anthropic.Anthropic()

# Define tools using the decorator
@beta_tool
def get_weather(location: str, unit: str = "fahrenheit") -> str:
    """Get the current weather in a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA
        unit: Temperature unit, either 'celsius' or 'fahrenheit'
    """
    # In a full implementation, you'd call a weather API here
    return json.dumps({"temperature": "20°C", "condition": "Sunny"})

@beta_tool
def calculate_sum(a: int, b: int) -> str:
    """Add two numbers together.

    Args:
        a: First number
        b: Second number
    """
    return str(a + b)

# Use the tool runner
with client.beta.messages.tool_runner(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[get_weather, calculate_sum],
    messages=[
        {"role": "user", "content": "What's the weather like in Paris? Also, what's 15 + 27?"}
    ]
) as runner:
    for message in runner:
        print(message.content[0].text)
A função decorada deve retornar um bloco de conteúdo ou array de blocos de conteúdo, incluindo texto, imagens ou blocos de documento. Isso permite que ferramentas retornem respostas ricas e multimodais. Strings retornadas serão convertidas em um bloco de conteúdo de texto. Se você quiser retornar um objeto JSON estruturado para Claude, codifique-o como uma string JSON antes de retorná-lo. Números, booleanos ou outras primitivas não-string também devem ser convertidas para strings.O decorador @beta_tool inspecionará os argumentos da função e a docstring para extrair uma representação de esquema json da função fornecida, no exemplo acima calculate_sum será transformado em:
{
  "name": "calculate_sum",
  "description": "Adds two integers together.",
  "input_schema": {
    "additionalProperties": false,
    "properties": {
      "left": {
        "description": "The first integer to add.",
        "title": "Left",
        "type": "integer"
      },
      "right": {
        "description": "The second integer to add.",
        "title": "Right",
        "type": "integer"
      }
    },
    "required": ["left", "right"],
    "type": "object"
  }
}
O executor de ferramentas do SDK está em beta. O resto deste documento cobre implementação manual de ferramentas.

Controlando a saída de Claude

Forçando o uso de ferramentas

Em alguns casos, você pode querer que Claude use uma ferramenta específica para responder à pergunta do usuário, mesmo que Claude pense que pode fornecer uma resposta sem usar uma ferramenta. Você pode fazer isso especificando a ferramenta no campo tool_choice assim:
tool_choice = {"type": "tool", "name": "get_weather"}
Ao trabalhar com o parâmetro tool_choice, temos quatro opções possíveis:
  • auto permite que Claude decida se deve chamar qualquer ferramenta fornecida ou não. Este é o valor padrão quando tools são fornecidas.
  • any diz a Claude que ele deve usar uma das ferramentas fornecidas, mas não força uma ferramenta particular.
  • tool nos permite forçar Claude a sempre usar uma ferramenta particular.
  • none impede Claude de usar qualquer ferramenta. Este é o valor padrão quando nenhuma tools é fornecida.
Ao usar cache de prompt, mudanças no parâmetro tool_choice invalidarão blocos de mensagens em cache. Definições de ferramentas e prompts do sistema permanecem em cache, mas o conteúdo da mensagem deve ser reprocessado.
Este diagrama ilustra como cada opção funciona:
Observe que quando você tem tool_choice como any ou tool, preencheremos previamente a mensagem do assistente para forçar o uso de uma ferramenta. Isso significa que os modelos não emitirão uma resposta em linguagem natural ou explicação antes dos blocos de conteúdo tool_use, mesmo se explicitamente solicitado.
Ao usar pensamento estendido com uso de ferramentas, tool_choice: {"type": "any"} e tool_choice: {"type": "tool", "name": "..."} não são suportados e resultarão em um erro. Apenas tool_choice: {"type": "auto"} (o padrão) e tool_choice: {"type": "none"} são compatíveis com pensamento estendido.
Nossos testes mostraram que isso não deve reduzir o desempenho. Se você gostaria que o modelo fornecesse contexto em linguagem natural ou explicações enquanto ainda solicitava que o modelo usasse uma ferramenta específica, você pode usar {"type": "auto"} para tool_choice (o padrão) e adicionar instruções explícitas em uma mensagem user. Por exemplo: What's the weather like in London? Use the get_weather tool in your response.

Saída JSON

Ferramentas não precisam necessariamente ser funções do cliente — você pode usar ferramentas sempre que quiser que o modelo retorne uma saída JSON que siga um esquema fornecido. Por exemplo, você pode usar uma ferramenta record_summary com um esquema particular. Veja Uso de ferramentas com Claude para um exemplo completo funcionando.

Respostas do modelo com ferramentas

Ao usar ferramentas, Claude frequentemente comentará sobre o que está fazendo ou responderá naturalmente ao usuário antes de invocar ferramentas. Por exemplo, dada a solicitação “What’s the weather like in San Francisco right now, and what time is it there?”, Claude pode responder com:
JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}
Este estilo de resposta natural ajuda os usuários a entender o que Claude está fazendo e cria uma interação mais conversacional. Você pode guiar o estilo e conteúdo dessas respostas através de seus prompts do sistema e fornecendo <examples> em seus prompts. É importante notar que Claude pode usar várias frases e abordagens ao explicar suas ações. Seu código deve tratar essas respostas como qualquer outro texto gerado pelo assistente, e não confiar em convenções de formatação específicas.

Uso paralelo de ferramentas

Por padrão, Claude pode usar múltiplas ferramentas para responder a uma consulta do usuário. Você pode desabilitar esse comportamento por:
  • Configurar disable_parallel_tool_use=true quando o tipo de tool_choice é auto, o que garante que Claude use no máximo uma ferramenta
  • Configurar disable_parallel_tool_use=true quando o tipo de tool_choice é any ou tool, o que garante que Claude use exatamente uma ferramenta
Mais simples com executor de ferramentas: O exemplo abaixo mostra tratamento manual de ferramentas paralelas. Para a maioria dos casos de uso, executor de ferramentas lida automaticamente com execução paralela de ferramentas com muito menos código.
Aqui está um exemplo completo mostrando como formatar corretamente chamadas paralelas de ferramentas no histórico de mensagens:
import anthropic

client = anthropic.Anthropic()

# Define tools
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Initial request
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "What's the weather in SF and NYC, and what time is it there?"
        }
    ]
)

# Claude's response with parallel tool calls
print("Claude wants to use tools:", response.stop_reason == "tool_use")
print("Number of tool calls:", len([c for c in response.content if c.type == "tool_use"]))

# Build the conversation with tool results
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?"
    },
    {
        "role": "assistant",
        "content": response.content  # Contains multiple tool_use blocks
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # Must match the ID from tool_use
                "content": "San Francisco: 68°F, partly cloudy"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "New York: 45°F, clear skies"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "San Francisco time: 2:30 PM PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "New York time: 5:30 PM EST"
            }
        ]
    }
]

# Get final response
final_response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)
A mensagem do assistente com chamadas paralelas de ferramentas ficaria assim:
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the weather and time for both San Francisco and New York City."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "New York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}
Aqui está um script completo e executável para testar e verificar se as chamadas paralelas de ferramentas estão funcionando corretamente:
#!/usr/bin/env python3
"""Test script to verify parallel tool calls with the Claude API"""

import os
from anthropic import Anthropic

# Initialize client
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Define tools
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Test conversation with parallel tool calls
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?"
    }
]

# Make initial request
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# Check for parallel tool calls
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude made {len(tool_uses)} tool calls")

if len(tool_uses) > 1:
    print("✓ Parallel tool calls detected!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ No parallel tool calls detected")

# Simulate tool execution and format results correctly
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, partly cloudy"
        else:
            result = "New York: 45°F, clear skies"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM EST"

    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# Continue conversation with tool results
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # All results in one message!
])

# Get final response
print("\nGetting final response...")
final_response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nClaude's response:\n{final_response.content[0].text}")

# Verify formatting
print("\n--- Verification ---")
print(f"✓ Tool results sent in single user message: {len(tool_results)} results")
print("✓ No text before tool results in content array")
print("✓ Conversation formatted correctly for future parallel tool use")
Este script demonstra:
  • Como formatar corretamente chamadas paralelas de ferramentas e resultados
  • Como verificar que chamadas paralelas estão sendo feitas
  • A estrutura de mensagem correta que incentiva o uso paralelo de ferramentas no futuro
  • Erros comuns a evitar (como texto antes dos resultados das ferramentas)
Execute este script para testar sua implementação e garantir que Claude está fazendo chamadas paralelas de ferramentas efetivamente.

Maximizando o uso paralelo de ferramentas

Embora os modelos Claude 4 tenham excelentes capacidades de uso paralelo de ferramentas por padrão, você pode aumentar a probabilidade de execução paralela de ferramentas em todos os modelos com prompting direcionado:
Para modelos Claude 4 (Opus 4.1, Opus 4 e Sonnet 4), adicione isto ao seu prompt do sistema:
For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
Para uso paralelo de ferramentas ainda mais forte (recomendado se o padrão não for suficiente), use:
<use_parallel_tool_calls>
For maximum efficiency, whenever you perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Prioritize calling tools in parallel whenever possible. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple read-only commands like `ls` or `list_dir`, always run all of the commands in parallel. Err on the side of maximizing parallel tool calls rather than running too many tools sequentially.
</use_parallel_tool_calls>
Você também pode incentivar o uso paralelo de ferramentas dentro de mensagens de usuário específicas:
# Instead of:
"What's the weather in Paris? Also check London."

# Use:
"Check the weather in Paris and London simultaneously."

# Or be explicit:
"Please use parallel tool calls to get the weather for Paris, London, and Tokyo at the same time."
Uso paralelo de ferramentas com Claude Sonnet 3.7Claude Sonnet 3.7 pode ser menos provável de fazer chamadas paralelas de ferramentas em uma resposta, mesmo quando você não tiver configurado disable_parallel_tool_use. Para contornar isso, recomendamos ativar uso eficiente de ferramentas em termos de tokens, que ajuda a incentivar Claude a usar ferramentas paralelas. Este recurso beta também reduz a latência e economiza uma média de 14% em tokens de saída.Se você preferir não optar pelo beta de uso eficiente de ferramentas em termos de tokens, você também pode introduzir uma “ferramenta em lote” que pode atuar como uma meta-ferramenta para envolver invocações para outras ferramentas simultaneamente. Descobrimos que se esta ferramenta estiver presente, o modelo a usará para chamar simultaneamente múltiplas ferramentas em paralelo para você.Veja este exemplo em nosso cookbook para como usar esta solução alternativa.

Tratando blocos de conteúdo de uso de ferramentas e resultado de ferramentas

Mais simples com executor de ferramentas: O tratamento manual de ferramentas descrito nesta seção é gerenciado automaticamente por executor de ferramentas. Use esta seção quando precisar de controle personalizado sobre a execução de ferramentas.
A resposta de Claude difere dependendo se ela usa uma ferramenta de cliente ou servidor.

Tratando resultados de ferramentas de cliente

A resposta terá um stop_reason de tool_use e um ou mais blocos de conteúdo tool_use que incluem:
  • id: Um identificador único para este bloco de uso de ferramenta particular. Isso será usado para corresponder aos resultados da ferramenta mais tarde.
  • name: O nome da ferramenta sendo usada.
  • input: Um objeto contendo a entrada sendo passada para a ferramenta, em conformidade com o input_schema da ferramenta.
JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-sonnet-4-5",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the current weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}
Quando você recebe uma resposta de uso de ferramenta para uma ferramenta de cliente, você deve:
  1. Extrair o name, id e input do bloco tool_use.
  2. Executar a ferramenta real em sua base de código correspondente a esse nome de ferramenta, passando a input da ferramenta.
  3. Continuar a conversa enviando uma nova mensagem com o role de user e um bloco content contendo o tipo tool_result e as seguintes informações:
    • tool_use_id: O id da solicitação de uso de ferramenta para a qual este é um resultado.
    • content: O resultado da ferramenta, como uma string (por exemplo, "content": "15 degrees"), uma lista de blocos de conteúdo aninhados (por exemplo, "content": [{"type": "text", "text": "15 degrees"}]), ou uma lista de blocos de documento (por exemplo, "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}]). Estes blocos de conteúdo podem usar os tipos text, image ou document.
    • is_error (opcional): Defina como true se a execução da ferramenta resultou em um erro.
Requisitos importantes de formatação:
  • Blocos de resultado de ferramenta devem seguir imediatamente seus blocos de uso de ferramenta correspondentes no histórico de mensagens. Você não pode incluir nenhuma mensagem entre a mensagem de uso de ferramenta do assistente e a mensagem de resultado de ferramenta do usuário.
  • Na mensagem do usuário contendo resultados de ferramentas, os blocos tool_result devem vir PRIMEIRO no array de conteúdo. Qualquer texto deve vir DEPOIS de todos os resultados de ferramentas.
Por exemplo, isto causará um erro 400:
{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Text before tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}
Isto está correto:
{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "What should I do next?"}  // ✅ Text after tool_result
]}
Se você receber um erro como “tool_use ids were found without tool_result blocks immediately after”, verifique se seus resultados de ferramentas estão formatados corretamente.
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 degrees"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "The weather is"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 degrees"
          }
        }
      ]
    }
  ]
}
Após receber o resultado da ferramenta, Claude usará essa informação para continuar gerando uma resposta ao prompt original do usuário.

Tratando resultados de ferramentas de servidor

Claude executa a ferramenta internamente e incorpora os resultados diretamente em sua resposta sem exigir interação adicional do usuário.
Diferenças de outras APIsAo contrário de APIs que separam o uso de ferramentas ou usam funções especiais como tool ou function, a API Claude integra ferramentas diretamente na estrutura de mensagem user e assistant.As mensagens contêm arrays de blocos text, image, tool_use e tool_result. Mensagens user incluem conteúdo do cliente e tool_result, enquanto mensagens assistant contêm conteúdo gerado por IA e tool_use.

Tratando o motivo de parada max_tokens

Se a resposta de Claude for cortada devido ao limite max_tokens, e a resposta truncada contiver um bloco de uso de ferramenta incompleto, você precisará repetir a solicitação com um valor max_tokens mais alto para obter o uso de ferramenta completo.
# Check if response was truncated during tool use
if response.stop_reason == "max_tokens":
    # Check if the last content block is an incomplete tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Send the request with higher max_tokens
        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools
        )

Tratando o motivo de parada pause_turn

Ao usar ferramentas de servidor como busca na web, a API pode retornar um motivo de parada pause_turn, indicando que a API pausou um turno de longa duração. Aqui está como tratar o motivo de parada pause_turn:
import anthropic

client = anthropic.Anthropic()

# Initial request with web search
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {"role": "user", "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"},
        {"role": "assistant", "content": response.content}
    ]

    # Send the continuation request
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )

    print(continuation)
else:
    print(response)
Ao tratar pause_turn:
  • Continue a conversa: Passe a resposta pausada como está em uma solicitação subsequente para deixar Claude continuar seu turno
  • Modifique se necessário: Você pode opcionalmente modificar o conteúdo antes de continuar se quiser interromper ou redirecionar a conversa
  • Preserve o estado da ferramenta: Inclua as mesmas ferramentas na solicitação de continuação para manter a funcionalidade

Resolvendo problemas de erros

Tratamento de erros integrado: Executor de ferramentas fornece tratamento automático de erros para a maioria dos cenários comuns. Esta seção cobre tratamento manual de erros para casos de uso avançados.
Existem alguns tipos diferentes de erros que podem ocorrer ao usar ferramentas com Claude:
Se a ferramenta em si lançar um erro durante a execução (por exemplo, um erro de rede ao buscar dados de clima), você pode retornar a mensagem de erro no content junto com "is_error": true:
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}
Claude então incorporará este erro em sua resposta ao usuário, por exemplo, “I’m sorry, I was unable to retrieve the current weather because the weather service API is not available. Please try again later.”
Se a tentativa de Claude de usar uma ferramenta for inválida (por exemplo, parâmetros obrigatórios ausentes), geralmente significa que não havia informações suficientes para Claude usar a ferramenta corretamente. Sua melhor aposta durante o desenvolvimento é tentar a solicitação novamente com valores description mais detalhados em suas definições de ferramentas.No entanto, você também pode continuar a conversa para frente com um tool_result que indica o erro, e Claude tentará usar a ferramenta novamente com as informações ausentes preenchidas:
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}
Se uma solicitação de ferramenta for inválida ou estiver faltando parâmetros, Claude tentará novamente 2-3 vezes com correções antes de se desculpar com o usuário.
Para evitar que Claude reflita sobre a qualidade da busca com tags <search_quality_reflection>, adicione “Do not reflect on the quality of the returned search results in your response” ao seu prompt.
Quando ferramentas de servidor encontram erros (por exemplo, problemas de rede com Busca na Web), Claude tratará esses erros de forma transparente e tentará fornecer uma resposta alternativa ou explicação ao usuário. Ao contrário das ferramentas de cliente, você não precisa lidar com resultados is_error para ferramentas de servidor.Para busca na web especificamente, os códigos de erro possíveis incluem:
  • too_many_requests: Limite de taxa excedido
  • invalid_input: Parâmetro de consulta de busca inválido
  • max_uses_exceeded: Máximo de usos da ferramenta de busca na web excedido
  • query_too_long: Consulta excede o comprimento máximo
  • unavailable: Um erro interno ocorreu
Se Claude não estiver fazendo chamadas paralelas de ferramentas quando esperado, verifique estes problemas comuns:1. Formatação incorreta de resultado de ferramentaO problema mais comum é formatar incorretamente os resultados de ferramentas no histórico de conversas. Isso “ensina” Claude a evitar chamadas paralelas.Especificamente para uso paralelo de ferramentas:
  • Errado: Enviar mensagens de usuário separadas para cada resultado de ferramenta
  • Correto: Todos os resultados de ferramentas devem estar em uma única mensagem de usuário
// ❌ This reduces parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Separate message
]

// ✅ This maintains parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Single message
]
Veja os requisitos gerais de formatação acima para outras regras de formatação.2. Prompting fracoO prompting padrão pode não ser suficiente. Use linguagem mais forte:
<use_parallel_tool_calls>
For maximum efficiency, whenever you perform multiple independent operations,
invoke all relevant tools simultaneously rather than sequentially.
Prioritize calling tools in parallel whenever possible.
</use_parallel_tool_calls>
3. Medindo o uso paralelo de ferramentasPara verificar se as chamadas paralelas de ferramentas estão funcionando:
# Calculate average tools per tool-calling message
tool_call_messages = [msg for msg in messages if any(
    block.type == "tool_use" for block in msg.content
)]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"])
    for msg in tool_call_messages
)
avg_tools_per_message = total_tool_calls / len(tool_call_messages)
print(f"Average tools per message: {avg_tools_per_message}")
# Should be > 1.0 if parallel calls are working
4. Comportamento específico do modelo
  • Claude Opus 4.1, Opus 4 e Sonnet 4: Excelentes em uso paralelo de ferramentas com prompting mínimo
  • Claude Sonnet 3.7: Pode precisar de prompting mais forte ou uso eficiente de ferramentas em termos de tokens
  • Claude Haiku: Menos provável de usar ferramentas paralelas sem prompting explícito