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

Penggunaan alat sekarang tersedia secara umum di seluruh keluarga model Claude 3 untuk pengembang yang menggunakan API Anthropic Messages, Amazon Bedrock, dan Google Vertex AI! Silakan terus berbagi ide dan saran Anda menggunakan formulir ini.

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

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
      {
        "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"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Bagaimana cuaca di San Francisco?"
      }
    ]
  }'

​
Cara kerja penggunaan alat

Menggunakan alat dengan Claude melibatkan langkah-langkah berikut:

  1. Berikan Claude alat dan prompt pengguna: (permintaan API)
    • Tentukan kumpulan alat yang ingin Anda berikan akses ke Claude, termasuk nama, deskripsi, dan skema input mereka.
    • Berikan prompt pengguna yang mungkin memerlukan penggunaan satu atau lebih alat ini untuk menjawab, seperti “Bagaimana cuaca di San Francisco?“.
  2. Claude menggunakan alat: (respons API)
    • Claude menilai prompt pengguna dan memutuskan apakah ada alat yang tersedia yang akan membantu dengan pertanyaan atau tugas pengguna. Jika demikian, ia juga memutuskan alat mana yang akan digunakan dan dengan input apa.
    • Claude membuat permintaan penggunaan alat yang diformat dengan benar.
    • Respons API akan memiliki stop_reason berupa tool_use, menunjukkan bahwa Claude ingin menggunakan alat eksternal.
  3. Ekstrak input alat, jalankan kode, dan kembalikan hasil: (permintaan API)
    • Di sisi klien, Anda harus mengekstrak nama alat dan input dari permintaan penggunaan alat Claude.
    • Jalankan kode alat yang sebenarnya di sisi klien.
    • Kembalikan hasilnya ke Claude dengan melanjutkan percakapan dengan pesan user baru yang berisi blok konten tool_result.
  4. Claude menggunakan hasil alat untuk merumuskan respons: (respons API)
    • Setelah menerima hasil alat, Claude akan menggunakan informasi itu untuk merumuskan respons akhirnya terhadap prompt pengguna asli.

Langkah (3) dan (4) bersifat opsional — untuk beberapa alur kerja, Claude menggunakan alat adalah semua informasi yang Anda butuhkan, dan Anda mungkin tidak perlu mengembalikan hasil alat kembali ke Claude.

Semua alat disediakan oleh pengguna

Penting untuk dicatat bahwa Claude tidak memiliki akses ke alat sisi server bawaan apa pun. Semua alat harus secara eksplisit disediakan oleh Anda, pengguna, dalam setiap permintaan API. Ini memberi Anda kontrol penuh dan fleksibilitas atas alat yang dapat digunakan Claude.

​
Menentukan alat

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

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

Berikut adalah contoh definisi alat sederhana:

JSON
{
  "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": "Satuan suhu, 'celsius' atau 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

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

​
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 terpenting dalam kinerja alat. Deskripsi Anda harus menjelaskan setiap detail tentang alat, termasuk:
    • Apa yang dilakukan alat
    • Kapan harus digunakan (dan kapan tidak boleh)
    • Apa arti setiap parameter dan bagaimana memengaruhi 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 kepada Claude tentang alat Anda, semakin baik Claude dalam memutuskan kapan dan bagaimana menggunakannya. Targetkan setidaknya 3-4 kalimat per deskripsi alat, lebih 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 mengembangkan deskripsi.

Berikut adalah contoh deskripsi alat yang baik:

JSON
{
  "name": "get_stock_price",
  "description": "Mengambil harga saham saat ini untuk simbol ticker tertentu. Simbol ticker harus berupa simbol yang valid untuk perusahaan yang diperdagangkan secara publik di bursa saham utama AS seperti NYSE atau NASDAQ. Alat akan mengembalikan harga perdagangan terbaru dalam USD. Ini harus digunakan ketika pengguna bertanya tentang harga saat ini atau harga terbaru dari saham tertentu. Alat 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"]
  }
}

Sebaliknya, berikut adalah contoh deskripsi alat yang buruk:

JSON
{
  "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 harus digunakan, 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.

​
Blok konten penggunaan alat dan hasil alat

Ketika Claude memutuskan untuk menggunakan salah satu alat yang telah 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: 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.

Berikut adalah contoh respons API dengan blok konten tool_use:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Saya perlu menggunakan get_weather, dan pengguna menginginkan SF, yang kemungkinan besar 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 yang sebenarnya dalam basis kode Anda yang sesuai dengan nama alat itu, 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 merupakan hasil untuk ini.
    • content: Hasil 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): Setel ke true jika eksekusi alat menghasilkan kesalahan.

