Tool Use (Function Calling)

Halaman ini mengandaikan kamu sudah akrab dengan tiga hal. Tak perlu ahli; cukup tidak kaget ketika bertemu mereka.

• JSON dan JSON Schema. JSON Schema adalah cara baku menuliskan bentuk sebuah objek JSON: medan apa saja yang ada (properties), tipenya (type), mana yang wajib (required), pilihan yang boleh (enum), dan apakah medan lain dilarang (additionalProperties). Setiap tool dideskripsikan dengan skema seperti ini, dan argumen yang dikirim model berbentuk objek JSON.
• Satu panggilan API model bahasa. Kamu pernah mengirim pesan ke model dan membaca balasannya. Satu hal yang penting diingat: API-nya stateless, artinya ia tak menyimpan ingatan di antara permintaan. Karena itu seluruh riwayat percakapan dikirim ulang setiap kali.
• Python 3.10 atau lebih baru, karena contoh kodenya memakai SDK resmi anthropic.

Kabar baiknya, kamu tak perlu kunci API untuk mengikuti sebagian besar langkah. Putaran agennya bisa diuji dengan respons tiruan, seperti yang ditunjukkan di langkah 4.

Sebelum menulis kode apa pun, pegang dulu satu gagasan ini: model tak pernah menjalankan apa pun sendiri. Coba ikuti satu putaran dari awal.

1. Kamu mengirim pesan pengguna bersama daftar tool yang boleh dipakai.
2. Model memutuskan butuh tool. Ia berhenti dengan stop_reason: "tool_use" dan menyertakan blok tool_use, semacam formulir permintaan berisi id (nomor permintaan), name (tool yang diminta), dan input (argumennya).
3. Kamu menjalankan fungsinya di kodemu sendiri: kueri basis data, panggilan HTTP, atau menulis berkas.
4. Kamu mengirim hasilnya sebagai tool_result, dan model melanjutkan dari situ.

Model tak pernah melihat isi fungsimu. Yang ia tahu hanya deskripsi yang kamu tulis dan hasil yang kamu kembalikan, jadi dua hal itulah yang menentukan seberapa baik ia memakai tool-mu.

Bagi model, definisi tool adalah satu-satunya petunjuk. Ia tak bisa membaca kodemu, jadi deskripsimu perlu menjawab hal-hal yang biasanya kamu jelaskan kepada rekan kerja baru. Ini definisi yang kita pakai di sepanjang halaman:

{
  "name": "cari_buku",
  "description": "Mencari buku di katalog perpustakaan berdasarkan judul atau nama penulis. Pakai tool ini setiap kali pengguna menanyakan ketersediaan, penulis, atau lokasi rak sebuah buku. Hasilnya paling banyak `maks_hasil` buku, masing-masing dengan id, judul, penulis, dan jumlah eksemplar yang tersedia. Tool ini tidak meminjamkan buku.",
  "input_schema": {
    "type": "object",
    "properties": {
      "kata_kunci": {
        "type": "string",
        "description": "Judul atau nama penulis, mis. 'Laskar Pelangi' atau 'Pramoedya'."
      },
      "maks_hasil": {
        "type": "integer",
        "description": "Jumlah hasil paling banyak, 1 sampai 10. Bawaan 5."
      }
    },
    "required": ["kata_kunci"]
  }
}

Baca deskripsinya pelan-pelan. Ia menjawab empat pertanyaan: apa yang dilakukan tool ini, kapan dipakai, apa arti tiap parameter, dan apa yang tidak dilakukannya. Kalimat terakhir, "Tool ini tidak meminjamkan buku", tampak sepele, padahal justru itu yang mencegah model memakai cari_buku untuk meminjam.

Tiga kebiasaan kecil lainnya: pakai enum bila pilihannya terbatas, masukkan ke required hanya yang benar-benar wajib, dan beri awalan nama layanan bila tool-mu banyak (github_list_prs, slack_send_message).

Setiap blok tool_use membawa tiga hal yang kamu butuhkan: id, name, dan input. Balasanmu berupa pesan user yang berisi blok tool_result, satu untuk setiap permintaan:

Anggap tool_use_id seperti nomor antrean: dari situ model tahu hasil mana menjawab permintaan yang mana.

Ada tiga aturan yang paling sering terlewat, dan ketiganya berujung galat:

1. Pesan hasil harus langsung mengikuti giliran asisten; tak boleh ada pesan lain di antaranya.
2. Di dalam pesan itu, semua tool_result ditaruh lebih dulu. Teks tambahan hanya boleh sesudahnya.
3. Giliran asisten dikirim balik utuh (response.content), bukan hanya teksnya. Tanpa blok tool_use-nya, tool_use_id tak punya pasangan.

Latihan: tulis dengan tangan balasan untuk respons yang berisi satu text dan dua tool_use, dengan salah satu tool gagal.

Sekarang kita rangkai semuanya. Idenya sederhana: kirim pesan, lihat alasan model berhenti, jalankan tool bila diminta, kirim hasilnya, lalu ulangi. Begini wujudnya dengan SDK Python resmi:

def tanya(pertanyaan: str) -> str:
    messages: list[MessageParam] = [{"role": "user", "content": pertanyaan}]
    while True:
        response = client.messages.create(
            model="claude-opus-5-5",
            max_tokens=16000,
            tools=TOOLS,
            messages=messages,
        )
        messages.append({"role": "assistant", "content": response.content})
        if response.stop_reason != "tool_use":
            break  # end_turn, atau max_tokens / refusal yang perlu ditangani aplikasimu

        hasil: list[ToolResultBlockParam] = []
        for blok in response.content:
            if blok.type != "tool_use":
                continue
            try:
                isi = jalankan_tool(blok.name, blok.input)
                hasil.append({"type": "tool_result", "tool_use_id": blok.id, "content": isi})
            except Exception as galat:
                hasil.append({"type": "tool_result", "tool_use_id": blok.id,
                              "content": str(galat), "is_error": True})
        messages.append({"role": "user", "content": hasil})  # SEMUA hasil, satu pesan

    return "".join(b.text for b in response.content if b.type == "text")

Perhatikan tiga hal. Giliran model disimpan utuh lewat response.content. Semua hasil dikirim dalam satu pesan. Dan galat tidak menghentikan putaran, karena ia dikembalikan sebagai hasil ber-is_error.

Apa yang sebaiknya terjadi bila tool gagal, misalnya server mati atau buku tak ditemukan? Godaan pertama adalah melempar pengecualian. Jangan. Putaranmu akan berhenti, dan model tak pernah tahu apa yang salah. Lebih baik kembalikan tool_result dengan is_error: true dan pesan yang bisa ditindaklanjuti.

Kenapa isi pesannya penting? Menurut dokumentasi Claude, model biasanya mencoba 2–3 kali memperbaiki panggilan yang tak sah (misalnya parameter wajib hilang) sebelum meminta maaf kepada pengguna. Pesan galatmu adalah petunjuk perbaikannya.

Ada tiga jenis galat, masing-masing dengan penanganannya sendiri:

• Tool gagal dijalankan (jaringan putus, layanan mati): kembalikan is_error: true berisi penyebab dan saran.
• Argumen tak sah: kembalikan is_error: true yang menyebut medan yang salah. Selama pengembangan, ini tanda deskripsimu perlu diperjelas. strict: true menghapus jenis galat ini sama sekali.
• Galat dari tool server (misalnya web_search): model menanganinya sendiri, jadi tak perlu is_error darimu.

Kadang model meminta beberapa tool dalam satu giliran, misalnya mencari dua buku sekaligus. Kamu bebas menjalankannya bersamaan (asyncio.gather) atau satu per satu. Pilihannya bergantung pada sifat tool-nya:

