Penggunaan alat dengan Claude

Claude mampu berinteraksi dengan alat dan fungsi, memungkinkan Anda memperluas kemampuan Claude untuk melakukan berbagai macam tugas.

Pelajari semua yang Anda butuhkan untuk menguasai penggunaan alat dengan Claude melalui kursus komprehensif baru kami kursus penggunaan alat! Silakan terus berbagi ide dan saran Anda menggunakan formulir ini.

Berikut adalah contoh cara menyediakan alat untuk Claude menggunakan Messages API:

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-20250514",
    "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?"
      }
    ]
  }'

Cara kerja penggunaan alat

Claude mendukung dua jenis alat:

Alat klien: Alat yang dijalankan pada sistem Anda, yang meliputi:
- Alat kustom yang ditentukan pengguna yang Anda buat dan implementasikan
- Alat yang ditentukan Anthropic seperti penggunaan komputer (beta) dan editor teks yang memerlukan implementasi klien
Alat server: Alat yang dijalankan di server Anthropic, seperti alat pencarian web. Alat-alat ini harus ditentukan dalam permintaan API tetapi tidak memerlukan implementasi dari pihak Anda.

Alat yang ditentukan Anthropic menggunakan tipe berversi (misalnya, web_search_20250305, text_editor_20250124) untuk memastikan kompatibilitas di seluruh versi model.

Alat klien

Integrasikan alat klien dengan Claude dalam langkah-langkah berikut:

Berikan Claude alat dan prompt pengguna

Tentukan alat klien dengan nama, deskripsi, dan skema input dalam permintaan API Anda.
Sertakan prompt pengguna yang mungkin memerlukan alat-alat ini, misalnya, “Bagaimana cuaca di San Francisco?”

Claude memutuskan untuk menggunakan alat

Claude menilai apakah ada alat yang dapat membantu dengan kueri pengguna.
Jika ya, Claude membangun permintaan penggunaan alat yang diformat dengan benar.
Untuk alat klien, respons API memiliki stop_reason berupa tool_use, yang menandakan maksud Claude.

Jalankan alat dan kembalikan hasilnya

Ekstrak nama alat dan input dari permintaan Claude
Jalankan kode alat pada sistem Anda
Kembalikan hasilnya dalam pesan user baru yang berisi blok konten tool_result

Claude menggunakan hasil alat untuk merumuskan respons

Claude menganalisis hasil alat untuk menyusun respons akhirnya terhadap prompt pengguna asli.

Catatan: Langkah 3 dan 4 bersifat opsional. Untuk beberapa alur kerja, permintaan penggunaan alat Claude (langkah 2) mungkin sudah cukup, tanpa perlu mengirimkan hasil kembali ke Claude.

Alat server

Alat server mengikuti alur kerja yang berbeda:

Berikan Claude alat dan prompt pengguna

Alat server, seperti pencarian web, memiliki parameter sendiri.
Sertakan prompt pengguna yang mungkin memerlukan alat-alat ini, misalnya, “Cari berita terbaru tentang AI.”

Claude menjalankan alat server

Claude menilai apakah alat server dapat membantu dengan kueri pengguna.
Jika ya, Claude menjalankan alat tersebut, dan hasilnya secara otomatis dimasukkan ke dalam respons Claude.

Claude menggunakan hasil alat server untuk merumuskan respons

Claude menganalisis hasil alat server untuk menyusun respons akhirnya terhadap prompt pengguna asli.
Tidak diperlukan interaksi pengguna tambahan untuk eksekusi alat server.

Contoh penggunaan alat

Berikut adalah beberapa contoh kode yang mendemonstrasikan berbagai pola dan teknik penggunaan alat. Demi singkatnya, alat-alat yang digunakan adalah alat sederhana, dan deskripsi alat lebih pendek dari yang ideal untuk memastikan performa terbaik.

Contoh alat tunggal

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

Claude akan mengembalikan respons yang mirip dengan:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to call the get_weather function, and the user wants SF, which is likely San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Anda kemudian perlu menjalankan fungsi get_weather dengan input yang disediakan, dan mengembalikan hasilnya dalam pesan user baru:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "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, either \"celsius\" or \"fahrenheit\""
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather like in San Francisco?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "<thinking>I need to use get_weather, and the user wants SF, which is likely San Francisco, CA.</thinking>"
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01A09q90qw90lq917835lq9",
                    "name": "get_weather",
                    "input": {
                        "location": "San Francisco, CA",
                        "unit": "celsius"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 degrees"
                }
            ]
        }
    ]
}'

