Definir ferramentas

Escolhendo um modelo

Use o modelo Claude Opus mais recente (4.7) para ferramentas complexas e consultas ambíguas; ele lida melhor com múltiplas ferramentas e busca esclarecimentos quando necessário.

Use modelos Claude Haiku para ferramentas diretas, mas observe que eles podem inferir parâmetros ausentes.

Especificando ferramentas do cliente

Ferramentas do cliente (tanto esquema Anthropic quanto definidas pelo usuário) são especificadas no parâmetro tools de nível superior da solicitação da API. Cada definição de ferramenta inclui:

Para o conjunto completo de propriedades opcionais disponíveis em qualquer definição de ferramenta, incluindo cache_control, strict, defer_loading e allowed_callers, consulte a referência de ferramentas.

Prompt do sistema de uso de ferramentas

Quando você chama a API Claude com o parâmetro tools, a API constrói 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 a(s) ferramenta(s) especificada(s) e fornecer o contexto necessário para que a ferramenta funcione adequadamente:

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 que informações a ferramenta não retorna se o nome da ferramenta for pouco claro. Quanto mais contexto você puder dar 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, mas considere usar input_examples para ferramentas complexas. Descrições claras são mais importantes, mas para ferramentas com entradas complexas, objetos aninhados ou parâmetros sensíveis ao formato, você pode usar o campo input_examples para fornecer exemplos validados por esquema. Veja Fornecendo exemplos de uso de ferramentas para detalhes.
• Consolide operações relacionadas em menos ferramentas. Em vez de criar uma ferramenta separada para cada ação (create_pr, review_pr, merge_pr), agrupe-as em uma única ferramenta com um parâmetro action. Menos ferramentas, mais capazes, reduzem a ambiguidade de seleção e tornam sua superfície de ferramentas mais fácil para Claude navegar.
• Use namespacing significativo em nomes de ferramentas. Quando suas ferramentas abrangem múltiplos serviços ou recursos, prefixe nomes com o serviço (por exemplo, github_list_prs, slack_send_message). Isso torna a seleção de ferramentas inequívoca conforme sua biblioteca cresce, e é especialmente importante ao usar busca de ferramentas.
• Projete respostas de ferramentas para retornar apenas informações de alto sinal. Retorne identificadores semânticos e estáveis (por exemplo, slugs ou UUIDs) em vez de referências internas opacas, e inclua apenas os campos que Claude precisa para raciocinar sobre seu próximo passo. Respostas inchadas desperdiçam contexto e dificultam para Claude extrair o que importa.

A boa descrição explica claramente o que a ferramenta faz, quando usá-la, que dados ela retorna e o que o parâmetro ticker significa. A descrição ruim é muito breve e deixa Claude com muitas questões abertas sobre o comportamento e uso da ferramenta.

Fornecendo exemplos de uso de ferramentas

Você pode fornecer exemplos concretos de entradas de ferramentas válidas para ajudar Claude a entender como usar suas ferramentas de forma mais eficaz. Isso é particularmente útil para ferramentas complexas com objetos aninhados, parâmetros opcionais ou entradas sensíveis ao formato.

Uso básico

Adicione um campo input_examples opcional à sua definição de ferramenta com uma matriz de objetos de entrada de exemplo. Cada exemplo deve ser válido de acordo com o input_schema da ferramenta:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    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",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature",
                    },
                },
                "required": ["location"],
            },
            "input_examples": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Os exemplos são incluídos no prompt junto com seu esquema de ferramenta, mostrando ao Claude padrões concretos para chamadas de ferramentas bem formadas. Isso ajuda Claude a entender quando incluir parâmetros opcionais, que formatos usar e como estruturar entradas complexas.

Requisitos e limitações

• Validação de esquema - Cada exemplo deve ser válido de acordo com o input_schema da ferramenta. Exemplos inválidos retornam um erro 400
• Não suportado para ferramentas do lado do servidor - Exemplos de entrada funcionam em ferramentas de cliente definidas pelo usuário e esquema Anthropic, mas não em ferramentas do servidor como busca na web ou execução de código
• Custo de token - Os exemplos adicionam tokens de prompt: ~20-50 tokens para exemplos simples, ~100-200 tokens para objetos aninhados complexos

Controlando a saída do 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 responderia diretamente sem chamar 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, existem 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 ao Claude que ele deve usar uma das ferramentas fornecidas, mas não força uma ferramenta particular.
• tool força Claude a sempre usar uma ferramenta particular.
• none impede Claude de usar qualquer ferramenta. Este é o valor padrão quando nenhuma tools é fornecida.

Este diagrama ilustra como cada opção funciona:

Observe que quando você tem tool_choice como any ou tool, a API preenche 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 de blocos de conteúdo tool_use, mesmo se explicitamente solicitado.

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 solicitasse que o modelo use 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.

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:

{
  "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.

Próximas etapas