Berikut adalah contoh pengembalian hasil alat yang berhasil:

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

Gambar juga didukung dalam content:

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

Dan berikut adalah contoh pengembalian hasil kesalahan:

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

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

Anda juga dapat mengembalikan hasil alat yang tidak salah dengan content kosong, menunjukkan bahwa alat berjalan dengan sukses tanpa output apa pun:

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

Perbedaan dari API lain

Anda mungkin terbiasa dengan API lain yang mengembalikan penggunaan alat terpisah dari output utama model, atau yang menggunakan role pesan tool atau function khusus.

Sebaliknya, model dan API Anthropic dibangun di sekitar pesan user dan assistant yang bergantian, di mana setiap pesan adalah array blok konten yang kaya: text, image, tool_use, dan tool_result.

Dalam format ini, pesan user mewakili konten yang dikelola klien dan pengguna / manusia, dan pesan assistant mewakili konten yang dikelola server dan AI. Dengan demikian, tidak ada role pesan tool atau function khusus, dan Anda harus menyertakan blok tool_result dalam content pesan user Anda.

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

Dengan secara eksplisit memberi tahu Claude untuk menggunakan alat get_weather, Anda dapat mendorongnya untuk menggunakan alat yang Anda inginkan. Teknik ini dapat berguna untuk menguji dan men-debug integrasi alat Anda, atau ketika Anda tahu bahwa alat harus selalu digunakan, terlepas dari input.

Anda juga dapat memberi tahu Claude untuk menggunakan salah satu alat yang disediakan melalui {"type": "any"}. tool_choice default adalah {"type": "auto"}, yang memungkinkan Claude untuk memutuskan apakah akan menggunakan alat atau tidak.

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 mengeluarkan blok konten text rantai pemikiran sebelum blok konten tool_use, bahkan jika diminta secara eksplisit untuk melakukannya. Pengujian kami telah menunjukkan bahwa ini tidak boleh mengurangi kinerja. Jika Anda ingin tetap menggunakan rantai pemikiran (khususnya 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 pun Anda ingin model mengembalikan output JSON yang mengikuti skema yang disediakan. Misalnya, Anda dapat menggunakan alat record_summary dengan skema tertentu. Lihat contoh penggunaan alat untuk contoh lengkap yang berfungsi.

​
Penanganan kesalahan

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

​
Kesalahan eksekusi alat

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

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

Claude kemudian akan memasukkan kesalahan ini ke dalam responsnya kepada pengguna, misalnya “Maaf, saya tidak dapat mengambil cuaca saat ini karena layanan API cuaca tidak tersedia. Silakan coba lagi nanti.”

​
Melebihi token maksimum

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

​
Penggunaan alat tidak valid

Jika upaya Claude menggunakan alat tidak valid (misalnya parameter yang diperlukan hilang), itu biasanya berarti 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 terperinci 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: Parameter 'location' yang diperlukan hilang",
      "is_error": true
    }
  ]
}

​
Penggunaan alat 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 diminta untuk melakukannya.

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": "<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. Untuk contoh yang lebih mendalam, lihat contoh penggunaan alat rantai pemikiran.

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

​
Praktik terbaik dan batasan penggunaan alat