• Bersamaan untuk operasi baca yang tak saling bergantung, supaya pengguna menunggu lebih singkat.
• Berurutan untuk tool yang mengubah sesuatu atau yang saling bergantung. Berhentilah di kegagalan pertama, lalu balas panggilan yang batal dijalankan dengan is_error: true, misalnya "Not executed: the preceding write_file call failed."

Strategi apa pun yang kamu pilih, semua hasil kembali dalam satu pesan user, urut sesuai tool_use_id. Bila model terlalu sering menggabungkan panggilan yang sebenarnya saling bergantung, dokumentasi menyarankan satu kalimat di prompt sistem: "Only batch tool calls that are independent of each other."

Latihan: buat dua tool, satu membaca dan satu menulis. Kapan putaranmu boleh menjalankan keduanya bersamaan, dan kapan tidak?

Di sini ada dua tuas yang berbeda. tool_choice mengatur apakah model memanggil tool, sedangkan strict mengatur bentuk argumennya. Untuk tool yang berakibat nyata, seperti meminjamkan buku, bentuk argumen yang pasti sangat berharga. Skema tool ketat wajib memakai additionalProperties: false:

{
  "name": "pinjam_buku",
  "description": "Meminjamkan satu buku kepada anggota. Hanya dipanggil sesudah pengguna menyetujui peminjaman secara eksplisit.",
  "strict": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "id_buku": { "type": "string" },
      "id_anggota": { "type": "string" },
      "lama_hari": { "type": "integer", "enum": [7, 14] }
    },
    "required": ["id_buku", "id_anggota", "lama_hari"],
    "additionalProperties": false
  }
}

Dengan strict, lama_hari dijamin berupa angka 7 atau 14. Tak akan muncul "seminggu".

Butuh JSON berbentuk tetap tanpa memanggil apa pun? Itu tugas structured outputs (output_config.format), bukan tool pura-pura.

Setelah menulis putaran sendiri, kamu akan menghargai kabar ini: untuk kebanyakan agen, SDK bisa memutarnya untukmu. Tandai fungsi dengan @beta_tool, dan SDK membuat skemanya dari tanda tangan fungsi beserta docstring-nya:

@beta_tool
def cari_buku(kata_kunci: str, maks_hasil: int = 5) -> str:
    """Mencari buku di katalog perpustakaan berdasarkan judul atau nama penulis.

    Args:
        kata_kunci: Judul atau nama penulis, mis. 'Laskar Pelangi'.
        maks_hasil: Jumlah hasil paling banyak, 1 sampai 10.
    """
    return "B-017 | Laskar Pelangi | Andrea Hirata | tersedia 2"


runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=16000,
    tools=[cari_buku],
    messages=[{"role": "user", "content": "Apakah Laskar Pelangi ada?"}],
)
for message in runner:  # satu BetaMessage per giliran; berhenti saat model selesai
    print(message.stop_reason)

Dari tanda tangan itu, SDK menyusun skema dengan kata_kunci wajib, maks_hasil berbawaan 5, dan additionalProperties: false. Ia lalu memanggil model, menjalankan fungsimu saat diminta, mengirim tool_result, dan berhenti ketika model selesai (end_turn).

Tool Runner masih beta, tetapi kamu tidak kehilangan kendali. Setiap giliran bisa diperiksa sebelum tool dijalankan, untuk meminta persetujuan, mencatat, atau menolak. Kembalilah ke putaran manual hanya bila kamu butuh kendali yang tidak disediakannya.

Tool yang nyaman bagi programmer belum tentu nyaman bagi agen. Programmer membaca dokumentasi sekali lalu ingat; agen membaca semuanya token demi token, setiap kali. Artikel Writing effective tools for agents (Anthropic, 2025) merangkum pelajarannya:

• Sedikit tool yang cerdas, bukan bungkus setiap endpoint. Ganti list_contacts dengan search_contacts, dan ganti list_users + list_events + create_event dengan satu schedule_event. Mengembalikan semua kontak hanya memboroskan konteks agen.
• Pisahkan dengan awalan nama (namespace) menurut layanan dan sumber daya: asana_projects_search, asana_users_search.
• Kembalikan konteks yang bermakna. Nama dan istilah yang wajar lebih mudah dipakai model daripada UUID samar. Buang medan teknis yang tak membantu langkah berikutnya.
• Hemat token. Sediakan paginasi, filter, dan pemotongan dengan bawaan yang masuk akal; Claude Code, misalnya, membatasi respons tool 25.000 token. Parameter response_format (concise atau detailed) membiarkan agen memilih sendiri.
• Galat yang mendidik. Pesan galat dan pemotongan bisa mengarahkan agen ke strategi yang lebih hemat, misalnya pencarian yang lebih sempit.
• Jelaskan seperti kepada pegawai baru. Tulis eksplisit hal-hal yang biasanya kamu anggap jelas: format kueri, istilah khusus, hubungan antarsumber daya. Nama parameter pun tak boleh ambigu: user_id, bukan user.

Latihan: ambil satu API yang kamu kenal, lalu rancang tiga tool untuk agen di atasnya, bukan satu tool per endpoint.

Memberi model tool sama dengan memberinya tangan untuk bertindak. Karena itu, perlakukan setiap argumen tool sebagai keluaran model yang belum dipercaya, dan setiap hasil tool dari luar sebagai masukan yang bisa berbahaya.

• Validasi argumen sebelum menjalankan, bahkan bila strict aktif. Skema menjamin bentuk, bukan izin.
• Minta persetujuan manusia untuk tindakan yang berakibat nyata: mengirim, menghapus, membayar. Di putaran manual, periksa tool_use sebelum menjalankannya; di Tool Runner, gerbangnya bisa di dalam fungsi tool atau di pemeriksaan tiap giliran.
• Beri hak akses seperlunya. Tool yang hanya perlu membaca jangan diberi kredensial untuk menulis.
• Kurung jalur berkas. Ubah path dari model ke bentuk kanonik dan pastikan tetap di bawah direktori proyek (Path.resolve() lalu .is_relative_to(root)). Tolak .., symlink, dan jalur absolut di luarnya.
• Perintah shell: izinkan hanya program yang ada di daftar (allowlist), tolak operator &&, |, ;, dan jalankan di lingkungan terisolasi dengan batas waktu. Daftar larangan (blocklist) saja tidak cukup.
• Waspadai injeksi prompt tidak langsung. Halaman web atau email yang dikembalikan tool bisa berisi instruksi palsu. Biarkan isinya di dalam tool_result, dan jangan beri tool berbahaya kepada agen yang membaca isi tak tepercaya tanpa gerbang persetujuan.

Tool yang "terasa" bagus belum tentu dipakai dengan benar. Satu-satunya cara tahu adalah mengukurnya. Writing effective tools for agents menyarankan langkah-langkah ini:

1. Buat banyak tugas evaluasi dari pemakaian nyata, masing-masing dengan jawaban atau hasil yang bisa diperiksa. Tugas yang kuat butuh beberapa panggilan tool: "Jadwalkan rapat dengan Jane minggu depan, lampirkan catatan rapat terakhir, dan pesan ruangan." Tugas yang lemah terlalu harfiah: "Jadwalkan rapat dengan jane@acme.corp minggu depan."
2. Jalankan secara terprogram dengan putaran agen sederhana, satu putaran per tugas.
3. Catat lebih dari sekadar benar atau salah: jumlah panggilan tool, token yang dipakai, waktu, dan galat tool.
4. Baca transkripnya. Panggilan yang berlebihan sering menandakan perlunya paginasi atau tool yang sebaiknya digabung. Parameter yang keliru sering menandakan deskripsi yang ambigu.
5. Ubah satu hal, lalu ukur lagi, dengan set uji yang tidak dipakai saat memperbaiki, supaya hasilnya tidak sekadar cocok dengan soal latihan (overfit).