Claude Platform Docs
MessagesFerramentas

Uso estrito de ferramentas

Imponha a conformidade com JSON Schema nas entradas de ferramentas do Claude com amostragem restrita por gramática.

Definir strict: true em uma definição de ferramenta garante que as entradas de ferramentas do Claude correspondam ao seu JSON Schema, restringindo a amostragem de tokens do modelo a saídas válidas segundo o schema (uma técnica chamada "grammar-constrained sampling", ou amostragem restrita por gramática). Esta página aborda por que o modo estrito é importante para agentes, como habilitá-lo e casos de uso comuns. Para o subconjunto de JSON Schema suportado, consulte Limitações do JSON Schema. Para orientações sobre schemas não estritos, consulte Definir ferramentas.

O "strict tool use" (uso estrito de ferramentas) valida os parâmetros das ferramentas, garantindo que o Claude chame suas funções com argumentos corretamente tipados. Use o uso estrito de ferramentas quando você precisar:

  • Validar parâmetros de ferramentas
  • Construir fluxos de trabalho agênticos
  • Garantir chamadas de função com segurança de tipos
  • Lidar com ferramentas complexas com propriedades aninhadas

Por que o uso estrito de ferramentas é importante para agentes

Construir sistemas agênticos confiáveis requer conformidade garantida com o schema. Sem o modo estrito, o Claude pode retornar tipos incompatíveis ("2" em vez de 2) ou omitir campos obrigatórios, quebrando suas funções e causando erros em tempo de execução.

O uso estrito de ferramentas garante parâmetros com segurança de tipos:

  • As funções recebem argumentos corretamente tipados todas as vezes
  • Não há necessidade de validar e repetir chamadas de ferramentas
  • Agentes prontos para produção que funcionam de forma consistente em escala

Por exemplo, suponha que um sistema de reservas precise de passengers: int. Sem o modo estrito, o Claude pode fornecer passengers: "two" ou passengers: "2". Com strict: true, a resposta sempre contém passengers: 2.

Início rápido

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "strict": True,  # Enable strict mode
            "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"],
                "additionalProperties": False,
            },
        }
    ],
)
print(response.content)

Formato da resposta: Blocos de uso de ferramentas com entradas validadas em response.content[x].input

Output
{
  "type": "tool_use",
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA"
  }
}

Garantias:

  • O input da ferramenta segue estritamente o input_schema
  • O name da ferramenta é sempre válido (das ferramentas fornecidas ou ferramentas do servidor)

Como funciona

  1. Defina o schema da sua ferramenta

    Crie um JSON schema para o input_schema da sua ferramenta. O schema usa o formato JSON Schema padrão com algumas limitações (consulte Limitações do JSON Schema).

  2. Adicione strict: true

    Defina "strict": true como uma propriedade de nível superior na definição da sua ferramenta, junto com name, description e input_schema.

  3. Trate as chamadas de ferramentas

    Quando o Claude usa a ferramenta, o campo input no bloco tool_use segue estritamente o seu input_schema, e o name é sempre válido.

As entradas de conjuntos de ferramentas de uso de computador e uso de navegador (computer_toolset_20260801 e browser_toolset_20260801) não aceitam strict: true; uma requisição que o defina em qualquer uma dessas entradas é rejeitada.

Casos de uso comuns

Retenção de dados

O uso estrito de ferramentas compila as definições de input_schema das ferramentas em gramáticas usando o mesmo pipeline das saídas estruturadas. Os schemas de ferramentas são armazenados temporariamente em cache por até 24 horas desde o último uso. Prompts e respostas não são retidos além da resposta da API.

O uso estrito de ferramentas é elegível para HIPAA, mas informações de saúde protegidas (PHI) não devem ser incluídas nas definições de schema de ferramentas. A API armazena em cache os schemas compilados separadamente do conteúdo das mensagens, e esses schemas em cache não recebem as mesmas proteções de PHI que prompts e respostas. Não inclua PHI em nomes de propriedades do input_schema, valores de enum, valores de const ou expressões regulares de pattern. PHI deve aparecer apenas no conteúdo das mensagens (prompts e respostas), onde está protegida pelas salvaguardas da HIPAA.

Para elegibilidade de ZDR e HIPAA em todos os recursos, consulte API e retenção de dados.

Próximos passos

Ferramenta de busca na web (web fetch)

Busque e leia conteúdo de URLs específicas para trazer conteúdo da web em tempo real para o contexto do Claude.

Uso de ferramentas com cache de prompt

Armazene definições de ferramentas em cache entre turnos para reduzir custo e latência.

Saídas estruturadas

Obtenha respostas JSON validadas usando a mesma amostragem restrita por gramática.

Definir ferramentas

Especifique schemas de ferramentas, escreva descrições eficazes e controle quando o Claude chama suas ferramentas.

Was this page helpful?