Penggunaan alat dengan Claude

"Tool use" (penggunaan alat) memungkinkan Claude memanggil fungsi yang Anda definisikan atau yang disediakan oleh Anthropic. Claude menentukan kapan harus memanggil alat berdasarkan permintaan pengguna dan deskripsi alat tersebut. Kemudian Claude mengembalikan panggilan terstruktur yang dieksekusi oleh aplikasi Anda (alat klien) atau yang dieksekusi oleh Anthropic (alat server).

Berikut adalah contoh minimal menggunakan alat server, yaitu alat Web search, yang dieksekusi oleh Anthropic untuk Anda:

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

Claude menjalankan pencarian pada infrastruktur Anthropic dan mengembalikan hasil yang disertai sitasi dalam respons yang sama. Agar Claude memanggil fungsi yang Anda definisikan, berikan alat dengan input_schema, lalu eksekusi panggilan tersebut ketika Claude mengembalikan blok tool_use. Mendefinisikan alat dan Menangani panggilan alat membahas siklus bolak-balik tersebut.



Cara kerja penggunaan alat

Alat dibedakan terutama berdasarkan di mana kodenya dieksekusi. Alat klien (termasuk alat yang didefinisikan pengguna dan alat dengan skema yang didefinisikan Anthropic, seperti bash dan text_editor) berjalan di aplikasi Anda. Claude merespons dengan stop_reason: "tool_use" dan satu atau lebih blok tool_use. Kode Anda mengeksekusi operasi tersebut dan mengirimkan kembali tool_result. Alat server (seperti web_search, web_fetch, code_execution, dan tool_search) berjalan pada infrastruktur Anthropic: Anda melihat hasilnya secara langsung tanpa menangani eksekusi, kecuali Claude memanggil alat tersebut dalam kelompok panggilan alat paralel yang sama dengan salah satu alat klien Anda (lihat Stop reason dan fallback).

Untuk model konseptual lengkap termasuk loop agentik dan kapan memilih setiap pendekatan, lihat Cara kerja penggunaan alat.

Untuk menghubungkan ke server Model Context Protocol (MCP), lihat MCP connector. Untuk membangun klien MCP Anda sendiri, lihat panduan Model Context Protocol untuk membangun klien MCP.



Kapan Claude menggunakan alat

Dengan tool_choice default {"type": "auto"}, Claude menentukan pada setiap giliran apakah akan memanggil alat atau merespons secara langsung. Claude memanggil alat ketika permintaan sesuai dengan kemampuan yang dijelaskan alat tersebut dan jawabannya belum ada dalam konteks. Claude merespons secara langsung untuk pengetahuan yang stabil, tugas kreatif, dan giliran percakapan biasa.

Batasan ini dapat diarahkan melalui prompt sistem Anda. Jika Claude tidak memanggil alat saat Anda mengharapkannya, instruksi ringan seperti "Use the tools to investigate before responding." akan meningkatkan penggunaan alat. Bentuk yang lebih kuat seperti "Always call a tool first before responding." mendorong lebih jauh. Sebaliknya, "Use your judgment about whether to call a tool or respond directly." menjaga perilaku pemicu tetap konservatif.

Untuk mewajibkan panggilan alat alih-alih mengandalkan prompting, atur tool_choice.

Setiap halaman alat server menjelaskan batasan pemicunya sendiri secara lebih rinci.



Memilih alat

Untuk string type, versi, dan header beta, lihat Referensi alat.



Alat Anda sendiri

Untuk alat yang Anda definisikan, Anda menulis skemanya dan aplikasi Anda mengeksekusi setiap panggilan.



Alat klien dengan skema Anthropic

Anthropic menerbitkan skemanya dan melatih Claude dengannya. Aplikasi Anda tetap mengeksekusi setiap panggilan dan mengembalikan tool_result.



Alat server

Alat server berjalan pada infrastruktur Anthropic, tanpa kode handler di aplikasi Anda. Lihat Alat server untuk mekanisme yang mereka miliki bersama.



Harga

Permintaan penggunaan alat dikenakan biaya berdasarkan:

1. Jumlah total token input yang dikirim ke model (termasuk dalam parameter tools)
2. Jumlah token output yang dihasilkan
3. Untuk alat sisi server, biaya tambahan berbasis penggunaan (misalnya, pencarian web dikenakan biaya per pencarian yang dilakukan)

Alat sisi klien dikenakan biaya yang sama seperti permintaan API Claude lainnya, sedangkan alat sisi server dapat dikenakan biaya tambahan berdasarkan penggunaan spesifiknya.

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, API 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). Perhatikan bahwa tabel ini mengasumsikan setidaknya 1 alat disediakan. Jika tidak ada tools yang disediakan, maka pilihan alat none menggunakan 0 token prompt sistem tambahan.

Jumlah token ini ditambahkan ke token input dan output normal Anda untuk menghitung total biaya permintaan.

Lihat tabel Ikhtisar model untuk harga per model saat ini.

Ketika Anda mengirim prompt penggunaan alat, seperti permintaan API lainnya, respons menyertakan jumlah token input dan output dalam metrik usage yang dilaporkan.

Beberapa alat server menambahkan biaya berbasis penggunaan di atas token: lihat Alat Web search dan Alat Code execution untuk tarifnya.



Langkah selanjutnya