Claude Platform Docs
PesanAlat

Penggunaan alat dengan Claude

Hubungkan Claude ke alat dan API eksternal. Lihat di mana alat dijalankan, kapan Claude memanggilnya, dan alat mana yang sesuai dengan tugas Anda.

“Tool use” (penggunaan alat), yang juga disebut “function calling” (pemanggilan fungsi), 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 dijalankan oleh aplikasi Anda (alat klien) atau yang dijalankan oleh Anthropic (alat server).

Berikut contoh minimal menggunakan alat server, yaitu alat pencarian web, yang dijalankan Anthropic untuk Anda:

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

Claude menjalankan pencarian di infrastruktur Anthropic dan mengembalikan hasil beserta kutipannya dalam respons yang sama. Agar Claude memanggil fungsi yang Anda definisikan, berikan alat dengan input_schema, lalu jalankan panggilan tersebut ketika Claude mengembalikan blok tool_use. Contoh alat klien menunjukkan alur bolak-balik tersebut dari awal hingga akhir. Pelajari lebih lanjut tentang mendefinisikan alat dan menangani panggilan alat.

Cara kerja penggunaan alat

Alat terutama dibedakan berdasarkan di mana kodenya dijalankan. 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 menjalankan operasinya dan mengirimkan kembali tool_result. Alat server (seperti web_search, web_fetch, code_execution, dan tool_search) berjalan di infrastruktur Anthropic: Anda melihat hasilnya secara langsung tanpa perlu menangani eksekusinya, kecuali jika Claude memanggil alat tersebut dalam kelompok panggilan alat paralel yang sama dengan salah satu alat klien Anda (lihat Alasan berhenti dan fallback).

Berikut adalah siklus bolak-balik tersebut secara lengkap untuk alat klien. Permintaan pertama mendefinisikan alat get_weather, dan Claude menjawab pertanyaan dengan memanggilnya: respons membawa blok tool_use, kode Anda menjalankan pencarian, dan permintaan kedua mengirimkan hasilnya kembali dalam blok tool_result sehingga Claude dapat membalas dengan jawabannya.

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claude membalas dengan blok tool_use yang menyebutkan alat dan argumennya.
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=tools,
    # Minta paling banyak satu pemanggilan alat di setiap giliran.
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# Jalankan alat, lalu kirim hasilnya kembali dalam blok tool_result.
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claude menggunakan hasil tersebut untuk menjawab pertanyaan awal.
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)
Output
Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

Menangani panggilan alat membahas setiap langkah secara mendetail, termasuk pemformatan hasil dan pensinyalan error; Penggunaan alat paralel membahas respons yang memanggil beberapa alat sekaligus. Agar tidak perlu menulis alur bolak-balik ini sendiri, gunakan tool runner: SDK menjalankan alat Anda dan mengirimkan hasilnya kembali secara otomatis.

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

Untuk terhubung ke server “Model Context Protocol”, atau MCP, lihat konektor MCP. Untuk membangun klien MCP Anda sendiri, lihat panduan Model Context Protocol tentang membangun klien MCP.

Kapan Claude menggunakan alat

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

Batas ini dapat diarahkan melalui prompt sistem Anda. Jika Claude tidak memanggil alat ketika Anda mengharapkannya, instruksi ringan seperti "Use the tools to investigate before responding." 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 pemicuan tetap konservatif.

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

Halaman setiap alat server menjelaskan batas pemicunya sendiri secara lebih mendetail.

Pilih 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 menjalankan setiap panggilan.

Tentukan skema alat, tulis deskripsi, dan kendalikan kapan Claude memanggil alat Anda.

Parse blok tool_use, format respons tool_result, dan tangani kesalahan.

Alat klien dengan skema Anthropic

Anthropic menerbitkan skemanya dan melatih Claude berdasarkan skema tersebut. Aplikasi Anda tetap menjalankan setiap panggilan dan mengembalikan tool_result.

Simpan dan ambil informasi lintas percakapan dalam file yang Anda kendalikan.

Jalankan perintah shell dalam sesi persisten yang mempertahankan state.

Lihat dan modifikasi file teks untuk men-debug, memperbaiki, dan meningkatkan kode.

Ambil tangkapan layar dan kendalikan mouse serta keyboard di lingkungan desktop.

Navigasi, baca, dan berinteraksi dengan halaman web di lingkungan browser Anda sendiri.

Alat server

Alat server berjalan di infrastruktur Anthropic, tanpa kode handler di aplikasi Anda. Lihat Alat server untuk mekanisme yang dimiliki bersama oleh alat-alat tersebut.

Cari informasi di web yang melampaui batas pengetahuan, dengan sumber yang dikutip.

Ambil konten lengkap dari halaman web dan dokumen PDF yang ditentukan.

Jalankan kode Python dan Bash dalam container sandbox untuk menganalisis data dan menghasilkan file.

Biarkan model eksekutor yang lebih cepat berkonsultasi dengan model penasihat berkecerdasan lebih tinggi di tengah proses generasi.

Bekerja dengan ribuan alat dengan menemukan dan memuatnya sesuai permintaan.

Terhubung ke server MCP jarak jauh dari Messages API tanpa klien MCP terpisah.

Harga

Permintaan “tool use” (penggunaan alat) dikenai harga 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, harga tambahan berbasis penggunaan (misalnya, pencarian web mengenakan biaya per pencarian yang dilakukan).

Alat sisi klien dikenai harga yang sama seperti permintaan Claude API lainnya, meskipun alat sisi server dapat menimbulkan 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

Saat Anda menggunakan tools, API juga secara otomatis menyertakan “system prompt” (prompt sistem) khusus untuk model yang memungkinkan penggunaan alat. Tabel berikut mencantumkan jumlah token penggunaan alat yang diperlukan setiap model (tidak termasuk token tambahan yang disebutkan sebelumnya). Tabel ini mengasumsikan bahwa Anda menyediakan setidaknya satu alat. Jika Anda tidak menyediakan tools, pilihan alat none menggunakan 0 token prompt sistem tambahan.

ModelToken prompt sistem penggunaan alat
NamaJumlah token
Claude Opus 5.5For long-running agentic coding and knowledge work
auto, none
286 token
Claude Sonnet 5.5The best combination of speed and intelligence
auto, none
286 token
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing
auto, none
286 token
any, tool
406 token
auto, none
286 token
any, tool
406 token
auto, none
290 token
any, tool
410 token
auto, none
675 token
any, tool
804 token
auto, none
497 token
any, tool
589 token
auto, none
496 token
any, tool
588 token
Claude Opus 4.1
auto, none
313 token
any, tool
315 token
Claude Opus 4
auto, none
313 token
any, tool
315 token
auto, none
354 token
any, tool
474 token
auto, none
497 token
any, tool
589 token
auto, none
496 token
any, tool
588 token
Claude Sonnet 4
auto, none
313 token
any, tool
315 token
auto, none
496 token
any, tool
588 token

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

Lihat tabel Semua model untuk harga per model saat ini.

Ketika Anda mengirim prompt penggunaan alat, sama 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 biaya token: lihat Penggunaan dan harga alat pencarian web dan Penggunaan dan harga alat eksekusi kode untuk tarifnya.

Langkah selanjutnya

Pahami loop penggunaan alat, di mana alat dijalankan, dan kapan menggunakan alat alih-alih prosa.

Panduan langkah demi langkah dari satu panggilan alat hingga loop agentik yang siap produksi.

Direktori alat yang disediakan Anthropic dan referensi untuk properti definisi alat opsional.

Apakah halaman ini membantu?