Cara mengimplementasikan penggunaan alat

Memilih model

Kami merekomendasikan menggunakan Claude Sonnet (4.5) atau Claude Opus (4.1) terbaru untuk alat kompleks dan kueri yang ambigu; mereka menangani beberapa alat dengan lebih baik dan mencari klarifikasi saat diperlukan.

Gunakan model Claude Haiku untuk alat yang sederhana, tetapi perhatikan bahwa mereka mungkin menyimpulkan parameter yang hilang.

Jika menggunakan Claude dengan penggunaan alat dan pemikiran yang diperluas, lihat panduan kami di sini untuk informasi lebih lanjut.

Menentukan alat klien

Alat klien (baik yang ditentukan Anthropic maupun yang ditentukan pengguna) ditentukan dalam parameter tingkat atas tools dari permintaan API. Setiap definisi alat mencakup:

Parameter	Deskripsi
`name`	Nama alat. Harus cocok dengan regex `^[a-zA-Z0-9_-]{1,64}$`.
`description`	Deskripsi plaintext terperinci tentang apa yang dilakukan alat, kapan harus digunakan, dan bagaimana perilakunya.
`input_schema`	Objek JSON Schema yang mendefinisikan parameter yang diharapkan untuk alat.
`input_examples`	(Opsional, beta) Larik objek input contoh untuk membantu Claude memahami cara menggunakan alat. Lihat Memberikan contoh penggunaan alat.

Prompt sistem penggunaan alat

Ketika Anda memanggil Claude API dengan parameter tools, kami membuat prompt sistem khusus dari definisi alat, konfigurasi alat, dan prompt sistem yang ditentukan pengguna. Prompt yang dibangun dirancang untuk menginstruksikan model menggunakan alat yang ditentukan dan memberikan konteks yang diperlukan agar alat beroperasi dengan baik:

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 }}

Praktik terbaik untuk definisi alat

Untuk mendapatkan kinerja terbaik dari Claude saat menggunakan alat, ikuti panduan ini:

Berikan deskripsi yang sangat terperinci. Ini adalah faktor paling penting dalam kinerja alat. Deskripsi Anda harus menjelaskan setiap detail tentang alat, termasuk:
- Apa yang dilakukan alat
- Kapan harus digunakan (dan kapan tidak boleh digunakan)
- Apa arti setiap parameter dan bagaimana pengaruhnya terhadap perilaku alat
- Peringatan atau batasan penting apa pun, seperti informasi apa yang tidak dikembalikan alat jika nama alat tidak jelas. Semakin banyak konteks yang dapat Anda berikan Claude tentang alat Anda, semakin baik dalam memutuskan kapan dan bagaimana menggunakannya. Targetkan setidaknya 3-4 kalimat per deskripsi alat, lebih banyak jika alat kompleks.
Prioritaskan deskripsi, tetapi pertimbangkan menggunakan input_examples untuk alat kompleks. Deskripsi yang jelas paling penting, tetapi untuk alat dengan input kompleks, objek bersarang, atau parameter sensitif format, Anda dapat menggunakan bidang input_examples (beta) untuk memberikan contoh yang divalidasi skema. Lihat Memberikan contoh penggunaan alat untuk detail.

Deskripsi yang baik dengan jelas menjelaskan apa yang dilakukan alat, kapan menggunakannya, data apa yang dikembalikan, dan apa arti parameter ticker. Deskripsi yang buruk terlalu singkat dan meninggalkan Claude dengan banyak pertanyaan terbuka tentang perilaku dan penggunaan alat.

Memberikan contoh penggunaan alat

Anda dapat memberikan contoh konkret dari input alat yang valid untuk membantu Claude memahami cara menggunakan alat Anda dengan lebih efektif. Ini sangat berguna untuk alat kompleks dengan objek bersarang, parameter opsional, atau input sensitif format.

Contoh penggunaan alat adalah fitur beta. Sertakan header beta yang sesuai untuk penyedia Anda:

Penyedia	Header beta	Model yang didukung
Claude API, Microsoft Foundry	`advanced-tool-use-2025-11-20`	Semua model
Vertex AI, Amazon Bedrock	`tool-examples-2025-10-29`	Claude Opus 4.5 saja

Penggunaan dasar

Tambahkan bidang input_examples opsional ke definisi alat Anda dengan larik objek input contoh. Setiap contoh harus valid sesuai dengan input_schema alat:

Contoh disertakan dalam prompt bersama skema alat Anda, menunjukkan Claude pola konkret untuk panggilan alat yang terbentuk dengan baik. Ini membantu Claude memahami kapan harus menyertakan parameter opsional, format apa yang harus digunakan, dan cara menyusun input kompleks.

Persyaratan dan batasan

Validasi skema - Setiap contoh harus valid sesuai dengan input_schema alat. Contoh yang tidak valid mengembalikan kesalahan 400
Tidak didukung untuk alat sisi server - Hanya alat yang ditentukan pengguna yang dapat memiliki contoh input
Biaya token - Contoh menambah token prompt: ~20-50 token untuk contoh sederhana, ~100-200 token untuk objek bersarang kompleks

Pelari alat (beta)

Pelari alat menyediakan solusi siap pakai untuk menjalankan alat dengan Claude. Alih-alih menangani panggilan alat, hasil alat, dan manajemen percakapan secara manual, pelari alat secara otomatis:

Menjalankan alat ketika Claude memanggilnya
Menangani siklus permintaan/respons
Mengelola status percakapan
Menyediakan keamanan tipe dan validasi

Kami merekomendasikan agar Anda menggunakan pelari alat untuk sebagian besar implementasi penggunaan alat.

Pelari alat saat ini dalam beta dan tersedia di SDK Python, TypeScript, dan Ruby.

Manajemen konteks otomatis dengan pemadatan

Pelari alat mendukung pemadatan otomatis, yang menghasilkan ringkasan ketika penggunaan token melebihi ambang batas. Ini memungkinkan tugas agentic jangka panjang untuk melanjutkan melampaui batas jendela konteks.

Pelari alat SDK dalam beta. Sisa dokumen ini mencakup implementasi alat manual.

Mengontrol output Claude

Memaksa penggunaan alat

Dalam beberapa kasus, Anda mungkin ingin Claude menggunakan alat tertentu untuk menjawab pertanyaan pengguna, bahkan jika Claude berpikir dapat memberikan jawaban tanpa menggunakan alat. Anda dapat melakukan ini dengan menentukan alat dalam bidang tool_choice seperti ini:

tool_choice = {"type": "tool", "name": "get_weather"}

Saat bekerja dengan parameter tool_choice, kami memiliki empat opsi yang mungkin:

auto memungkinkan Claude memutuskan apakah akan memanggil alat yang disediakan atau tidak. Ini adalah nilai default ketika tools disediakan.
any memberitahu Claude bahwa itu harus menggunakan salah satu alat yang disediakan, tetapi tidak memaksa alat tertentu.
tool memungkinkan kami memaksa Claude untuk selalu menggunakan alat tertentu.
none mencegah Claude menggunakan alat apa pun. Ini adalah nilai default ketika tidak ada tools yang disediakan.

Saat menggunakan prompt caching, perubahan pada parameter tool_choice akan membatalkan blok pesan yang di-cache. Definisi alat dan prompt sistem tetap di-cache, tetapi konten pesan harus diproses ulang.

Diagram ini mengilustrasikan cara kerja setiap opsi:

Perhatikan bahwa ketika Anda memiliki tool_choice sebagai any atau tool, kami akan mengisi pesan asisten sebelumnya untuk memaksa alat digunakan. Ini berarti bahwa model tidak akan memancarkan respons bahasa alami atau penjelasan sebelum blok konten tool_use, bahkan jika secara eksplisit diminta untuk melakukannya.

Saat menggunakan pemikiran yang diperluas dengan penggunaan alat, tool_choice: {"type": "any"} dan tool_choice: {"type": "tool", "name": "..."} tidak didukung dan akan menghasilkan kesalahan. Hanya tool_choice: {"type": "auto"} (default) dan tool_choice: {"type": "none"} yang kompatibel dengan pemikiran yang diperluas.

Pengujian kami telah menunjukkan bahwa ini seharusnya tidak mengurangi kinerja. Jika Anda ingin model memberikan konteks bahasa alami atau penjelasan sambil tetap meminta model menggunakan alat tertentu, Anda dapat menggunakan {"type": "auto"} untuk tool_choice (default) dan menambahkan instruksi eksplisit dalam pesan user. Misalnya: What's the weather like in London? Use the get_weather tool in your response.

Panggilan alat yang dijamin dengan alat ketat

Gabungkan tool_choice: {"type": "any"} dengan penggunaan alat ketat untuk menjamin bahwa salah satu alat Anda akan dipanggil DAN input alat secara ketat mengikuti skema Anda. Atur strict: true pada definisi alat Anda untuk mengaktifkan validasi skema.

Output JSON

Alat tidak harus berupa fungsi klien — Anda dapat menggunakan alat kapan saja Anda ingin model mengembalikan output JSON yang mengikuti skema yang disediakan. Misalnya, Anda mungkin menggunakan alat record_summary dengan skema tertentu. Lihat Penggunaan alat dengan Claude untuk contoh kerja lengkap.

Respons model dengan alat

Saat menggunakan alat, Claude sering kali akan mengomentari apa yang sedang dilakukannya atau merespons secara alami kepada pengguna sebelum memanggil alat.

Misalnya, diberikan prompt "Bagaimana cuaca di San Francisco sekarang, dan jam berapa di sana?", Claude mungkin merespons dengan:

JSON

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Saya akan membantu Anda memeriksa cuaca saat ini dan waktu di San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Gaya respons alami ini membantu pengguna memahami apa yang dilakukan Claude dan menciptakan interaksi yang lebih percakapan. Anda dapat memandu gaya dan konten respons ini melalui prompt sistem Anda dan dengan menyediakan <examples> dalam prompt Anda.

Penting untuk dicatat bahwa Claude dapat menggunakan berbagai frasa dan pendekatan saat menjelaskan tindakannya. Kode Anda harus memperlakukan respons ini seperti teks yang dihasilkan asisten lainnya, dan tidak mengandalkan konvensi pemformatan tertentu.

Penggunaan alat paralel

Secara default, Claude dapat menggunakan beberapa alat untuk menjawab pertanyaan pengguna. Anda dapat menonaktifkan perilaku ini dengan:

Mengatur disable_parallel_tool_use=true ketika tipe tool_choice adalah auto, yang memastikan bahwa Claude menggunakan paling banyak satu alat
Mengatur disable_parallel_tool_use=true ketika tipe tool_choice adalah any atau tool, yang memastikan bahwa Claude menggunakan tepat satu alat

Memaksimalkan penggunaan alat paralel

Meskipun model Claude 4 memiliki kemampuan penggunaan alat paralel yang sangat baik secara default, Anda dapat meningkatkan kemungkinan eksekusi alat paralel di semua model dengan prompting yang ditargetkan:

Penggunaan alat paralel dengan Claude Sonnet 3.7

Claude Sonnet 3.7 mungkin kurang mungkin membuat panggilan alat paralel dalam respons, bahkan ketika Anda belum mengatur disable_parallel_tool_use. Kami merekomendasikan meningkatkan ke model Claude 4, yang memiliki penggunaan alat yang hemat token bawaan dan pemanggilan alat paralel yang ditingkatkan.

Jika Anda masih menggunakan Claude Sonnet 3.7, Anda dapat mengaktifkan header beta token-efficient-tools-2025-02-19 beta header, yang membantu mendorong Claude untuk menggunakan alat paralel. Anda juga dapat memperkenalkan "alat batch" yang dapat bertindak sebagai meta-alat untuk membungkus invokasi ke alat lain secara bersamaan.

Lihat contoh ini dalam cookbook kami untuk cara menggunakan solusi ini.

Menangani blok konten penggunaan alat dan hasil alat

Lebih sederhana dengan Tool runner: Penanganan alat manual yang dijelaskan di bagian ini secara otomatis dikelola oleh tool runner. Gunakan bagian ini ketika Anda memerlukan kontrol khusus atas eksekusi alat.

Respons Claude berbeda tergantung pada apakah menggunakan alat klien atau alat server.

Menangani hasil dari alat klien

Respons akan memiliki stop_reason dari tool_use dan satu atau lebih blok konten tool_use yang mencakup:

id: Pengenal unik untuk blok penggunaan alat tertentu ini. Ini akan digunakan untuk mencocokkan hasil alat nanti.
name: Nama alat yang digunakan.
input: Objek yang berisi input yang diteruskan ke alat, sesuai dengan input_schema alat.

Ketika Anda menerima respons penggunaan alat untuk alat klien, Anda harus:

Ekstrak name, id, dan input dari blok tool_use.
Jalankan alat sebenarnya dalam codebase Anda yang sesuai dengan nama alat itu, meneruskan input alat.
Lanjutkan percakapan dengan mengirim pesan baru dengan role dari user, dan blok content yang berisi tipe tool_result dan informasi berikut:
- tool_use_id: id dari permintaan penggunaan alat yang merupakan hasil ini.
- content: Hasil alat, sebagai string (misalnya "content": "15 derajat"), daftar blok konten bersarang (misalnya ), atau daftar blok dokumen (misalnya ). Blok konten ini dapat menggunakan tipe , , atau .

Persyaratan pemformatan penting:

Blok hasil alat harus segera mengikuti blok penggunaan alat yang sesuai dalam riwayat pesan. Anda tidak dapat menyertakan pesan apa pun antara pesan penggunaan alat asisten dan pesan hasil alat pengguna.
Dalam pesan pengguna yang berisi hasil alat, blok tool_result harus datang PERTAMA dalam larik konten. Teks apa pun harus datang SETELAH semua hasil alat.

Misalnya, ini akan menyebabkan kesalahan 400:

{"role": "user", "content": [
  {"type": "text", "text": "Berikut adalah hasilnya:"},  // ❌ Teks sebelum tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

Setelah menerima hasil alat, Claude akan menggunakan informasi itu untuk melanjutkan menghasilkan respons terhadap prompt pengguna asli.

Menangani hasil dari alat server

Claude mengeksekusi alat secara internal dan menggabungkan hasil langsung ke dalam responsnya tanpa memerlukan interaksi pengguna tambahan.

Perbedaan dari API lain

Tidak seperti API yang memisahkan penggunaan alat atau menggunakan peran khusus seperti tool atau function, API Claude mengintegrasikan alat langsung ke dalam struktur pesan user dan assistant.

Pesan berisi larik blok text, image, tool_use, dan tool_result. Pesan user mencakup konten klien dan tool_result, sementara pesan assistant berisi konten yang dihasilkan AI dan tool_use.

Menangani alasan penghentian `max_tokens`

Jika respons Claude terpotong karena mencapai batas max_tokens, dan respons yang terpotong berisi blok penggunaan alat yang tidak lengkap, Anda perlu mencoba ulang permintaan dengan nilai max_tokens yang lebih tinggi untuk mendapatkan penggunaan alat lengkap.

Menangani alasan penghentian `pause_turn`

Saat menggunakan alat server seperti pencarian web, API dapat mengembalikan alasan penghentian pause_turn, menunjukkan bahwa API telah menjeda giliran yang berjalan lama.

Berikut cara menangani alasan penghentian pause_turn:

Saat menangani pause_turn:

Lanjutkan percakapan: Teruskan respons yang dijeda apa adanya dalam permintaan berikutnya untuk membiarkan Claude melanjutkan gilirannya
Ubah jika diperlukan: Anda dapat secara opsional memodifikasi konten sebelum melanjutkan jika Anda ingin mengganggu atau mengalihkan percakapan
Pertahankan status alat: Sertakan alat yang sama dalam permintaan kelanjutan untuk mempertahankan fungsionalitas

Pemecahan masalah kesalahan

Penanganan Kesalahan Bawaan: Tool runner menyediakan penanganan kesalahan otomatis untuk sebagian besar skenario umum. Bagian ini mencakup penanganan kesalahan manual untuk kasus penggunaan lanjutan.

Ada beberapa jenis kesalahan berbeda yang dapat terjadi saat menggunakan alat dengan Claude:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    betas=["advanced-tool-use-2025-11-20"],
    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?"}
    ]
)

"content": [{"type": "text", "text": "15 derajat"}]

"content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 derajat"}]

text

image

document

# Periksa apakah respons terpotong selama penggunaan alat
if response.stop_reason == "max_tokens":
    # Periksa apakah blok konten terakhir adalah tool_use yang tidak lengkap
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Kirim permintaan dengan max_tokens yang lebih tinggi
        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=4096,  # Batas yang ditingkatkan
            messages=messages,
            tools=tools
        )

import anthropic

client = anthropic.Anthropic()

# Permintaan awal dengan pencarian web
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Cari informasi komprehensif tentang terobosan komputasi kuantum pada tahun 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Periksa apakah respons memiliki alasan penghentian pause_turn
if response.stop_reason == "pause_turn":
    # Lanjutkan percakapan dengan konten yang dijeda
    messages = [
        {"role": "user", "content": "Cari informasi komprehensif tentang terobosan komputasi kuantum pada tahun 2025"},
        {"role": "assistant", "content": response.content}
    ]

    # Kirim permintaan kelanjutan
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )

    print(continuation)
else:
    print(response)

Memilih model

Menentukan alat klien

Contoh definisi alat sederhana

Prompt sistem penggunaan alat

Praktik terbaik untuk definisi alat

Contoh deskripsi alat yang baik

Memberikan contoh penggunaan alat

Penggunaan dasar

Persyaratan dan batasan

Pelari alat (beta)

Mengontrol output Claude

Memaksa penggunaan alat

Output JSON

Respons model dengan alat

Penggunaan alat paralel

Contoh penggunaan alat paralel lengkap

Memaksimalkan penggunaan alat paralel

Prompt sistem untuk penggunaan alat paralel

Prompting pesan pengguna

Menangani blok konten penggunaan alat dan hasil alat

Menangani hasil dari alat klien

Contoh respons API dengan blok konten `tool_use`

Contoh hasil alat yang berhasil

Contoh hasil alat dengan gambar

Menangani hasil dari alat server

Menangani alasan penghentian max_tokens

Menangani alasan penghentian pause_turn

Pemecahan masalah kesalahan

Kesalahan eksekusi alat

Contoh deskripsi alat yang buruk

Skrip pengujian lengkap untuk alat paralel

Contoh hasil alat kosong

Contoh hasil alat dengan dokumen

Nama alat tidak valid

Tag \<search_quality_reflection>

Kesalahan alat server

Panggilan alat paralel tidak berfungsi

Menangani alasan penghentian `max_tokens`

Menangani alasan penghentian `pause_turn`