Penggunaan alat (pemanggilan fungsi)

Claude mampu berinteraksi dengan alat dan fungsi eksternal sisi klien, memungkinkan Anda melengkapi Claude dengan alat kustom Anda sendiri untuk melakukan berbagai macam tugas.

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

​

Cara kerja penggunaan alat

Integrasikan alat eksternal dengan Claude dalam langkah-langkah berikut:

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.

​

Cara mengimplementasikan penggunaan alat

​

Memilih model

Secara umum, gunakan Claude 3.5 Sonnet atau Claude 3 Opus untuk alat kompleks dan query ambigu; mereka menangani beberapa alat dengan lebih baik dan mencari klarifikasi bila diperlukan.

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

​

Menentukan alat

Alat ditentukan dalam parameter tingkat atas tools dari permintaan API. Setiap definisi alat mencakup:

{
  "name": "get_weather",
  "description": "Dapatkan cuaca saat ini di lokasi tertentu",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "Kota dan negara bagian, misalnya San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Unit suhu, baik 'celsius' atau 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

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

Dalam lingkungan ini Anda memiliki akses ke serangkaian alat yang dapat Anda gunakan untuk menjawab pertanyaan pengguna.
{{ FORMATTING INSTRUCTIONS }}
Parameter string dan skalar harus ditentukan apa adanya, sementara daftar dan objek harus menggunakan format JSON. Perhatikan bahwa spasi untuk nilai string tidak dihapus. Output tidak diharapkan menjadi XML yang valid dan diuraikan dengan ekspresi reguler.
Berikut adalah fungsi yang tersedia dalam format JSONSchema:
{{ 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 pedoman ini:

• Berikan deskripsi yang sangat detail. Ini adalah faktor terpenting dalam kinerja alat. Deskripsi Anda harus menjelaskan setiap detail tentang alat, termasuk:
  • Apa yang dilakukan alat
  • 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 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 alatnya kompleks.
• Prioritaskan deskripsi daripada contoh. Meskipun Anda dapat menyertakan contoh cara menggunakan alat dalam deskripsinya atau dalam prompt yang menyertainya, ini kurang penting daripada memiliki penjelasan yang jelas dan komprehensif tentang tujuan dan parameter alat. Hanya tambahkan contoh setelah Anda sepenuhnya menguraikan deskripsinya.

{
  "name": "get_stock_price",
  "description": "Mengambil harga saham saat ini untuk simbol ticker tertentu. Simbol ticker harus merupakan simbol yang valid untuk perusahaan yang diperdagangkan secara publik di bursa saham AS utama seperti NYSE atau NASDAQ. Alat ini akan mengembalikan harga perdagangan terbaru dalam USD. Ini harus digunakan ketika pengguna menanyakan tentang harga saat ini atau terbaru dari saham tertentu. Ini tidak akan memberikan informasi lain tentang saham atau perusahaan.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Simbol ticker saham, misalnya AAPL untuk Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Mendapatkan harga saham untuk ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

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

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

Saat bekerja dengan parameter tool_choice, kita memiliki tiga opsi yang mungkin:

• auto memungkinkan Claude memutuskan apakah akan memanggil alat yang disediakan atau tidak. Ini adalah nilai default.
• 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.

Diagram ini mengilustrasikan bagaimana setiap opsi bekerja:

Perhatikan bahwa ketika Anda memiliki tool_choice sebagai any atau tool, kami akan mengisi terlebih dahulu pesan asisten untuk memaksa alat digunakan. Ini berarti bahwa model tidak akan mengeluarkan blok konten text chain-of-thought sebelum blok konten tool_use, bahkan jika secara eksplisit diminta untuk melakukannya.

Pengujian kami telah menunjukkan bahwa ini seharusnya tidak mengurangi kinerja. Jika Anda ingin tetap menggunakan chain-of-thought (terutama dengan Opus) sambil tetap meminta model menggunakan alat tertentu, Anda dapat menggunakan {"type": "auto"} untuk tool_choice (default) dan menambahkan instruksi eksplisit dalam pesan user. Misalnya: Bagaimana cuaca di London? Gunakan alat get_weather dalam respons Anda.

​

Output JSON

Alat tidak harus berupa fungsi sisi 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 contoh penggunaan alat untuk contoh yang lengkap.

​

Chain of thought

Saat menggunakan alat, Claude sering menunjukkan “chain of thought”-nya, yaitu penalaran langkah demi langkah yang digunakannya untuk menguraikan masalah dan memutuskan alat mana yang akan digunakan. Model Claude 3 Opus 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 “Bagaimana cuaca di San Francisco sekarang, dan jam berapa di sana?”, Claude mungkin merespons dengan:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Untuk menjawab pertanyaan ini, saya akan: 1. Menggunakan alat get_weather untuk mendapatkan cuaca saat ini di San Francisco. 2. Menggunakan alat get_time untuk mendapatkan waktu saat ini di zona waktu America/Los_Angeles, yang mencakup San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Chain of thought ini memberikan wawasan tentang proses penalaran Claude dan dapat membantu Anda men-debug perilaku yang tidak diharapkan.

Dengan model Claude 3 Sonnet, chain of thought kurang umum secara default, tetapi Anda dapat meminta Claude untuk menunjukkan penalarannya dengan menambahkan sesuatu seperti "Sebelum menjawab, jelaskan penalaran Anda langkah demi langkah dalam tag." ke pesan pengguna atau prompt sistem.

Penting untuk dicatat bahwa meskipun tag <thinking> adalah konvensi umum yang digunakan Claude untuk menandakan chain of thought-nya, format yang tepat (seperti nama tag XML ini) dapat berubah seiring waktu. Kode Anda harus memperlakukan chain of thought seperti teks yang dihasilkan asisten lainnya, dan tidak bergantung pada keberadaan atau format khusus dari tag <thinking>.

​

Menonaktifkan penggunaan alat paralel

Secara default, Claude dapat menggunakan beberapa alat untuk menjawab query pengguna. Anda dapat menonaktifkan perilaku ini dengan mengatur disable_parallel_tool_use=true dalam bidang tool_choice.

• Ketika tipe tool_choice adalah auto, ini memastikan bahwa Claude menggunakan paling banyak satu alat
• Ketika tipe tool_choice adalah any atau tool, ini memastikan bahwa Claude menggunakan tepat satu alat

​

Menangani blok konten penggunaan alat dan hasil alat

Ketika Claude memutuskan untuk menggunakan salah satu alat yang Anda sediakan, ia akan mengembalikan respons dengan stop_reason berupa tool_use dan satu atau lebih blok konten tool_use dalam respons API 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.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Saya perlu menggunakan get_weather, dan pengguna menginginkan SF, yang kemungkinan adalah 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, Anda harus:

1. Ekstrak name, id, dan input dari blok tool_use.
2. Jalankan alat sebenarnya dalam basis kode Anda yang sesuai dengan nama alat tersebut, dengan meneruskan input alat.
3. [opsional] 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 ini adalah hasilnya.
   • content: Hasil dari alat, sebagai string (misalnya "content": "15 derajat") atau daftar blok konten bersarang (misalnya "content": [{"type": "text", "text": "15 derajat"}]). Blok konten ini dapat menggunakan tipe text atau image.
   • is_error (opsional): Diatur ke true jika eksekusi alat menghasilkan error.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 derajat"
    }
  ]
}

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

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

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

​

Mengatasi error

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

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: layanan API cuaca tidak tersedia (HTTP 500)",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Parameter wajib 'location' hilang",
      "is_error": true
    }
  ]
}

