Cara mengimplementasikan penggunaan alat

Memilih model

Secara umum, gunakan Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 atau Claude Opus 3 untuk alat yang kompleks dan kueri yang ambigu; mereka menangani beberapa alat dengan lebih baik dan mencari klarifikasi saat diperlukan.

Gunakan Claude Haiku 3.5 atau Claude Haiku 3 untuk alat yang sederhana, tetapi perhatikan bahwa mereka mungkin akan menyimpulkan parameter yang hilang.

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

Menentukan alat klien

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

Parameter	Deskripsi
`name`	Nama alat. Harus sesuai dengan regex `^[a-zA-Z0-9_-]{1,64}$`.
`description`	Deskripsi teks biasa yang mendetail tentang apa yang dilakukan alat, kapan harus digunakan, dan bagaimana perilakunya.
`input_schema`	Objek JSON Schema yang mendefinisikan parameter yang diharapkan untuk alat tersebut.

Contoh definisi alat sederhana

JSON
{
  "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"]
  }
}

Alat ini, bernama get_weather, mengharapkan objek input dengan string location yang wajib dan string unit opsional yang harus berupa “celsius” atau “fahrenheit”.

Prompt sistem penggunaan alat

Ketika Anda memanggil API Anthropic dengan parameter tools, kami membuat prompt sistem khusus dari definisi alat, konfigurasi alat, dan prompt sistem yang ditentukan pengguna. Prompt yang dibuat dirancang untuk menginstruksikan model untuk menggunakan alat yang ditentukan dan memberikan konteks yang diperlukan agar alat dapat 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 performa terbaik dari Claude saat menggunakan alat, ikuti pedoman ini:

Berikan deskripsi yang sangat detail. Ini adalah faktor yang paling penting dalam performa alat. Deskripsi Anda harus menjelaskan setiap detail tentang alat, termasuk:
- Apa yang dilakukan alat
- Kapan alat harus digunakan (dan kapan tidak boleh)
- Apa arti setiap parameter dan bagaimana pengaruhnya terhadap perilaku alat
- Peringatan atau batasan penting, 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 kemampuannya dalam memutuskan kapan dan bagaimana menggunakannya. Targetkan setidaknya 3-4 kalimat per deskripsi alat, lebih banyak jika alat tersebut kompleks.
Prioritaskan deskripsi daripada contoh. Meskipun Anda dapat menyertakan contoh cara menggunakan alat dalam deskripsi atau dalam prompt yang menyertainya, ini kurang penting daripada memiliki penjelasan yang jelas dan komprehensif tentang tujuan dan parameter alat. Tambahkan contoh hanya setelah Anda sepenuhnya menguraikan deskripsi.

Contoh deskripsi alat yang baik

JSON
{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Contoh deskripsi alat yang buruk

JSON
{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

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

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 di bidang tool_choice seperti ini:

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

Saat bekerja dengan parameter tool_choice, kita 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 memberi tahu Claude bahwa ia harus menggunakan salah satu alat yang disediakan, tetapi tidak memaksa alat tertentu.
tool memungkinkan kita 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 bagaimana setiap opsi bekerja:

Perhatikan bahwa ketika Anda memiliki tool_choice sebagai any atau tool, kami akan mengisi awal pesan asisten untuk memaksa penggunaan alat. Ini berarti bahwa model tidak akan mengeluarkan blok konten text alur pemikiran sebelum blok konten tool_use, bahkan jika secara eksplisit diminta untuk melakukannya.

Pengujian kami menunjukkan bahwa ini seharusnya tidak mengurangi performa. Jika Anda ingin mempertahankan alur pemikiran (terutama dengan Opus) sambil tetap meminta model untuk 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.

Output JSON

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

Alur pemikiran

Saat menggunakan alat, Claude sering menunjukkan “alur pemikirannya”, yaitu penalaran langkah demi langkah yang digunakannya untuk memecah masalah dan memutuskan alat mana yang akan digunakan. Model Claude Opus 3 akan melakukan ini jika tool_choice diatur ke auto (ini adalah nilai default, lihat Memaksa penggunaan alat), dan Sonnet dan Haiku dapat diprompt untuk melakukannya.

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

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Alur pemikiran ini memberikan wawasan tentang proses penalaran Claude dan dapat membantu Anda men-debug perilaku yang tidak terduga.

Dengan model Claude Sonnet 3, alur pemikiran kurang umum secara default, tetapi Anda dapat meminta Claude untuk menunjukkan penalarannya dengan menambahkan sesuatu seperti "Before answering, explain your reasoning step-by-step in tags." ke pesan pengguna atau prompt sistem.

Penting untuk dicatat bahwa meskipun tag <thinking> adalah konvensi umum yang digunakan Claude untuk menunjukkan alur pemikirannya, format yang tepat (seperti nama tag XML ini) dapat berubah seiring waktu. Kode Anda harus memperlakukan alur pemikiran seperti teks yang dihasilkan asisten lainnya, dan tidak bergantung pada keberadaan atau format spesifik dari tag <thinking>.

Penggunaan alat paralel

Secara default, Claude dapat menggunakan beberapa alat untuk menjawab kueri 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

Penggunaan alat paralel dengan Claude Sonnet 3.7

Claude Sonnet 3.7 mungkin lebih kecil kemungkinannya untuk membuat panggilan alat paralel dalam respons, bahkan ketika Anda belum mengatur disable_parallel_tool_use. Untuk mengatasi ini, kami merekomendasikan untuk mengaktifkan penggunaan alat yang hemat token, yang membantu mendorong Claude untuk menggunakan alat paralel. Fitur beta ini juga mengurangi latensi dan menghemat rata-rata 14% dalam token output.

Jika Anda lebih suka tidak mengikuti beta penggunaan alat yang hemat token, Anda juga dapat memperkenalkan “alat batch” yang dapat bertindak sebagai meta-alat untuk membungkus pemanggilan ke beberapa alat secara bersamaan. Kami menemukan bahwa jika alat ini ada, model akan menggunakannya untuk memanggil beberapa alat secara paralel untuk Anda.

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

Menangani blok konten penggunaan alat dan hasil alat

Respons Claude berbeda berdasarkan apakah ia menggunakan alat klien atau server.

Menangani hasil dari alat klien

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

id: Pengidentifikasi 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.

Contoh respons API dengan blok konten `tool_use`

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to use the 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"}
    }
  ]
}

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

Ekstrak name, id, dan input dari blok tool_use.
Jalankan alat yang sebenarnya dalam kode Anda yang sesuai dengan nama alat tersebut, dengan meneruskan input alat.
Lanjutkan percakapan dengan mengirim pesan baru dengan role berupa 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 dari alat, sebagai string (misalnya "content": "15 degrees") atau daftar blok konten bersarang (misalnya "content": [{"type": "text", "text": "15 degrees"}]). Blok konten ini dapat menggunakan tipe text atau image.
- is_error (opsional): Diatur ke true jika eksekusi alat menghasilkan kesalahan.

Contoh hasil alat yang berhasil

Contoh hasil alat dengan gambar

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 degrees"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

Contoh hasil alat kosong

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

Menangani hasil dari alat server

Claude mengeksekusi alat secara internal dan menggabungkan hasilnya 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 Anthropic mengintegrasikan alat langsung ke dalam struktur pesan user dan assistant.

Pesan berisi array 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 berhenti `pause_turn`

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

Berikut cara menangani alasan berhenti pause_turn:

import anthropic

client = anthropic.Anthropic()

# Initial request with web search
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {"role": "user", "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"},
        {"role": "assistant", "content": response.content}
    ]
    
    # Send the continuation request
    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)

Saat menangani pause_turn:

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

Pemecahan masalah kesalahan

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

Kesalahan eksekusi alat

Jika alat itu sendiri mengalami kesalahan selama eksekusi (misalnya kesalahan jaringan saat mengambil data cuaca), Anda dapat mengembalikan pesan kesalahan di content bersama dengan "is_error": true:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

Claude kemudian akan memasukkan kesalahan ini ke dalam responsnya kepada pengguna, misalnya “I’m sorry, I was unable to retrieve the current weather because the weather service API is not available. Please try again later.”

Max tokens terlampaui

Nama alat tidak valid

Jika upaya Claude untuk menggunakan alat tidak valid (misalnya parameter yang diperlukan hilang), biasanya berarti bahwa tidak ada cukup informasi bagi Claude untuk menggunakan alat dengan benar. Pilihan terbaik Anda selama pengembangan adalah mencoba permintaan lagi dengan nilai description yang lebih detail dalam definisi alat Anda.

Namun, Anda juga dapat melanjutkan percakapan dengan tool_result yang menunjukkan kesalahan, dan Claude akan mencoba menggunakan alat lagi dengan informasi yang hilang diisi:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

Jika permintaan alat tidak valid atau parameter hilang, Claude akan mencoba 2-3 kali dengan koreksi sebelum meminta maaf kepada pengguna.

Tag <search_quality_reflection>

Kesalahan alat server

Langkah awal

Model & harga

Jelajahi fitur

Pelajari tentang Claude

Uji & evaluasi

Pusat Hukum

Komponen agen

Cara mengimplementasikan penggunaan alat

Memilih model

Menentukan alat klien

Prompt sistem penggunaan alat

Praktik terbaik untuk definisi alat

Mengontrol output Claude

Memaksa penggunaan alat

Output JSON

Alur pemikiran

Penggunaan alat paralel

Menangani blok konten penggunaan alat dan hasil alat

Menangani hasil dari alat klien

Menangani hasil dari alat server

Menangani alasan berhenti `pause_turn`

Pemecahan masalah kesalahan

Langkah awal

Model & harga

Jelajahi fitur

Pelajari tentang Claude

Uji & evaluasi

Pusat Hukum

Komponen agen

​Memilih model

​Menentukan alat klien

​Prompt sistem penggunaan alat

​Praktik terbaik untuk definisi alat

​Mengontrol output Claude

​Memaksa penggunaan alat

​Output JSON

​Alur pemikiran

​Penggunaan alat paralel

​Menangani blok konten penggunaan alat dan hasil alat

​Menangani hasil dari alat klien

​Menangani hasil dari alat server

​Menangani alasan berhenti pause_turn

​Pemecahan masalah kesalahan

Memilih model

Menentukan alat klien

Prompt sistem penggunaan alat

Praktik terbaik untuk definisi alat

Mengontrol output Claude

Memaksa penggunaan alat

Output JSON

Alur pemikiran

Penggunaan alat paralel

Menangani blok konten penggunaan alat dan hasil alat

Menangani hasil dari alat klien

Menangani hasil dari alat server

Menangani alasan berhenti `pause_turn`

Pemecahan masalah kesalahan