Penggunaan tool dengan Claude

Claude mampu berinteraksi dengan tool dan fungsi, memungkinkan Anda memperluas kemampuan Claude untuk melakukan berbagai tugas yang lebih luas.

Pelajari semua yang Anda butuhkan untuk menguasai penggunaan tool dengan Claude sebagai bagian dari kursus baru kami! Silakan terus bagikan ide dan saran Anda menggunakan formulir ini.

Berikut adalah contoh cara menyediakan tool kepada 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-1-20250805",
    "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 tool

Claude mendukung dua jenis tool:

Tool klien: Tool yang dieksekusi pada sistem Anda, yang meliputi:
- Tool kustom yang didefinisikan pengguna yang Anda buat dan implementasikan
- Tool yang didefinisikan Anthropic seperti penggunaan komputer dan editor teks yang memerlukan implementasi klien
Tool server: Tool yang dieksekusi pada server Anthropic, seperti tool pencarian web dan pengambilan web. Tool ini harus dispesifikasikan dalam permintaan API tetapi tidak memerlukan implementasi dari pihak Anda.

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

Tool klien

Integrasikan tool klien dengan Claude dalam langkah-langkah berikut:

Berikan Claude tool dan prompt pengguna

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

Claude memutuskan untuk menggunakan tool

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

Eksekusi tool dan kembalikan hasil

Ekstrak nama tool dan input dari permintaan Claude
Eksekusi kode tool pada sistem Anda
Kembalikan hasil dalam pesan user baru yang berisi blok konten tool_result

Claude menggunakan hasil tool untuk merumuskan respons

Claude menganalisis hasil tool untuk menyusun respons akhir terhadap prompt pengguna asli.

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

Tool server

Tool server mengikuti alur kerja yang berbeda:

Berikan Claude tool dan prompt pengguna

Tool server, seperti pencarian web dan pengambilan web, memiliki parameter mereka sendiri.
Sertakan prompt pengguna yang mungkin memerlukan tool ini, misalnya, “Cari berita terbaru tentang AI” atau “Analisis konten di URL ini.”

Claude mengeksekusi tool server

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

Claude menggunakan hasil tool server untuk merumuskan respons

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

Contoh penggunaan tool

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

Contoh tool 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-1-20250805",
    "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-1-20250805",
  "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"}
    }
  ]
}

Anda kemudian perlu mengeksekusi fungsi get_weather dengan input yang diberikan, dan mengembalikan hasil 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-1-20250805",
    "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": "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"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 degrees"
                }
            ]
        }
    ]
}'

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

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "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!"
    }
  ]
}

Penggunaan tool paralel

Contoh beberapa tool

Anda dapat menyediakan Claude dengan beberapa tool untuk dipilih dalam satu permintaan. Berikut adalah contoh dengan tool 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-1-20250805",
    "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 mungkin:

Menggunakan tool secara berurutan (satu per satu) — memanggil get_weather terlebih dahulu, kemudian get_time setelah menerima hasil cuaca
Menggunakan panggilan tool paralel — mengeluarkan beberapa blok tool_use dalam satu respons ketika operasi bersifat independen

Ketika Claude melakukan panggilan tool paralel, Anda harus mengembalikan semua hasil tool dalam satu pesan user, dengan setiap hasil dalam blok tool_result sendiri.

Informasi yang hilang

Jika prompt pengguna tidak menyertakan informasi yang cukup untuk mengisi semua parameter yang diperlukan untuk tool, Claude Opus jauh lebih mungkin mengenali bahwa parameter hilang dan memintanya. Claude Sonnet mungkin bertanya, terutama ketika diminta untuk berpikir sebelum mengeluarkan permintaan tool. Tetapi mungkin juga melakukan yang terbaik untuk menyimpulkan nilai yang masuk akal.Misalnya, menggunakan tool get_weather di atas, jika Anda bertanya kepada Claude “Bagaimana cuacanya?” tanpa menentukan lokasi, Claude, khususnya Claude Sonnet, mungkin membuat tebakan tentang input tool:

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, ia jauh lebih mungkin merespons dengan pertanyaan klarifikasi daripada melakukan panggilan tool.

Tool berurutan

Beberapa tugas mungkin memerlukan pemanggilan beberapa tool secara berurutan, menggunakan output dari satu tool sebagai input untuk tool lain. Dalam kasus seperti itu, Claude akan memanggil satu tool pada satu waktu. Jika diminta untuk memanggil semua tool sekaligus, Claude kemungkinan akan menebak parameter untuk tool yang lebih hilir jika mereka bergantung pada hasil tool untuk tool yang lebih hulu.Berikut adalah contoh menggunakan tool get_location untuk mendapatkan lokasi pengguna, kemudian meneruskan lokasi tersebut ke tool 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-1-20250805",
    "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 tool 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 lengkap mungkin terlihat seperti:

Peran	Konten
Pengguna	Bagaimana cuaca di tempat saya?
Asisten	Saya akan mencari lokasi Anda saat ini terlebih dahulu, kemudian memeriksa cuaca di sana. [Penggunaan tool untuk get_location]
Pengguna	[Hasil tool untuk get_location dengan id yang cocok dan hasil San Francisco, CA]
Asisten	[Penggunaan tool untuk get_weather dengan input berikut]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
Pengguna	[Hasil tool untuk get_weather dengan id yang cocok dan hasil “59°F (15°C), sebagian besar berawan”]
Asisten	Berdasarkan lokasi Anda saat ini di San Francisco, CA, cuaca sekarang adalah 59°F (15°C) dan sebagian besar berawan. Ini adalah hari yang cukup sejuk dan mendung di kota. Anda mungkin ingin membawa jaket ringan jika akan keluar.

Contoh ini mendemonstrasikan bagaimana Claude dapat merangkai beberapa panggilan tool untuk menjawab pertanyaan yang memerlukan pengumpulan data dari sumber yang berbeda. Langkah-langkah kuncinya adalah:

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

Penggunaan tool chain of thought

Mode JSON

Anda dapat menggunakan tool untuk membuat Claude menghasilkan output JSON yang mengikuti skema, bahkan jika Anda tidak berniat menjalankan output tersebut melalui tool atau fungsi.Saat menggunakan tool dengan cara ini:

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

Berikut ini menggunakan tool 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-1-20250805",
    "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.1	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
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) (deprecated)	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (June) (deprecated)	`auto`, `none` `any`, `tool`	294 tokens 261 tokens
Claude Haiku 3.5	`auto`, `none` `any`, `tool`	264 tokens 340 tokens
Claude Opus 3 (deprecated)	`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 gambaran umum model kami untuk harga per model saat ini. Ketika Anda mengirim prompt penggunaan tool, sama 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 tool siap implementasi kami dalam buku masak kami:

Tool Kalkulator

Pelajari cara mengintegrasikan tool kalkulator sederhana dengan Claude untuk komputasi numerik yang presisi.

Agen Layanan Pelanggan

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

Ekstraksi JSON

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

Langkah pertama

Model & harga

Pelajari tentang Claude

Kemampuan

Alat

Model Context Protocol (MCP)

Kasus penggunaan

Rekayasa prompt

Uji & evaluasi

Perkuat pagar pengaman

Pusat Hukum

Penggunaan tool dengan Claude

Cara kerja penggunaan tool

Tool klien

Tool server

Contoh penggunaan tool

Harga

Langkah Selanjutnya

Tool Kalkulator

Agen Layanan Pelanggan

Ekstraksi JSON

Langkah pertama

Model & harga

Pelajari tentang Claude

Kemampuan

Alat

Model Context Protocol (MCP)

Kasus penggunaan

Rekayasa prompt

Uji & evaluasi

Perkuat pagar pengaman

Pusat Hukum

​Cara kerja penggunaan tool

​Tool klien

​Tool server

​Contoh penggunaan tool

​Harga

​Langkah Selanjutnya

Tool Kalkulator

Agen Layanan Pelanggan

Ekstraksi JSON

Cara kerja penggunaan tool

Tool klien

Tool server

Contoh penggunaan tool

Harga

Langkah Selanjutnya