​

Contoh penggunaan alat

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Saya perlu memanggil fungsi get_weather, dan pengguna menginginkan SF, yang kemungkinan adalah San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Cuaca saat ini di San Francisco adalah 15 derajat Celsius (59 derajat Fahrenheit). Ini adalah hari yang sejuk di kota di teluk!"
    }
  ]
}

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

​

Harga

Permintaan penggunaan alat dihargai sama seperti permintaan API Claude lainnya, berdasarkan total jumlah token input yang dikirim ke model (termasuk dalam parameter tools) dan jumlah token output yang dihasilkan.”

Token tambahan dari penggunaan alat berasal dari:

• Parameter tools dalam permintaan API (nama alat, deskripsi, dan skema)
• Blok konten tool_use dalam permintaan dan respons API
• Blok konten tool_result dalam permintaan API

Ketika Anda menggunakan tools, kami juga secara otomatis menyertakan prompt sistem khusus untuk model yang mengaktifkan penggunaan alat. Jumlah token penggunaan alat yang diperlukan untuk setiap model tercantum di bawah ini (tidak termasuk token tambahan yang tercantum di atas):

Jumlah token ini ditambahkan ke token input dan output normal Anda untuk menghitung total biaya permintaan. Lihat tabel ikhtisar model kami untuk harga per model saat ini.

Ketika Anda mengirim prompt penggunaan alat, 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 alat siap implementasi kami dalam buku panduan kami: