Penggunaan alat (pemanggilan fungsi)
Claude mampu berinteraksi dengan alat dan fungsi eksternal sisi klien, memungkinkan Anda melengkapi Claude dengan alat khusus Anda sendiri untuk melakukan berbagai tugas.
Pelajari semua yang Anda butuhkan untuk menguasai penggunaan alat dengan Claude melalui kursus komprehensif baru kami tentang penggunaan alat! Silakan terus berbagi ide dan saran Anda menggunakan formulir ini.
Berikut adalah contoh cara menyediakan alat untuk Claude menggunakan API Messages:
Cara kerja penggunaan alat
Integrasikan alat eksternal dengan Claude dalam langkah-langkah berikut:
Berikan Claude alat dan prompt pengguna
- Tentukan alat dengan nama, deskripsi, dan skema input dalam permintaan API Anda.
- Sertakan prompt pengguna yang mungkin memerlukan alat-alat ini, misalnya, “Bagaimana cuaca di San Francisco?”
Claude memutuskan untuk menggunakan alat
- Claude menilai apakah ada alat yang dapat membantu pertanyaan pengguna.
- Jika ya, Claude membuat permintaan penggunaan alat yang diformat dengan benar.
- Respons API memiliki
stop_reason
berupatool_use
, menandakan niat Claude.
Ekstrak input alat, jalankan kode, dan kembalikan hasilnya
- Di sisi Anda, ekstrak nama alat dan input dari permintaan Claude.
- Jalankan kode alat yang sebenarnya di sisi klien.
- Lanjutkan percakapan dengan pesan
user
baru yang berisi blok kontentool_result
.
Claude menggunakan hasil alat untuk merumuskan respons
- Claude menganalisis hasil alat untuk menyusun respons akhirnya terhadap prompt pengguna awal.
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.
Semua alat disediakan oleh pengguna
Penting untuk dicatat bahwa Claude tidak memiliki akses ke alat bawaan sisi server. Semua alat harus secara eksplisit disediakan oleh Anda, pengguna, dalam setiap permintaan API. Ini memberi Anda kendali penuh dan fleksibilitas atas alat yang dapat digunakan Claude.
Cara mengimplementasikan penggunaan alat
Memilih model
Secara umum, gunakan Claude 3 Opus untuk alat yang kompleks dan pertanyaan yang ambigu; model ini menangani beberapa alat dengan lebih baik dan mencari klarifikasi jika diperlukan.
Gunakan Haiku untuk alat yang sederhana, tetapi perhatikan bahwa model ini mungkin akan menyimpulkan parameter yang hilang.
Menentukan alat
Alat 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 terperinci tentang apa yang dilakukan alat, kapan harus digunakan, dan bagaimana perilakunya. |
input_schema | Objek JSON Schema yang mendefinisikan parameter yang diharapkan untuk alat tersebut. |
Praktik terbaik untuk definisi alat
Untuk mendapatkan kinerja terbaik dari Claude saat menggunakan alat, ikuti pedoman berikut:
- Berikan deskripsi yang sangat terperinci. 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 oleh alat jika nama alat tidak jelas. Semakin banyak konteks yang dapat Anda berikan kepada Claude tentang alat Anda, semakin baik Claude akan memutuskan kapan dan bagaimana menggunakannya. Usahakan setidaknya 3-4 kalimat untuk setiap deskripsi alat, lebih banyak jika alat tersebut 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.
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 di 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
rantai pemikiran sebelum blok konten tool_use
, bahkan jika secara eksplisit diminta untuk melakukannya.
Pengujian kami menunjukkan bahwa ini seharusnya tidak mengurangi kinerja. Jika Anda ingin tetap menggunakan rantai 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: 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.
Rantai pemikiran
Saat menggunakan alat, Claude sering kali akan menunjukkan “rantai pemikirannya”, yaitu penalaran langkah demi langkah yang digunakannya untuk memecah 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"}
}
]
}
Rantai pemikiran ini memberikan wawasan tentang proses penalaran Claude dan dapat membantu Anda men-debug perilaku yang tidak terduga.
Dengan model Claude 3 Sonnet, rantai pemikiran 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 rantai pemikirannya, format yang tepat (seperti nama tag XML ini) dapat berubah seiring waktu. Kode Anda harus memperlakukan rantai pemikiran seperti teks lain yang dihasilkan asisten, dan tidak bergantung pada keberadaan atau format khusus dari tag <thinking>
.
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 denganinput_schema
alat.
Ketika Anda menerima respons penggunaan alat, Anda harus:
- Ekstrak
name
,id
, daninput
dari bloktool_use
. - Jalankan alat yang sebenarnya dalam basis kode Anda yang sesuai dengan nama alat tersebut, dengan meneruskan
input
alat. - [opsional] Lanjutkan percakapan dengan mengirim pesan baru dengan
role
user
, dan blokcontent
yang berisi tipetool_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 derajat"
) atau daftar blok konten bersarang (misalnya"content": [{"type": "text", "text": "15 derajat"}]
). Blok konten ini dapat menggunakan tipetext
atauimage
.is_error
(opsional): Atur ketrue
jika eksekusi alat menghasilkan kesalahan.
Setelah menerima hasil alat, Claude akan menggunakan informasi tersebut untuk melanjutkan menghasilkan respons terhadap prompt pengguna awal.
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 sisi klien dan tool_result
, sementara pesan assistant
berisi konten yang dihasilkan AI dan tool_use
.
Mengatasi kesalahan
Ada beberapa jenis kesalahan yang dapat terjadi saat menggunakan alat dengan Claude:
Contoh penggunaan alat
Berikut adalah beberapa contoh kode yang mendemonstrasikan berbagai pola dan teknik penggunaan alat. Demi singkatnya, alat-alat tersebut adalah alat sederhana, dan deskripsi alat lebih pendek daripada yang ideal untuk memastikan kinerja terbaik.
Harga
Permintaan penggunaan alat dihargai sama dengan 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 memungkinkan penggunaan alat. Jumlah token penggunaan alat yang diperlukan untuk setiap model tercantum di bawah ini (tidak termasuk token tambahan yang tercantum di atas):
Model | Pilihan alat | Jumlah token prompt sistem penggunaan alat |
---|---|---|
Claude 3.5 Sonnet | auto any , tool | 294 token 261 token |
Claude 3 Opus | auto any , tool | 530 token 281 token |
Claude 3 Sonnet | auto any , tool | 159 token 235 token |
Claude 3 Haiku | auto any , tool | 264 token 340 token |
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 resep kami:
Alat Kalkulator
Pelajari cara mengintegrasikan alat kalkulator sederhana dengan Claude untuk perhitungan numerik yang tepat.
Agen Layanan Pelanggan
Bangun bot layanan pelanggan yang responsif yang memanfaatkan alat sisi klien untuk meningkatkan dukungan.
Ekstraktor JSON
Lihat bagaimana Claude dan penggunaan alat dapat mengekstrak data terstruktur dari teks tidak terstruktur.