Uso de ferramentas com Claude

Claude é capaz de interagir com ferramentas e funções, permitindo que você estenda os recursos do Claude para realizar uma variedade maior de tarefas.

Aqui está um exemplo de como fornecer ferramentas ao Claude usando a API de Mensagens:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What is the weather like in San Francisco?"
      }
    ]
  }'

Como o uso de ferramentas funciona

Claude suporta dois tipos de ferramentas:

1. Ferramentas de cliente: Ferramentas que são executadas em seus sistemas, que incluem:

   • Ferramentas personalizadas definidas pelo usuário que você cria e implementa
   • Ferramentas definidas pela Anthropic como uso de computador e editor de texto que requerem implementação no cliente

2. Ferramentas de servidor: Ferramentas que são executadas nos servidores da Anthropic, como as ferramentas de busca na web e busca na web. Essas ferramentas devem ser especificadas na solicitação da API, mas não requerem implementação da sua parte.

Ferramentas de cliente

Integre ferramentas de cliente com Claude nestas etapas:

Nota: As etapas 3 e 4 são opcionais. Para alguns fluxos de trabalho, a solicitação de uso de ferramenta do Claude (etapa 2) pode ser tudo que você precisa, sem enviar resultados de volta ao Claude.

Ferramentas de servidor

As ferramentas de servidor seguem um fluxo de trabalho diferente:

Usando ferramentas MCP com Claude

Se você está construindo uma aplicação que usa o Model Context Protocol (MCP), você pode usar ferramentas de servidores MCP diretamente com a API de Mensagens do Claude. As definições de ferramentas MCP usam um formato de esquema semelhante ao formato de ferramenta do Claude. Você apenas precisa renomear inputSchema para input_schema.

Convertendo ferramentas MCP para o formato Claude

Quando você constrói um cliente MCP e chama list_tools() em um servidor MCP, você receberá definições de ferramentas com um campo inputSchema. Para usar essas ferramentas com Claude, converta-as para o formato do Claude:

from mcp import ClientSession

async def get_claude_tools(mcp_session: ClientSession):
    """Convert MCP tools to Claude's tool format."""
    mcp_tools = await mcp_session.list_tools()

    claude_tools = []
    for tool in mcp_tools.tools:
        claude_tools.append({
            "name": tool.name,
            "description": tool.description or "",
            "input_schema": tool.inputSchema  # Rename inputSchema to input_schema
        })

    return claude_tools

Então passe essas ferramentas convertidas para Claude:

import anthropic

client = anthropic.Anthropic()
claude_tools = await get_claude_tools(mcp_session)

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    tools=claude_tools,
    messages=[{"role": "user", "content": "What tools do you have available?"}]
)

Quando Claude responde com um bloco tool_use, execute a ferramenta em seu servidor MCP usando call_tool() e retorne o resultado ao Claude em um bloco tool_result.

Para um guia completo sobre como construir clientes MCP, consulte Construir um cliente MCP.

Exemplos de uso de ferramentas

Aqui estão alguns exemplos de código demonstrando vários padrões e técnicas de uso de ferramentas. Por brevidade, as ferramentas são simples e as descrições das ferramentas são mais curtas do que o ideal para garantir o melhor desempenho.

Preços

Tool use requests are priced based on:

1. The total number of input tokens sent to the model (including in the tools parameter)
2. The number of output tokens generated
3. For server-side tools, additional usage-based pricing (e.g., web search charges per search performed)

Client-side tools are priced the same as any other Claude API request, while server-side tools may incur additional charges based on their specific usage.

The additional tokens from tool use come from:

• The tools parameter in API requests (tool names, descriptions, and schemas)
• tool_use content blocks in API requests and responses
• tool_result content blocks in API requests

When you use tools, we also automatically include a special system prompt for the model which enables tool use. The number of tool use tokens required for each model are listed below (excluding the additional tokens listed above). Note that the table assumes at least 1 tool is provided. If no tools are provided, then a tool choice of none uses 0 additional system prompt tokens.

These token counts are added to your normal input and output tokens to calculate the total cost of a request.

Consulte nossa tabela de visão geral de modelos para os preços atuais por modelo.

Quando você envia um prompt de uso de ferramenta, assim como qualquer outra solicitação de API, a resposta exibirá contagens de tokens de entrada e saída como parte das métricas usage relatadas.

Próximas Etapas

Explore nosso repositório de exemplos de código de uso de ferramenta prontos para implementação em nossos cookbooks: