Mendefinisikan alat



Prasyarat

• Keakraban dengan ikhtisar penggunaan alat
• Kunci API Claude dan pengaturan SDK atau cURL yang berfungsi



Memilih model

Gunakan model Claude Opus terbaru, Claude Opus 5, untuk alat yang kompleks dan kueri yang ambigu; model ini menangani beberapa alat dengan lebih baik dan meminta klarifikasi saat diperlukan.

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



Menentukan alat klien

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

Untuk kumpulan lengkap properti opsional yang tersedia pada definisi alat apa pun, termasuk cache_control, strict, defer_loading, dan allowed_callers, lihat Referensi alat.



Prompt sistem penggunaan alat

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

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 berikut:

• Berikan deskripsi yang sangat terperinci. Ini sejauh ini merupakan faktor terpenting dalam kinerja alat. Deskripsi Anda harus menjelaskan setiap detail tentang alat tersebut, termasuk:
  • Apa yang dilakukan alat tersebut
  • Kapan harus digunakan (dan kapan tidak)
  • Apa arti setiap parameter dan bagaimana pengaruhnya terhadap perilaku alat
  • Peringatan atau batasan penting apa pun, seperti informasi apa yang tidak dikembalikan oleh alat jika nama alat tidak jelas. Semakin banyak konteks yang dapat Anda berikan kepada Claude tentang alat Anda, semakin baik Claude dalam memutuskan kapan dan bagaimana menggunakannya. Usahakan setidaknya 3–4 kalimat untuk setiap deskripsi alat, lebih banyak jika alatnya kompleks.
• Prioritaskan deskripsi, tetapi pertimbangkan untuk menggunakan input_examples untuk alat yang kompleks. Deskripsi yang jelas adalah yang paling penting, tetapi untuk alat dengan input yang kompleks, objek bersarang, atau parameter yang sensitif terhadap format, Anda dapat menggunakan bidang input_examples untuk memberikan contoh yang divalidasi skema. Lihat Memberikan contoh penggunaan alat untuk detailnya.
• Konsolidasikan operasi terkait menjadi lebih sedikit alat. Daripada membuat alat terpisah untuk setiap tindakan (create_pr, review_pr, merge_pr), kelompokkan menjadi satu alat dengan parameter action. Alat yang lebih sedikit dan lebih mumpuni mengurangi ambiguitas pemilihan dan membuat permukaan alat Anda lebih mudah dinavigasi oleh Claude.
• Gunakan namespacing yang bermakna dalam nama alat. Ketika alat Anda mencakup beberapa layanan atau sumber daya, awali nama dengan layanan (misalnya, github_list_prs, slack_send_message). Ini membuat pemilihan alat tidak ambigu seiring bertambahnya pustaka Anda, dan sangat penting saat menggunakan pencarian alat.
• Rancang respons alat agar hanya mengembalikan informasi bernilai tinggi. Kembalikan pengidentifikasi semantik yang stabil (misalnya, slug atau UUID) daripada referensi internal yang tidak jelas, dan sertakan hanya bidang yang dibutuhkan Claude untuk mempertimbangkan langkah berikutnya. Respons yang membengkak membuang-buang konteks dan mempersulit Claude untuk mengekstrak apa yang penting.

Deskripsi yang baik dengan jelas menjelaskan apa yang dilakukan alat, kapan menggunakannya, data apa yang dikembalikannya, dan apa arti parameter ticker. Deskripsi yang buruk terlalu singkat dan meninggalkan banyak pertanyaan terbuka bagi Claude 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 yang sensitif terhadap format.



Penggunaan dasar

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    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",
                    },
                },
                "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?"}],
)

print(response)

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



Persyaratan dan batasan

• Validasi skema - Setiap contoh harus valid sesuai dengan input_schema alat. Contoh yang tidak valid mengembalikan error 400
• Tidak didukung untuk alat sisi server - Contoh input berfungsi pada alat klien yang ditentukan pengguna dan berskema Anthropic, tetapi tidak pada alat server seperti pencarian web atau eksekusi kode
• Biaya token - Contoh menambah token prompt: ~20–50 token untuk contoh sederhana, ~100–200 token untuk objek bersarang yang kompleks



Mengendalikan output Claude



Memaksa penggunaan alat

Dalam beberapa kasus, Anda mungkin ingin Claude menggunakan alat tertentu untuk menjawab pertanyaan pengguna, bahkan jika Claude sebenarnya akan menjawab langsung tanpa memanggil alat. Anda dapat melakukan ini dengan menentukan alat dalam bidang tool_choice dari permintaan. Baris yang disorot adalah satu-satunya perbedaan dari permintaan penggunaan alat standar:

client = anthropic.Anthropic()

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

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Saat bekerja dengan parameter tool_choice, ada empat opsi yang mungkin:

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

Diagram ini mengilustrasikan cara kerja setiap opsi:

Perhatikan bahwa ketika Anda menetapkan tool_choice sebagai any atau tool, API akan mengisi awal pesan asisten untuk memaksa penggunaan alat. Ini berarti model tidak akan mengeluarkan respons bahasa alami atau penjelasan sebelum blok konten tool_use, bahkan jika diminta secara eksplisit untuk melakukannya.

Pengujian telah menunjukkan bahwa ini seharusnya tidak mengurangi kinerja. Jika Anda ingin model memberikan konteks atau penjelasan bahasa alami 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.



Respons model dengan alat

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

Misalnya, dengan prompt "What's the weather like in San Francisco right now, and what time is it there?", Claude mungkin merespons dengan:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in 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 sedang dilakukan Claude dan menciptakan interaksi yang lebih bersifat percakapan. Anda dapat memandu gaya dan konten respons ini melalui prompt sistem Anda dan dengan memberikan <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 lain yang dihasilkan asisten, dan tidak bergantung pada konvensi pemformatan tertentu.



Langkah selanjutnya