Saat menggunakan alat dengan Claude, perhatikan batasan dan praktik terbaik berikut:

  • Gunakan Claude 3 Opus untuk menavigasi penggunaan alat yang kompleks, Haiku jika berurusan dengan alat yang sederhana: Opus mampu menangani alat simultan paling banyak dan lebih baik dalam menangkap argumen yang hilang dibandingkan dengan model lain. Opus lebih mungkin untuk meminta klarifikasi dalam kasus ambigu di mana argumen tidak secara eksplisit diberikan atau ketika alat mungkin tidak diperlukan untuk menyelesaikan permintaan pengguna. Haiku secara default mencoba menggunakan alat lebih sering (bahkan jika tidak relevan dengan kueri) dan akan menyimpulkan parameter yang hilang jika tidak secara eksplisit diberikan.
  • Jumlah alat: Semua model Claude 3 dapat mempertahankan akurasi >90% bahkan ketika bekerja dengan ratusan alat sederhana, dan sejumlah kecil alat kompleks. “Alat kompleks” adalah alat dengan sejumlah besar parameter atau parameter dengan skema kompleks (misalnya objek bersarang).
  • Alat kompleks dan bersarang dalam: Seperti manusia, Claude dapat bekerja lebih baik dengan antarmuka yang lebih sederhana dan alat yang lebih sederhana. Jika Claude kesulitan menggunakan alat Anda dengan benar, cobalah untuk meratakan skema input dari objek json yang bersarang dalam, dan kurangi jumlah input.
  • Penggunaan alat berurutan: Claude umumnya lebih suka menggunakan satu alat pada satu waktu, kemudian menggunakan output dari alat itu untuk menginformasikan tindakan berikutnya. Meskipun Anda dapat meminta Claude untuk menggunakan beberapa alat secara paralel dengan merancang prompt dan alat Anda dengan hati-hati, ini dapat menyebabkan Claude mengisi nilai dummy untuk parameter yang bergantung pada hasil penggunaan alat sebelumnya. Untuk hasil terbaik, rancang alur kerja dan alat Anda untuk memancing dan bekerja dengan serangkaian penggunaan alat berurutan dari Claude.
  • Pengulangan: Jika permintaan penggunaan alat Claude tidak valid atau parameter yang diperlukan hilang, Anda dapat mengembalikan respons kesalahan dan Claude biasanya akan mencoba kembali permintaan dengan informasi yang hilang diisi. Namun, setelah 2-3 upaya yang gagal, Claude mungkin menyerah dan mengembalikan permintaan maaf kepada pengguna alih-alih mencoba lebih lanjut.
  • Debugging: Saat men-debug perilaku penggunaan alat yang tidak terduga, perhatikan output rantai pemikiran Claude (jika ada) untuk memahami mengapa ia membuat pilihan yang dibuatnya. Anda juga dapat mencoba meminta Claude untuk menggunakan alat tertentu untuk melihat apakah itu mengarah pada perilaku yang diharapkan. Jika Claude menyalahgunakan alat, periksa kembali apakah deskripsi dan skema alat Anda jelas dan tidak ambigu.
  • Tag <search_quality_reflection>: Terkadang saat menggunakan alat pencarian, model dapat mengembalikan tag XML <search_quality_reflection> dan skor kualitas pencarian dalam responsnya. Untuk menghentikan model melakukan ini, tambahkan kalimat “Jangan merefleksikan kualitas hasil pencarian yang dikembalikan dalam respons Anda.” ke akhir prompt Anda.

Dengan memperhatikan batasan dan pedoman ini, Anda dapat merancang alat yang efektif dan orkestrasi agensi yang secara signifikan memperluas kemampuan Claude untuk menangani berbagai tugas.

​
Riwayat versi beta (warisan)

Penggunaan alat tidak lagi dalam beta dan tersedia secara umum mulai 30 Mei 2024.

  • tools-2024-05-16
    • Perubahan prompt sistem untuk Opus untuk menangani skenario di mana beberapa penggunaan alat mungkin diperlukan dalam satu giliran dengan lebih baik
  • tools-2024-04-04: Rilis beta awal untuk penggunaan alat

​
Langkah selanjutnya

Penggunaan alat adalah teknik yang ampuh untuk memperluas kemampuan Claude dengan menghubungkannya ke sumber data dan fungsionalitas eksternal. Dengan seperangkat alat yang dirancang dengan baik, Anda dapat memungkinkan Claude untuk menangani berbagai tugas yang tidak mungkin dilakukan dengan pengetahuan dasarnya saja.

Beberapa langkah potensial selanjutnya untuk dieksplorasi:

  • Jelajahi buku resep penggunaan alat kami: jelajahi repositori kami yang berisi contoh kode penggunaan alat siap diimplementasikan, seperti:
  • Tingkatkan kualitas dan keandalan penggunaan alat: Iterasi dan tingkatkan deskripsi alat dan prompt Anda untuk memancing penggunaan alat yang lebih andal dan akurat dari Claude
  • Perluas kemampuan Claude:
    • Bereksperimen dengan alat dan skema yang berbeda untuk melihat bagaimana Claude menangani berbagai jenis format input dan output.
    • Rangkai beberapa alat bersama untuk memecah tugas kompleks menjadi serangkaian langkah yang lebih sederhana.
    • Bangun orkestrasi agensi di mana Claude dapat menyelesaikan berbagai tugas dari awal hingga akhir seolah-olah itu adalah asisten.
    • Jelajahi arsitektur penggunaan alat yang kompleks seperti memberi Claude alat untuk melakukan pencarian RAG, atau untuk memanggil subagen model yang lebih kecil, seperti Haiku, untuk melaksanakan tugas atas namanya

Saat Anda membangun dengan penggunaan alat, kami sangat senang mendengar umpan balik Anda dan melihat apa yang Anda buat! Bergabunglah dengan Discord pengembang kami untuk berbagi proyek Anda dan mendiskusikan tips dan teknik dengan pengembang lain.

Kami sangat senang melihat bagaimana Anda menggunakan penggunaan alat untuk mendorong batas kemungkinan dengan Claude. Selamat membangun!

Google Sheets add-onContoh penggunaan alat