Ini akan mencetak respons akhir Claude, yang menyertakan data cuaca:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-20250514",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The current weather in San Francisco is 15 degrees Celsius (59 degrees Fahrenheit). It's a cool day in the city by the bay!"
    }
  ]
}

Contoh beberapa alat

Anda dapat menyediakan Claude dengan beberapa alat untuk dipilih dalam satu permintaan. Berikut adalah contoh dengan alat get_weather dan get_time, bersama dengan kueri pengguna yang meminta keduanya.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "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, either 'celsius' or 'fahrenheit'"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given time zone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The IANA time zone name, e.g. America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "What is the weather like right now in New York? Also what time is it there?"
    }]
}'

Dalam kasus ini, Claude kemungkinan besar akan mencoba menggunakan dua alat terpisah, satu per satu — get_weather dan kemudian get_time — untuk menjawab pertanyaan pengguna sepenuhnya. Namun, terkadang Claude juga akan mengeluarkan dua blok tool_use sekaligus, terutama jika keduanya tidak saling bergantung. Anda perlu menjalankan setiap alat dan mengembalikan hasilnya dalam blok tool_result terpisah dalam satu pesan user.

Informasi yang hilang

Jika prompt pengguna tidak menyertakan informasi yang cukup untuk mengisi semua parameter yang diperlukan untuk suatu alat, Claude Opus jauh lebih mungkin untuk mengenali bahwa parameter tersebut hilang dan meminta parameter tersebut. Claude Sonnet mungkin bertanya, terutama ketika diminta untuk berpikir sebelum mengeluarkan permintaan alat. Tetapi Claude Sonnet juga mungkin melakukan yang terbaik untuk menyimpulkan nilai yang masuk akal.

Misalnya, menggunakan alat get_weather di atas, jika Anda bertanya kepada Claude “Bagaimana cuacanya?” tanpa menentukan lokasi, Claude, terutama Claude Sonnet, mungkin akan menebak input alat:

JSON
{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}

Perilaku ini tidak dijamin, terutama untuk prompt yang lebih ambigu dan untuk model yang kurang cerdas. Jika Claude Opus tidak memiliki konteks yang cukup untuk mengisi parameter yang diperlukan, jauh lebih mungkin untuk merespons dengan pertanyaan klarifikasi daripada membuat panggilan alat.

Alat berurutan

Beberapa tugas mungkin memerlukan pemanggilan beberapa alat secara berurutan, menggunakan output dari satu alat sebagai input untuk alat lain. Dalam kasus seperti itu, Claude akan memanggil satu alat pada satu waktu. Jika diminta untuk memanggil semua alat sekaligus, Claude cenderung menebak parameter untuk alat yang lebih hilir jika alat tersebut bergantung pada hasil alat yang lebih hulu.

Berikut adalah contoh penggunaan alat get_location untuk mendapatkan lokasi pengguna, kemudian meneruskan lokasi tersebut ke alat get_weather:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Get the current user location based on their IP address. This tool has no parameters or arguments.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "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"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What is the weather like where I am?"
    }]
}'

Dalam kasus ini, Claude akan terlebih dahulu memanggil alat get_location untuk mendapatkan lokasi pengguna. Setelah Anda mengembalikan lokasi dalam tool_result, Claude kemudian akan memanggil get_weather dengan lokasi tersebut untuk mendapatkan jawaban akhir.

Percakapan lengkapnya mungkin terlihat seperti:

Peran	Konten
User	What’s the weather like where I am?
Assistant	<thinking>To answer this, I first need to determine the user’s location using the get_location tool. Then I can pass that location to the get_weather tool to find the current weather there.</thinking>[Tool use for get_location]
User	[Tool result for get_location with matching id and result of San Francisco, CA]
Assistant	[Tool use for get_weather with the following input]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
User	[Tool result for get_weather with matching id and result of “59°F (15°C), mostly cloudy”]
Assistant	Based on your current location in San Francisco, CA, the weather right now is 59°F (15°C) and mostly cloudy. It’s a fairly cool and overcast day in the city. You may want to bring a light jacket if you’re heading outside.

Contoh ini menunjukkan bagaimana Claude dapat menggabungkan beberapa panggilan alat untuk menjawab pertanyaan yang memerlukan pengumpulan data dari sumber yang berbeda. Langkah-langkah utamanya adalah:

Claude pertama-tama menyadari bahwa ia membutuhkan lokasi pengguna untuk menjawab pertanyaan cuaca, jadi ia memanggil alat get_location.
Pengguna (yaitu kode klien) menjalankan fungsi get_location yang sebenarnya dan mengembalikan hasil “San Francisco, CA” dalam blok tool_result.
Dengan lokasi yang sekarang diketahui, Claude melanjutkan untuk memanggil alat get_weather, meneruskan “San Francisco, CA” sebagai parameter location (serta parameter unit yang ditebak, karena unit bukan parameter yang diperlukan).
Pengguna sekali lagi menjalankan fungsi get_weather yang sebenarnya dengan argumen yang disediakan dan mengembalikan data cuaca dalam blok tool_result lain.
Akhirnya, Claude memasukkan data cuaca ke dalam respons bahasa alami untuk pertanyaan asli.

Penggunaan alat dengan rantai pemikiran

Mode JSON

Anda dapat menggunakan alat untuk membuat Claude menghasilkan output JSON yang mengikuti skema, bahkan jika Anda tidak berniat menjalankan output tersebut melalui alat atau fungsi.

Ketika menggunakan alat dengan cara ini:

Anda biasanya ingin menyediakan alat tunggal
Anda harus mengatur tool_choice (lihat Memaksa penggunaan alat) untuk menginstruksikan model agar secara eksplisit menggunakan alat tersebut
Ingat bahwa model akan meneruskan input ke alat, jadi nama alat dan deskripsi harus dari perspektif model.

Berikut ini menggunakan alat record_summary untuk mendeskripsikan gambar mengikuti format tertentu.

#!/bin/bash
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Record summary of an image using well-structured JSON.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "red value [0.0, 1.0]" },
"g": { "type": "number", "description": "green value [0.0, 1.0]" },
"b": { "type": "number", "description": "blue value [0.0, 1.0]" },
"name": { "type": "string", "description": "Human-readable color name in snake_case, e.g. \"olive_green\" or \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Key colors in the image. Limit to less than four."
                },
                "description": {
                    "type": "string",
                    "description": "Image description. One to two sentences max."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Estimated year that the image was taken, if it is a photo. Only set this if the image appears to be non-fictional. Rough estimates are okay!"
                }
            },
            "required": [ "key_colors", "description" ]
        }
    }],
    "tool_choice": {"type": "tool", "name": "record_summary"},
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Describe this image."}
        ]}
    ]
}'

Harga

Tool use requests are priced based on:

The total number of input tokens sent to the model (including in the tools parameter)
The number of output tokens generated
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.

Model	Tool choice	Tool use system prompt token count
Claude Opus 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.7	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (Oct)	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (June)	`auto`, `none` `any`, `tool`	294 tokens 261 tokens
Claude Haiku 3.5	`auto`, `none` `any`, `tool`	264 tokens 340 tokens
Claude Opus 3	`auto`, `none` `any`, `tool`	530 tokens 281 tokens
Claude Sonnet 3	`auto`, `none` `any`, `tool`	159 tokens 235 tokens
Claude Haiku 3	`auto`, `none` `any`, `tool`	264 tokens 340 tokens

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

Lihat tabel ikhtisar model kami untuk harga per model saat ini.

Ketika Anda mengirimkan prompt penggunaan alat, seperti permintaan API lainnya, respons akan mengeluarkan jumlah token input dan output sebagai bagian dari metrik usage yang dilaporkan.

Langkah Selanjutnya

Jelajahi repositori contoh kode penggunaan alat siap implementasi kami dalam cookbook kami:

Alat Kalkulator

Pelajari cara mengintegrasikan alat kalkulator sederhana dengan Claude untuk perhitungan numerik yang tepat.

Agen Layanan Pelanggan

Bangun bot layanan pelanggan yang responsif yang memanfaatkan alat klien untuk meningkatkan dukungan.

Ekstraktor JSON

Lihat bagaimana Claude dan penggunaan alat dapat mengekstrak data terstruktur dari teks tidak terstruktur.

Langkah awal

Model & harga

Jelajahi fitur

Pelajari tentang Claude

Uji & evaluasi

Pusat Hukum

Komponen agen

Penggunaan alat dengan Claude

Cara kerja penggunaan alat

Alat klien

Alat server

Contoh penggunaan alat

Harga

Langkah Selanjutnya

Alat Kalkulator

Agen Layanan Pelanggan

Ekstraktor JSON

Langkah awal

Model & harga

Jelajahi fitur

Pelajari tentang Claude

Uji & evaluasi

Pusat Hukum

Komponen agen

​Cara kerja penggunaan alat

​Alat klien

​Alat server

​Contoh penggunaan alat

​Harga

​Langkah Selanjutnya

Alat Kalkulator

Agen Layanan Pelanggan

Ekstraktor JSON

Cara kerja penggunaan alat

Alat klien

Alat server

Contoh penggunaan alat

Harga

Langkah Selanjutnya