MessagesInfrastruktur alat

Pemanggilan alat terprogram

Biarkan Claude memanggil alat Anda dari kode di dalam container eksekusi kode, mengurangi perjalanan bolak-balik model dan penggunaan token dalam alur kerja multi-alat.

"Programmatic tool calling" (pemanggilan alat terprogram) memungkinkan Claude menulis kode yang memanggil alat Anda secara terprogram di dalam container code execution, alih-alih memerlukan perjalanan bolak-balik melalui model untuk setiap pemanggilan alat. Ini mengurangi latensi untuk alur kerja multi-alat dan menurunkan konsumsi token dengan memungkinkan Claude memfilter atau memproses data sebelum mencapai jendela konteks model. Pada benchmark pencarian agentik seperti BrowseComp dan DeepSearchQA, yang menguji riset web multilangkah dan pengambilan informasi kompleks, menambahkan pemanggilan alat terprogram di atas alat pencarian dasar meningkatkan kinerja rata-rata 11% sambil menggunakan 24% lebih sedikit token input (lihat Improved web search with dynamic filtering).

Pertimbangkan pemeriksaan kepatuhan anggaran untuk 20 karyawan: pendekatan tradisional memerlukan 20 perjalanan bolak-balik model yang terpisah, menarik ribuan item baris pengeluaran ke dalam konteks di sepanjang jalan. Dengan pemanggilan alat terprogram, satu skrip menjalankan semua 20 pencarian, memfilter hasilnya, dan hanya mengembalikan karyawan yang melebihi batas mereka, menyusutkan apa yang perlu dipertimbangkan Claude dari ratusan kilobyte menjadi hanya beberapa baris.

Kompatibilitas model

Pemanggilan alat terprogram memerlukan code_execution_20260120 atau yang lebih baru, yang didukung pada model-model berikut:

Model
Claude Fable 5 ()
Claude Mythos 5 ()
Claude Opus 5 ()
Claude Opus 4.8 ()
Claude Opus 4.7 ()
Claude Opus 4.6 ()
Claude Sonnet 5 ()
Claude Sonnet 4.6 ()
Claude Opus 4.5 ()
Claude Sonnet 4.5 ()

Untuk matriks versi alat code execution lengkap, lihat tabel kompatibilitas model alat code execution. Pemanggilan alat terprogram tersedia di Claude API, Claude Platform on AWS, dan Microsoft Foundry. Di Microsoft Foundry, pemanggilan alat terprogram memerlukan deployment Hosted on Anthropic. Saat ini tidak tersedia di Amazon Bedrock atau Google Cloud.

Mulai cepat

Berikut adalah contoh di mana Claude secara terprogram melakukan kueri database beberapa kali dan mengagregasi hasilnya:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue",
        }
    ],
    tools=[
        {"type": "code_execution_20260120", "name": "code_execution"},
        {
            "name": "query_database",
            "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "SQL query to execute"}
                },
                "required": ["sql"],
            },
            "allowed_callers": ["code_execution_20260120"],
        },
    ],
)

print(response)

Respons berhenti dengan stop_reason: "tool_use", ID container, dan blok tool_use untuk query_database yang field caller-nya mengidentifikasi eksekusi kode yang memanggilnya. Kembalikan hasilnya seperti yang ditunjukkan di Langkah 3 dari contoh alur kerja agar kode dapat selesai.

Cara kerja pemanggilan alat terprogram

Ketika Anda mengonfigurasi alat agar dapat dipanggil dari code execution dan Claude memutuskan untuk menggunakan alat tersebut:

Claude menulis kode Python yang memanggil alat sebagai fungsi, yang berpotensi mencakup beberapa pemanggilan alat dan logika pra/pasca-pemrosesan
Claude menjalankan kode ini dalam container sandbox melalui code execution
Ketika fungsi alat dipanggil, code execution berhenti sejenak dan API mengembalikan blok tool_use
Anda memberikan hasil alat, dan code execution berlanjut (hasil antara tidak dimuat ke dalam jendela konteks Claude)
Setelah semua code execution selesai, Claude menerima output akhir dan melanjutkan mengerjakan tugas

Pendekatan ini sangat berguna untuk:

Pemrosesan data besar: Memfilter atau mengagregasi hasil alat sebelum mencapai konteks Claude
Alur kerja multilangkah: Menghemat token dan latensi dengan memanggil alat secara berurutan atau dalam loop tanpa melakukan sampling Claude di antara pemanggilan alat
Logika kondisional: Membuat keputusan berdasarkan hasil alat antara

Konsep inti

Field `allowed_callers`

Field allowed_callers menentukan konteks mana yang dapat memanggil sebuah alat:

{
  "name": "query_database",
  "description": "Execute a SQL query against the database",
  "input_schema": {
    // ...
  },
  "allowed_callers": ["code_execution_20260120"]
}

Nilai yang mungkin:

["direct"] - Claude diarahkan untuk memanggil alat ini secara langsung (default jika dihilangkan)
["code_execution_20260120"] - Claude diarahkan untuk memanggil alat ini hanya dari dalam code execution
["direct", "code_execution_20260120"] - Claude dapat memanggil alat ini secara langsung atau dari dalam code execution

Baik "code_execution_20260120" maupun "code_execution_20260521" diterima dalam allowed_callers dan dapat dipertukarkan: permintaan yang menggunakan salah satu versi alat code-execution memenuhi alat yang mencantumkan salah satu pemanggil. Blok respons selalu menandai pemanggil sebagai code_execution_20260120 terlepas dari versi mana yang dideklarasikan oleh permintaan.

Field `caller` dalam respons

Setiap blok tool use menyertakan field caller yang menunjukkan bagaimana alat tersebut dipanggil:

Pemanggilan langsung (penggunaan alat tradisional):

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": { "type": "direct" }
}

Pemanggilan terprogram:

{
  "type": "tool_use",
  "id": "toolu_xyz789",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_abc123"
  }
}

tool_id adalah id dari blok server_tool_use code execution yang melakukan pemanggilan, sehingga Anda dapat mencocokkan setiap tool_use terprogram dengan eksekusi kode yang menghasilkannya.

Siklus hidup container

Pemanggilan alat terprogram menggunakan container yang sama dengan code execution:

Pembuatan container: Container baru dibuat untuk setiap permintaan kecuali Anda menggunakan kembali yang sudah ada
ID container: Dikembalikan dalam respons di field container, bersama dengan timestamp expires_at
Penggunaan kembali: Kirimkan kembali ID container pada permintaan berikutnya untuk mempertahankan state. Saat pemanggilan alat terprogram sedang menunggu hasil Anda, ID container diperlukan pada permintaan tersebut, bukan opsional: API menolak permintaan tanpanya.
Kedaluwarsa: expires_at memberi tahu Anda berapa lama waktu yang tersisa untuk container. Container yang menganggur saat ini diklaim kembali setelah sekitar 5 menit, dan tidak ada container yang dapat digunakan kembali lebih dari 30 hari setelah dibuat.

Contoh alur kerja

Berikut adalah cara kerja alur pemanggilan alat terprogram yang lengkap:

Langkah 1: Permintaan awal

Kirim permintaan dengan code execution dan alat yang mengizinkan pemanggilan terprogram. Untuk mengaktifkan pemanggilan terprogram, tambahkan field allowed_callers ke definisi alat Anda.

Bentuk permintaannya identik dengan contoh Mulai cepat: sertakan code_execution dalam daftar alat Anda, tambahkan allowed_callers: ["code_execution_20260120"] ke alat apa pun yang Anda ingin Claude panggil dari kode, dan kirim pesan pengguna Anda. Langkah-langkah selanjutnya dalam alur kerja ini menggunakan pesan pengguna "Query customer purchase history from the last quarter and identify our top 5 customers by revenue".

Langkah 2: Respons API dengan pemanggilan alat

Claude menulis kode yang memanggil alat Anda. API berhenti sejenak dan mengembalikan:

Output

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll query the purchase history and analyze the results."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "code_execution",
      "input": {
        "code": "import json\n\nrows = json.loads(await query_database({'sql': '<sql>'}))\ntop_customers = sorted(rows, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')"
      }
    },
    {
      "type": "tool_use",
      "id": "toolu_def456",
      "name": "query_database",
      "input": { "sql": "<sql>" },
      "caller": {
        "type": "code_execution_20260120",
        "tool_id": "srvtoolu_abc123"
      }
    }
  ],
  "container": {
    "id": "container_xyz789",
    "expires_at": "2026-01-20T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

Langkah 3: Berikan hasil alat

Kirim riwayat percakapan lengkap ditambah hasil alat Anda. Tiga detail penting pada permintaan ini:

Pesan pengguna yang membawa hasil Anda hanya boleh berisi blok tool_result. Lihat Pembatasan pemformatan pesan.
Kirimkan ID container dari respons yang dijeda. API menolak kelanjutan yang memiliki pemanggilan alat terprogram yang tertunda tetapi tidak memiliki ID container.
Kirim array tools yang sama dengan permintaan asli. Alat code execution harus tetap ada agar kode yang dijeda dapat dilanjutkan, dan alat yang Anda kirim pada permintaan ini adalah definisi yang dapat digunakan Claude dan kode yang sedang berjalan untuk sisa giliran tersebut.

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container="container_xyz789",  # Reuse the container
    messages=[
        {
            "role": "user",
            "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'll query the purchase history and analyze the results.",
                },
                {
                    "type": "server_tool_use",
                    "id": "srvtoolu_abc123",
                    "name": "code_execution",
                    "input": {"code": "..."},
                },
                {
                    "type": "tool_use",
                    "id": "toolu_def456",
                    "name": "query_database",
                    "input": {"sql": "<sql>"},
                    "caller": {
                        "type": "code_execution_20260120",
                        "tool_id": "srvtoolu_abc123",
                    },
                },
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_def456",
                    "content": '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]',
                }
            ],
        },
    ],
    # Array tools yang sama dengan permintaan asli
    tools=[
        {"type": "code_execution_20260120", "name": "code_execution"},
        {
            "name": "query_database",
            "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "SQL query to execute"}
                },
                "required": ["sql"],
            },
            "allowed_callers": ["code_execution_20260120"],
        },
    ],
)

print(response)

Langkah 4: Pemanggilan alat berikutnya atau penyelesaian

Kode melanjutkan dari tempat ia dijeda dan memproses hasil Anda. Setiap respons kelanjutan akan berhenti sejenak lagi dengan lebih banyak blok tool_use terprogram, atau menyelesaikan code execution dan membiarkan Claude melanjutkan giliran (Langkah 5). Periksa stop_reason dan caller dari setiap blok tool_use untuk membedakan keduanya: respons yang berhenti sejenak untuk Anda memiliki stop_reason: "tool_use" dan blok tool_use yang caller-nya menyebutkan versi code execution, dan Anda mengulangi Langkah 3 dengan tool_result untuk setiap pemanggilan terprogram yang tertunda dalam satu pesan pengguna.

Langkah 5: Respons akhir

Setelah code execution selesai, Claude memberikan respons akhir:

Output

{
  "content": [
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "code_execution_result",
        "stdout": "Top 5 customers: [{'customer_id': 'C1', 'revenue': 45000}, {'customer_id': 'C2', 'revenue': 38000}, {'customer_id': 'C5', 'revenue': 32000}, {'customer_id': 'C8', 'revenue': 28500}, {'customer_id': 'C3', 'revenue': 24000}]",
        "stderr": "",
        "return_code": 0,
        "content": []
      }
    },
    {
      "type": "text",
      "text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000."
    }
  ],
  "stop_reason": "end_turn"
}

Pola lanjutan

Pemrosesan batch dengan loop

Claude dapat menulis kode yang memproses beberapa item secara efisien:

regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
    rows = json.loads(await query_database({"sql": f"<sql for {region}>"}))
    results[region] = sum(row["revenue"] for row in rows)

# Memproses hasil secara terprogram
top_region = max(results.items(), key=lambda x: x[1])
print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")

Pola ini:

Mengurangi perjalanan bolak-balik model dari N (satu per wilayah) menjadi 1
Memproses kumpulan hasil besar secara terprogram sebelum kembali ke Claude
Menghemat token dengan hanya mengembalikan kesimpulan teragregasi alih-alih data mentah

Penghentian dini

Claude dapat menghentikan pemrosesan segera setelah kriteria keberhasilan terpenuhi:

endpoints = ["us-east", "eu-west", "apac"]
for endpoint in endpoints:
    status = await check_health({"endpoint": endpoint})
    if status == "healthy":
        print(f"Found healthy endpoint: {endpoint}")
        break  # Stop early, don't check remaining

Pemilihan alat kondisional

path = "/tmp/example.txt"
file_info = json.loads(await get_file_info({"path": path}))
if file_info["size"] < 10000:
    content = await read_full_file({"path": path})
else:
    content = await read_file_summary({"path": path})
print(content)

Pemfilteran data

server_id = "srv-01"
log_text = await fetch_logs({"server_id": server_id})
errors = [line for line in log_text.splitlines() if "ERROR" in line]
print(f"Found {len(errors)} errors")
for error in errors[-10:]:  # Only return last 10 errors
    print(error)

Format respons

Pemanggilan alat terprogram

Ketika code execution memanggil sebuah alat:

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_xyz789"
  }
}

Penanganan hasil alat

Hasil alat Anda diteruskan kembali ke kode yang sedang berjalan:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_abc123",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
    }
  ]
}

Penyelesaian code execution

Ketika semua pemanggilan alat terpenuhi dan kode selesai:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_xyz789",
  "content": {
    "type": "code_execution_result",
    "stdout": "Analysis complete. Top 5 customers identified from 847 total records.",
    "stderr": "",
    "return_code": 0,
    "content": []
  }
}

Penanganan error

Error umum

Error	Di mana muncul	Deskripsi	Solusi
`invalid_tool_input`	`error_code` pada blok error `code_execution_tool_result` dalam respons	Parameter yang tidak valid diteruskan ke alat code execution	Lihat error alat code execution
`invalid_request_error` (pada `tool_choice`)	Respons error HTTP 400	`tool_choice` menyebutkan alat yang `allowed_callers`-nya tidak menyertakan `"direct"`	Tambahkan `"direct"` ke `allowed_callers` alat tersebut, atau hapus alat dari `tool_choice` dan biarkan Claude memanggilnya dari kode

Kedaluwarsa container selama pemanggilan alat

Jika hasil alat Anda tidak tiba dalam waktu sekitar 4 menit, pemanggilan yang tertunda memunculkan TimeoutError di dalam kode Claude yang sedang berjalan. Claude melihat error di stderr dan biasanya mencoba ulang pemanggilan tersebut:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "TimeoutError: Calling tool ['query_database'] timed out (no response after 270s).",
    "return_code": 0,
    "content": []
  }
}

Untuk mencegah timeout:

Pantau field expires_at dalam respons
Implementasikan timeout untuk eksekusi alat Anda
Pertimbangkan untuk memecah operasi panjang menjadi bagian-bagian yang lebih kecil

Error eksekusi alat

Jika alat Anda mengembalikan error:

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "Error: Query timeout - table lock exceeded 30 seconds"
}

Kode Claude menerima error ini dan dapat menanganinya dengan tepat.

Batasan dan keterbatasan

Ketidakcocokan fitur

Structured outputs: Alat dengan strict: true tidak didukung dengan pemanggilan terprogram
Tool choice: Anda tidak dapat memaksa pemanggilan terprogram dari alat tertentu melalui tool_choice
Parallel tool use: disable_parallel_tool_use: true tidak didukung dengan pemanggilan terprogram

Keterbatasan skema input

Alat kustom yang input_schema-nya berisi $ref rekursif (siklus referensi, seperti skema yang merujuk pada dirinya sendiri) tidak dapat diaktifkan untuk pemanggilan terprogram. Menyertakan versi alat code execution dalam allowed_callers untuk alat semacam itu menyebabkan permintaan gagal dengan 400 invalid_request_error yang pesannya berisi Circular $ref detected. Skema yang sama diterima untuk pemanggilan alat langsung.

Untuk mengatasi hal ini, lakukan salah satu dari berikut:

Pertahankan alat hanya untuk pemanggilan langsung dengan menghilangkan allowed_callers (atau mengaturnya ke ["direct"]). Alat lain dalam permintaan yang sama masih dapat menggunakan pemanggilan terprogram.
Hapus siklus dari skema. Misalnya, uraikan rekursi ke kedalaman tetap dan jelaskan penyarangan yang lebih dalam di description pada tingkat terdalam, atau ganti properti rekursif dengan {"type": "object"} biasa yang description-nya menjelaskan bentuk yang diharapkan.

Pembatasan alat

Alat-alat berikut tidak dapat dipanggil secara terprogram:

Alat yang disediakan oleh MCP connector

Pembatasan pemformatan pesan

Saat merespons pemanggilan alat terprogram, ada persyaratan pemformatan yang ketat:

Respons hanya hasil alat: Jika ada pemanggilan alat terprogram yang tertunda menunggu hasil, pesan respons Anda harus berisi hanya blok tool_result. Anda tidak dapat menyertakan konten teks apa pun, bahkan setelah hasil alat.

Tidak valid - Tidak dapat menyertakan teks saat merespons pemanggilan alat terprogram:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    },
    { "type": "text", "text": "What should I do next?" }
  ]
}

Valid - Hanya hasil alat saat merespons pemanggilan alat terprogram:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    }
  ]
}

Pembatasan ini hanya berlaku saat merespons pemanggilan alat terprogram (code execution). Untuk pemanggilan alat sisi klien biasa, Anda dapat menyertakan konten teks setelah hasil alat.

Konten hasil alat hanya teks: content dari setiap tool_result yang menjawab pemanggilan terprogram harus berupa string atau blok text. Tipe blok konten gambar, dokumen, dan lainnya ditolak.

Batas laju

Pemanggilan alat terprogram tunduk pada batas laju yang sama dengan pemanggilan alat biasa. Setiap pemanggilan alat dari code execution dihitung sebagai pemanggilan terpisah.

Validasi hasil alat sebelum digunakan

Saat mengimplementasikan alat yang didefinisikan pengguna yang akan dipanggil secara terprogram:

Hasil alat dikembalikan sebagai string: Hasil tersebut dapat berisi konten apa pun, termasuk cuplikan kode atau perintah yang dapat dieksekusi yang mungkin diproses oleh lingkungan eksekusi.
Validasi hasil alat eksternal: Jika alat Anda mengembalikan data dari sumber eksternal atau menerima input pengguna, waspadai risiko injeksi kode jika output akan diinterpretasikan atau dieksekusi sebagai kode.

Efisiensi token

Pemanggilan alat terprogram mengurangi konsumsi token dengan tiga cara:

Hasil alat dari pemanggilan terprogram tidak ditambahkan ke konteks Claude - hanya output kode akhir yang ditambahkan
Pemrosesan antara terjadi dalam kode - pemfilteran, agregasi, dan transformasi lainnya tidak mengonsumsi token model
Beberapa pemanggilan alat dalam satu code execution - mengurangi overhead dibandingkan dengan giliran model yang terpisah

Misalnya, memanggil 10 alat secara langsung menggunakan ~10x token dibandingkan memanggilnya secara terprogram dan mengembalikan ringkasan.

Dalam evaluasi internal Anthropic pada model Claude produksi:

Pada benchmark agen manajemen proyek dengan 75 alat, mengaktifkan pemanggilan alat terprogram mengurangi token input yang ditagih sekitar 38% tanpa perubahan akurasi tugas.
Pada τ²-bench (domain maskapai penerbangan, ritel, dan telekomunikasi), di mana setiap giliran melakukan satu atau dua pemanggilan alat berurutan, pemanggilan alat terprogram tidak mengubah skor dan biayanya sekitar 8% lebih mahal. Alur kerja pemanggilan tunggal berurutan tidak mendapat manfaat.
Di seluruh lalu lintas API produksi, permintaan yang array tools-nya berisi 10 hingga 49 definisi alat melihat penghematan token tipikal 20% hingga 40% dengan pemanggilan alat terprogram diaktifkan.

Penghematan aktual bervariasi tergantung bentuk beban kerja. Lihat Kapan menggunakan pemanggilan terprogram.

Penggunaan dan harga

Pemanggilan alat terprogram menggunakan harga yang sama dengan code execution. Lihat harga code execution untuk detailnya.

Praktik terbaik

Desain alat

Berikan deskripsi output yang terperinci: Karena Claude melakukan deserialisasi hasil alat dalam kode, dokumentasikan formatnya (struktur JSON dan tipe field)
Kembalikan data terstruktur: JSON atau format lain yang dapat dibaca mesin bekerja paling baik untuk pemrosesan terprogram
Jaga respons tetap ringkas: Kembalikan hanya data yang diperlukan untuk meminimalkan overhead pemrosesan

Kapan menggunakan pemanggilan terprogram

Pemanggilan alat terprogram menukar overhead tetap yang kecil (startup container, pembuatan skrip) dengan penghematan besar pada token hasil alat dan perjalanan bolak-balik model. Apakah pertukaran itu menguntungkan tergantung pada bentuk beban kerja.

Sangat cocok:

Operasi fan-out atau paralel di banyak item (misalnya, memeriksa 50 endpoint atau mencari 20 catatan)
Hasil alat besar yang dapat difilter, diagregasi, atau diringkas sebelum mencapai konteks Claude
Pencarian dan pengambilan agentik, di mana kueri iteratif dan pemfilteran hasil mendominasi alur kerja

Kurang cocok:

Alur kerja yang benar-benar berurutan di mana setiap pemanggilan bergantung pada penalaran Claude atas hasil sebelumnya, karena skrip tidak dapat melewati perjalanan bolak-balik model dalam kasus tersebut
Sejumlah kecil pemanggilan alat dengan respons kecil, terutama pada giliran pertama percakapan, di mana overhead container dan skrip dapat melebihi penghematan
Alat yang memerlukan umpan balik pengguna segera di antara pemanggilan

Jika Anda tidak yakin, ukur token input yang ditagih dengan dan tanpa allowed_callers pada sampel representatif dari lalu lintas Anda sebelum mengaktifkannya secara luas.

Optimasi kinerja

Gunakan kembali container saat membuat beberapa permintaan terkait untuk mempertahankan state
Kelompokkan operasi serupa dalam satu code execution jika memungkinkan

Pemecahan masalah

Masalah umum

invalid_request_error saat mengatur tool_choice

tool_choice tidak dapat menyebutkan alat yang allowed_callers-nya menghilangkan "direct". Tambahkan "direct" ke allowed_callers alat tersebut, atau hapus alat dari tool_choice dan biarkan Claude memanggilnya dari kode.

Kedaluwarsa container

Respons setiap pemanggilan alat terprogram jauh sebelum timestamp expires_at dari respons yang dijeda. Kode Claude berhenti menunggu hasil setelah sekitar 4 menit, dan container yang menganggur saat ini diklaim kembali setelah sekitar 5 menit.
Pertimbangkan untuk mengimplementasikan eksekusi alat yang lebih cepat

Hasil alat tidak di-parse dengan benar

Pastikan alat Anda mengembalikan data string yang dapat dideserialisasi oleh Claude
Berikan dokumentasi format output yang jelas dalam deskripsi alat Anda

Tips debugging

Catat semua pemanggilan alat dan hasilnya untuk melacak alur
Periksa field caller untuk mengonfirmasi pemanggilan terprogram
Pantau ID container untuk memastikan penggunaan kembali yang tepat
Uji alat secara independen sebelum mengaktifkan pemanggilan terprogram

Mengapa pemanggilan alat terprogram berhasil

Claude dilatih pada sejumlah besar kode, sehingga menyajikan alat sebagai fungsi Python yang dapat dipanggil memungkinkannya menggunakan kekuatan tersebut:

Komposisi alat: Pemanggilan berantai, loop, dan kondisional adalah alur kontrol Python biasa alih-alih serangkaian perjalanan bolak-balik model
Pemrosesan hasil: Kode Claude memfilter dan mengagregasi output alat yang besar, atau menulisnya ke file, dan hanya output akhir yang masuk ke jendela konteks
Latensi: Model tidak di-sampling ulang di antara pemanggilan alat dalam satu code execution

Implementasi alternatif

Pemanggilan alat terprogram adalah pola yang dapat digeneralisasi yang juga dapat diimplementasikan pada infrastruktur Anda sendiri. Berikut perbandingan pendekatannya:

Eksekusi langsung sisi klien

Berikan Claude alat code execution dan jelaskan fungsi apa yang tersedia di lingkungan tersebut. Ketika Claude memanggil alat dengan kode, aplikasi Anda mengeksekusinya secara lokal di mana fungsi-fungsi tersebut didefinisikan.

Keuntungan:

Perubahan arsitektur minimal pada aplikasi Anda
Kontrol penuh atas lingkungan dan instruksi

Kerugian:

Mengeksekusi kode yang tidak tepercaya di luar sandbox
Pemanggilan alat dapat menjadi vektor untuk injeksi kode

Gunakan ketika: Aplikasi Anda dapat mengeksekusi kode arbitrer dengan aman, Anda menginginkan implementasi terkecil, dan penawaran terkelola Anthropic tidak sesuai dengan kebutuhan Anda.

Eksekusi sandbox yang dikelola sendiri

Pendekatan yang sama dari perspektif Claude, tetapi kode berjalan dalam container sandbox dengan pembatasan keamanan (misalnya, tanpa egress jaringan). Jika alat Anda memerlukan sumber daya eksternal, Anda memerlukan protokol untuk mengeksekusi pemanggilan alat di luar sandbox.

Keuntungan:

Pemanggilan alat terprogram yang aman pada infrastruktur Anda sendiri
Kontrol penuh atas lingkungan eksekusi

Kerugian:

Kompleks untuk dibangun dan dipelihara
Memerlukan pengelolaan infrastruktur dan komunikasi antar-proses

Gunakan ketika: Keamanan sangat penting dan solusi terkelola Anthropic tidak sesuai dengan kebutuhan Anda.

Eksekusi yang dikelola Anthropic

Pemanggilan alat terprogram Anthropic adalah versi terkelola dari eksekusi sandbox dengan lingkungan Python yang disesuaikan untuk Claude. Anthropic menangani pengelolaan container, code execution, dan komunikasi pemanggilan alat yang aman.

Keuntungan:

Aman dan terlindungi secara default
Diaktifkan dengan definisi alat, tanpa infrastruktur yang perlu dijalankan
Lingkungan dan instruksi dioptimalkan untuk Claude

Pertimbangkan untuk menggunakan solusi terkelola Anthropic jika Anda menggunakan Claude API, Claude Platform on AWS, atau Microsoft Foundry. Di Microsoft Foundry, pemanggilan alat terprogram memerlukan deployment Hosted on Anthropic.

Retensi data

Pemanggilan alat terprogram dibangun di atas infrastruktur code execution dan menggunakan container sandbox yang sama. Data container, termasuk artefak eksekusi dan output, disimpan hingga 30 hari.

Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.

Langkah selanjutnya

Streaming alat berbutir halus

Streaming input alat tanpa buffering JSON sisi server untuk aplikasi yang sensitif terhadap latensi.

Alat code execution

Jalankan kode Python dan bash dalam container sandbox untuk menganalisis data, menghasilkan file, dan mengiterasi solusi.

Penggunaan alat dengan Claude

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

Definisikan alat

Tentukan skema alat, tulis deskripsi yang efektif, dan kontrol kapan Claude memanggil alat Anda.

Was this page helpful?

MessagesInfrastruktur alat

Pemanggilan alat terprogram

Biarkan Claude memanggil alat Anda dari kode di dalam container eksekusi kode, mengurangi perjalanan bolak-balik model dan penggunaan token dalam alur kerja multi-alat.

Kompatibilitas model

Pemanggilan alat terprogram memerlukan code_execution_20260120 atau yang lebih baru, yang didukung pada model-model berikut:

Model
Claude Fable 5 ()
Claude Mythos 5 ()
Claude Opus 5 ()
Claude Opus 4.8 ()
Claude Opus 4.7 ()
Claude Opus 4.6 ()
Claude Sonnet 5 ()
Claude Sonnet 4.6 ()
Claude Opus 4.5 ()
Claude Sonnet 4.5 ()

Mulai cepat

Berikut adalah contoh di mana Claude secara terprogram melakukan kueri database beberapa kali dan mengagregasi hasilnya:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue",
        }
    ],
    tools=[
        {"type": "code_execution_20260120", "name": "code_execution"},
        {
            "name": "query_database",
            "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "SQL query to execute"}
                },
                "required": ["sql"],
            },
            "allowed_callers": ["code_execution_20260120"],
        },
    ],
)

print(response)

Cara kerja pemanggilan alat terprogram

Ketika Anda mengonfigurasi alat agar dapat dipanggil dari code execution dan Claude memutuskan untuk menggunakan alat tersebut:

Claude menulis kode Python yang memanggil alat sebagai fungsi, yang berpotensi mencakup beberapa pemanggilan alat dan logika pra/pasca-pemrosesan
Claude menjalankan kode ini dalam container sandbox melalui code execution
Ketika fungsi alat dipanggil, code execution berhenti sejenak dan API mengembalikan blok tool_use
Anda memberikan hasil alat, dan code execution berlanjut (hasil antara tidak dimuat ke dalam jendela konteks Claude)
Setelah semua code execution selesai, Claude menerima output akhir dan melanjutkan mengerjakan tugas

Pendekatan ini sangat berguna untuk:

Pemrosesan data besar: Memfilter atau mengagregasi hasil alat sebelum mencapai konteks Claude
Alur kerja multilangkah: Menghemat token dan latensi dengan memanggil alat secara berurutan atau dalam loop tanpa melakukan sampling Claude di antara pemanggilan alat
Logika kondisional: Membuat keputusan berdasarkan hasil alat antara

Konsep inti

Field `allowed_callers`

Field allowed_callers menentukan konteks mana yang dapat memanggil sebuah alat:

{
  "name": "query_database",
  "description": "Execute a SQL query against the database",
  "input_schema": {
    // ...
  },
  "allowed_callers": ["code_execution_20260120"]
}

Nilai yang mungkin:

["direct"] - Claude diarahkan untuk memanggil alat ini secara langsung (default jika dihilangkan)
["code_execution_20260120"] - Claude diarahkan untuk memanggil alat ini hanya dari dalam code execution
["direct", "code_execution_20260120"] - Claude dapat memanggil alat ini secara langsung atau dari dalam code execution

Field `caller` dalam respons

Setiap blok tool use menyertakan field caller yang menunjukkan bagaimana alat tersebut dipanggil:

Pemanggilan langsung (penggunaan alat tradisional):

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": { "type": "direct" }
}

Pemanggilan terprogram:

{
  "type": "tool_use",
  "id": "toolu_xyz789",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_abc123"
  }
}

tool_id adalah id dari blok server_tool_use code execution yang melakukan pemanggilan, sehingga Anda dapat mencocokkan setiap tool_use terprogram dengan eksekusi kode yang menghasilkannya.

Siklus hidup container

Pemanggilan alat terprogram menggunakan container yang sama dengan code execution:

Pembuatan container: Container baru dibuat untuk setiap permintaan kecuali Anda menggunakan kembali yang sudah ada
ID container: Dikembalikan dalam respons di field container, bersama dengan timestamp expires_at
Penggunaan kembali: Kirimkan kembali ID container pada permintaan berikutnya untuk mempertahankan state. Saat pemanggilan alat terprogram sedang menunggu hasil Anda, ID container diperlukan pada permintaan tersebut, bukan opsional: API menolak permintaan tanpanya.
Kedaluwarsa: expires_at memberi tahu Anda berapa lama waktu yang tersisa untuk container. Container yang menganggur saat ini diklaim kembali setelah sekitar 5 menit, dan tidak ada container yang dapat digunakan kembali lebih dari 30 hari setelah dibuat.

Contoh alur kerja

Berikut adalah cara kerja alur pemanggilan alat terprogram yang lengkap:

Langkah 1: Permintaan awal

Kirim permintaan dengan code execution dan alat yang mengizinkan pemanggilan terprogram. Untuk mengaktifkan pemanggilan terprogram, tambahkan field allowed_callers ke definisi alat Anda.

Langkah 2: Respons API dengan pemanggilan alat

Claude menulis kode yang memanggil alat Anda. API berhenti sejenak dan mengembalikan:

Output

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll query the purchase history and analyze the results."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "code_execution",
      "input": {
        "code": "import json\n\nrows = json.loads(await query_database({'sql': '<sql>'}))\ntop_customers = sorted(rows, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')"
      }
    },
    {
      "type": "tool_use",
      "id": "toolu_def456",
      "name": "query_database",
      "input": { "sql": "<sql>" },
      "caller": {
        "type": "code_execution_20260120",
        "tool_id": "srvtoolu_abc123"
      }
    }
  ],
  "container": {
    "id": "container_xyz789",
    "expires_at": "2026-01-20T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

Langkah 3: Berikan hasil alat

Kirim riwayat percakapan lengkap ditambah hasil alat Anda. Tiga detail penting pada permintaan ini:

Pesan pengguna yang membawa hasil Anda hanya boleh berisi blok tool_result. Lihat Pembatasan pemformatan pesan.
Kirimkan ID container dari respons yang dijeda. API menolak kelanjutan yang memiliki pemanggilan alat terprogram yang tertunda tetapi tidak memiliki ID container.
Kirim array tools yang sama dengan permintaan asli. Alat code execution harus tetap ada agar kode yang dijeda dapat dilanjutkan, dan alat yang Anda kirim pada permintaan ini adalah definisi yang dapat digunakan Claude dan kode yang sedang berjalan untuk sisa giliran tersebut.

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container="container_xyz789",  # Reuse the container
    messages=[
        {
            "role": "user",
            "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'll query the purchase history and analyze the results.",
                },
                {
                    "type": "server_tool_use",
                    "id": "srvtoolu_abc123",
                    "name": "code_execution",
                    "input": {"code": "..."},
                },
                {
                    "type": "tool_use",
                    "id": "toolu_def456",
                    "name": "query_database",
                    "input": {"sql": "<sql>"},
                    "caller": {
                        "type": "code_execution_20260120",
                        "tool_id": "srvtoolu_abc123",
                    },
                },
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_def456",
                    "content": '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]',
                }
            ],
        },
    ],
    # Array tools yang sama dengan permintaan asli
    tools=[
        {"type": "code_execution_20260120", "name": "code_execution"},
        {
            "name": "query_database",
            "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "SQL query to execute"}
                },
                "required": ["sql"],
            },
            "allowed_callers": ["code_execution_20260120"],
        },
    ],
)

print(response)

Langkah 4: Pemanggilan alat berikutnya atau penyelesaian

Langkah 5: Respons akhir

Setelah code execution selesai, Claude memberikan respons akhir:

Output

{
  "content": [
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "code_execution_result",
        "stdout": "Top 5 customers: [{'customer_id': 'C1', 'revenue': 45000}, {'customer_id': 'C2', 'revenue': 38000}, {'customer_id': 'C5', 'revenue': 32000}, {'customer_id': 'C8', 'revenue': 28500}, {'customer_id': 'C3', 'revenue': 24000}]",
        "stderr": "",
        "return_code": 0,
        "content": []
      }
    },
    {
      "type": "text",
      "text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000."
    }
  ],
  "stop_reason": "end_turn"
}

Pola lanjutan

Pemrosesan batch dengan loop

Claude dapat menulis kode yang memproses beberapa item secara efisien:

regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
    rows = json.loads(await query_database({"sql": f"<sql for {region}>"}))
    results[region] = sum(row["revenue"] for row in rows)

# Memproses hasil secara terprogram
top_region = max(results.items(), key=lambda x: x[1])
print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")

Pola ini:

Mengurangi perjalanan bolak-balik model dari N (satu per wilayah) menjadi 1
Memproses kumpulan hasil besar secara terprogram sebelum kembali ke Claude
Menghemat token dengan hanya mengembalikan kesimpulan teragregasi alih-alih data mentah

Penghentian dini

Claude dapat menghentikan pemrosesan segera setelah kriteria keberhasilan terpenuhi:

endpoints = ["us-east", "eu-west", "apac"]
for endpoint in endpoints:
    status = await check_health({"endpoint": endpoint})
    if status == "healthy":
        print(f"Found healthy endpoint: {endpoint}")
        break  # Stop early, don't check remaining

Pemilihan alat kondisional

path = "/tmp/example.txt"
file_info = json.loads(await get_file_info({"path": path}))
if file_info["size"] < 10000:
    content = await read_full_file({"path": path})
else:
    content = await read_file_summary({"path": path})
print(content)

Pemfilteran data

server_id = "srv-01"
log_text = await fetch_logs({"server_id": server_id})
errors = [line for line in log_text.splitlines() if "ERROR" in line]
print(f"Found {len(errors)} errors")
for error in errors[-10:]:  # Only return last 10 errors
    print(error)

Format respons

Pemanggilan alat terprogram

Ketika code execution memanggil sebuah alat:

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_xyz789"
  }
}

Penanganan hasil alat

Hasil alat Anda diteruskan kembali ke kode yang sedang berjalan:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_abc123",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
    }
  ]
}

Penyelesaian code execution

Ketika semua pemanggilan alat terpenuhi dan kode selesai:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_xyz789",
  "content": {
    "type": "code_execution_result",
    "stdout": "Analysis complete. Top 5 customers identified from 847 total records.",
    "stderr": "",
    "return_code": 0,
    "content": []
  }
}

Penanganan error

Error umum

Error	Di mana muncul	Deskripsi	Solusi
`invalid_tool_input`	`error_code` pada blok error `code_execution_tool_result` dalam respons	Parameter yang tidak valid diteruskan ke alat code execution	Lihat error alat code execution
`invalid_request_error` (pada `tool_choice`)	Respons error HTTP 400	`tool_choice` menyebutkan alat yang `allowed_callers`-nya tidak menyertakan `"direct"`	Tambahkan `"direct"` ke `allowed_callers` alat tersebut, atau hapus alat dari `tool_choice` dan biarkan Claude memanggilnya dari kode

Kedaluwarsa container selama pemanggilan alat

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "TimeoutError: Calling tool ['query_database'] timed out (no response after 270s).",
    "return_code": 0,
    "content": []
  }
}

Untuk mencegah timeout:

Pantau field expires_at dalam respons
Implementasikan timeout untuk eksekusi alat Anda
Pertimbangkan untuk memecah operasi panjang menjadi bagian-bagian yang lebih kecil

Error eksekusi alat

Jika alat Anda mengembalikan error:

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "Error: Query timeout - table lock exceeded 30 seconds"
}

Kode Claude menerima error ini dan dapat menanganinya dengan tepat.

Batasan dan keterbatasan

Ketidakcocokan fitur

Structured outputs: Alat dengan strict: true tidak didukung dengan pemanggilan terprogram
Tool choice: Anda tidak dapat memaksa pemanggilan terprogram dari alat tertentu melalui tool_choice
Parallel tool use: disable_parallel_tool_use: true tidak didukung dengan pemanggilan terprogram

Keterbatasan skema input

Untuk mengatasi hal ini, lakukan salah satu dari berikut:

Pertahankan alat hanya untuk pemanggilan langsung dengan menghilangkan allowed_callers (atau mengaturnya ke ["direct"]). Alat lain dalam permintaan yang sama masih dapat menggunakan pemanggilan terprogram.
Hapus siklus dari skema. Misalnya, uraikan rekursi ke kedalaman tetap dan jelaskan penyarangan yang lebih dalam di description pada tingkat terdalam, atau ganti properti rekursif dengan {"type": "object"} biasa yang description-nya menjelaskan bentuk yang diharapkan.

Pembatasan alat

Alat-alat berikut tidak dapat dipanggil secara terprogram:

Alat yang disediakan oleh MCP connector

Pembatasan pemformatan pesan

Saat merespons pemanggilan alat terprogram, ada persyaratan pemformatan yang ketat:

Tidak valid - Tidak dapat menyertakan teks saat merespons pemanggilan alat terprogram:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    },
    { "type": "text", "text": "What should I do next?" }
  ]
}

Valid - Hanya hasil alat saat merespons pemanggilan alat terprogram:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    }
  ]
}

Pembatasan ini hanya berlaku saat merespons pemanggilan alat terprogram (code execution). Untuk pemanggilan alat sisi klien biasa, Anda dapat menyertakan konten teks setelah hasil alat.

Konten hasil alat hanya teks: content dari setiap tool_result yang menjawab pemanggilan terprogram harus berupa string atau blok text. Tipe blok konten gambar, dokumen, dan lainnya ditolak.

Batas laju

Pemanggilan alat terprogram tunduk pada batas laju yang sama dengan pemanggilan alat biasa. Setiap pemanggilan alat dari code execution dihitung sebagai pemanggilan terpisah.

Validasi hasil alat sebelum digunakan

Saat mengimplementasikan alat yang didefinisikan pengguna yang akan dipanggil secara terprogram:

Hasil alat dikembalikan sebagai string: Hasil tersebut dapat berisi konten apa pun, termasuk cuplikan kode atau perintah yang dapat dieksekusi yang mungkin diproses oleh lingkungan eksekusi.
Validasi hasil alat eksternal: Jika alat Anda mengembalikan data dari sumber eksternal atau menerima input pengguna, waspadai risiko injeksi kode jika output akan diinterpretasikan atau dieksekusi sebagai kode.

Efisiensi token

Pemanggilan alat terprogram mengurangi konsumsi token dengan tiga cara:

Hasil alat dari pemanggilan terprogram tidak ditambahkan ke konteks Claude - hanya output kode akhir yang ditambahkan
Pemrosesan antara terjadi dalam kode - pemfilteran, agregasi, dan transformasi lainnya tidak mengonsumsi token model
Beberapa pemanggilan alat dalam satu code execution - mengurangi overhead dibandingkan dengan giliran model yang terpisah

Misalnya, memanggil 10 alat secara langsung menggunakan ~10x token dibandingkan memanggilnya secara terprogram dan mengembalikan ringkasan.

Dalam evaluasi internal Anthropic pada model Claude produksi:

Pada benchmark agen manajemen proyek dengan 75 alat, mengaktifkan pemanggilan alat terprogram mengurangi token input yang ditagih sekitar 38% tanpa perubahan akurasi tugas.
Pada τ²-bench (domain maskapai penerbangan, ritel, dan telekomunikasi), di mana setiap giliran melakukan satu atau dua pemanggilan alat berurutan, pemanggilan alat terprogram tidak mengubah skor dan biayanya sekitar 8% lebih mahal. Alur kerja pemanggilan tunggal berurutan tidak mendapat manfaat.
Di seluruh lalu lintas API produksi, permintaan yang array tools-nya berisi 10 hingga 49 definisi alat melihat penghematan token tipikal 20% hingga 40% dengan pemanggilan alat terprogram diaktifkan.

Penghematan aktual bervariasi tergantung bentuk beban kerja. Lihat Kapan menggunakan pemanggilan terprogram.

Penggunaan dan harga

Pemanggilan alat terprogram menggunakan harga yang sama dengan code execution. Lihat harga code execution untuk detailnya.

Praktik terbaik

Desain alat

Berikan deskripsi output yang terperinci: Karena Claude melakukan deserialisasi hasil alat dalam kode, dokumentasikan formatnya (struktur JSON dan tipe field)
Kembalikan data terstruktur: JSON atau format lain yang dapat dibaca mesin bekerja paling baik untuk pemrosesan terprogram
Jaga respons tetap ringkas: Kembalikan hanya data yang diperlukan untuk meminimalkan overhead pemrosesan

Kapan menggunakan pemanggilan terprogram

Sangat cocok:

Operasi fan-out atau paralel di banyak item (misalnya, memeriksa 50 endpoint atau mencari 20 catatan)
Hasil alat besar yang dapat difilter, diagregasi, atau diringkas sebelum mencapai konteks Claude
Pencarian dan pengambilan agentik, di mana kueri iteratif dan pemfilteran hasil mendominasi alur kerja

Kurang cocok:

Alur kerja yang benar-benar berurutan di mana setiap pemanggilan bergantung pada penalaran Claude atas hasil sebelumnya, karena skrip tidak dapat melewati perjalanan bolak-balik model dalam kasus tersebut
Sejumlah kecil pemanggilan alat dengan respons kecil, terutama pada giliran pertama percakapan, di mana overhead container dan skrip dapat melebihi penghematan
Alat yang memerlukan umpan balik pengguna segera di antara pemanggilan

Jika Anda tidak yakin, ukur token input yang ditagih dengan dan tanpa allowed_callers pada sampel representatif dari lalu lintas Anda sebelum mengaktifkannya secara luas.

Optimasi kinerja

Gunakan kembali container saat membuat beberapa permintaan terkait untuk mempertahankan state
Kelompokkan operasi serupa dalam satu code execution jika memungkinkan

Pemecahan masalah

Masalah umum

invalid_request_error saat mengatur tool_choice

tool_choice tidak dapat menyebutkan alat yang allowed_callers-nya menghilangkan "direct". Tambahkan "direct" ke allowed_callers alat tersebut, atau hapus alat dari tool_choice dan biarkan Claude memanggilnya dari kode.

Kedaluwarsa container

Respons setiap pemanggilan alat terprogram jauh sebelum timestamp expires_at dari respons yang dijeda. Kode Claude berhenti menunggu hasil setelah sekitar 4 menit, dan container yang menganggur saat ini diklaim kembali setelah sekitar 5 menit.
Pertimbangkan untuk mengimplementasikan eksekusi alat yang lebih cepat

Hasil alat tidak di-parse dengan benar

Pastikan alat Anda mengembalikan data string yang dapat dideserialisasi oleh Claude
Berikan dokumentasi format output yang jelas dalam deskripsi alat Anda

Tips debugging

Catat semua pemanggilan alat dan hasilnya untuk melacak alur
Periksa field caller untuk mengonfirmasi pemanggilan terprogram
Pantau ID container untuk memastikan penggunaan kembali yang tepat
Uji alat secara independen sebelum mengaktifkan pemanggilan terprogram

Mengapa pemanggilan alat terprogram berhasil

Claude dilatih pada sejumlah besar kode, sehingga menyajikan alat sebagai fungsi Python yang dapat dipanggil memungkinkannya menggunakan kekuatan tersebut:

Komposisi alat: Pemanggilan berantai, loop, dan kondisional adalah alur kontrol Python biasa alih-alih serangkaian perjalanan bolak-balik model
Pemrosesan hasil: Kode Claude memfilter dan mengagregasi output alat yang besar, atau menulisnya ke file, dan hanya output akhir yang masuk ke jendela konteks
Latensi: Model tidak di-sampling ulang di antara pemanggilan alat dalam satu code execution

Implementasi alternatif

Pemanggilan alat terprogram adalah pola yang dapat digeneralisasi yang juga dapat diimplementasikan pada infrastruktur Anda sendiri. Berikut perbandingan pendekatannya:

Eksekusi langsung sisi klien

Keuntungan:

Perubahan arsitektur minimal pada aplikasi Anda
Kontrol penuh atas lingkungan dan instruksi

Kerugian:

Mengeksekusi kode yang tidak tepercaya di luar sandbox
Pemanggilan alat dapat menjadi vektor untuk injeksi kode

Gunakan ketika: Aplikasi Anda dapat mengeksekusi kode arbitrer dengan aman, Anda menginginkan implementasi terkecil, dan penawaran terkelola Anthropic tidak sesuai dengan kebutuhan Anda.

Eksekusi sandbox yang dikelola sendiri

Keuntungan:

Pemanggilan alat terprogram yang aman pada infrastruktur Anda sendiri
Kontrol penuh atas lingkungan eksekusi

Kerugian:

Kompleks untuk dibangun dan dipelihara
Memerlukan pengelolaan infrastruktur dan komunikasi antar-proses

Gunakan ketika: Keamanan sangat penting dan solusi terkelola Anthropic tidak sesuai dengan kebutuhan Anda.

Eksekusi yang dikelola Anthropic

Keuntungan:

Aman dan terlindungi secara default
Diaktifkan dengan definisi alat, tanpa infrastruktur yang perlu dijalankan
Lingkungan dan instruksi dioptimalkan untuk Claude

Retensi data

Pemanggilan alat terprogram dibangun di atas infrastruktur code execution dan menggunakan container sandbox yang sama. Data container, termasuk artefak eksekusi dan output, disimpan hingga 30 hari.

Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.

Langkah selanjutnya

Streaming alat berbutir halus

Streaming input alat tanpa buffering JSON sisi server untuk aplikasi yang sensitif terhadap latensi.

Alat code execution

Jalankan kode Python dan bash dalam container sandbox untuk menganalisis data, menghasilkan file, dan mengiterasi solusi.

Penggunaan alat dengan Claude

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

Definisikan alat

Tentukan skema alat, tulis deskripsi yang efektif, dan kontrol kapan Claude memanggil alat Anda.

Was this page helpful?

Kompatibilitas model

Mulai cepat

Cara kerja pemanggilan alat terprogram

Konsep inti

Field allowed_callers

Field caller dalam respons

Siklus hidup container

Contoh alur kerja

Langkah 1: Permintaan awal

Langkah 2: Respons API dengan pemanggilan alat

Langkah 3: Berikan hasil alat

Langkah 4: Pemanggilan alat berikutnya atau penyelesaian

Langkah 5: Respons akhir

Pola lanjutan

Pemrosesan batch dengan loop

Penghentian dini

Pemilihan alat kondisional

Pemfilteran data

Format respons

Pemanggilan alat terprogram

Penanganan hasil alat

Penyelesaian code execution

Penanganan error

Error umum

Kedaluwarsa container selama pemanggilan alat

Error eksekusi alat

Batasan dan keterbatasan

Ketidakcocokan fitur

Keterbatasan skema input

Pembatasan alat

Pembatasan pemformatan pesan

Batas laju

Validasi hasil alat sebelum digunakan

Efisiensi token

Penggunaan dan harga

Praktik terbaik

Desain alat

Kapan menggunakan pemanggilan terprogram

Optimasi kinerja

Pemecahan masalah

Masalah umum

Tips debugging

Mengapa pemanggilan alat terprogram berhasil

Implementasi alternatif

Eksekusi langsung sisi klien

Eksekusi sandbox yang dikelola sendiri

Eksekusi yang dikelola Anthropic

Retensi data

Langkah selanjutnya

Kompatibilitas model

Mulai cepat

Cara kerja pemanggilan alat terprogram

Konsep inti

Field allowed_callers

Field caller dalam respons

Siklus hidup container

Contoh alur kerja

Langkah 1: Permintaan awal

Langkah 2: Respons API dengan pemanggilan alat

Langkah 3: Berikan hasil alat

Langkah 4: Pemanggilan alat berikutnya atau penyelesaian

Langkah 5: Respons akhir

Pola lanjutan

Pemrosesan batch dengan loop

Penghentian dini

Pemilihan alat kondisional

Pemfilteran data

Format respons

Pemanggilan alat terprogram

Penanganan hasil alat

Penyelesaian code execution

Penanganan error

Error umum

Kedaluwarsa container selama pemanggilan alat

Error eksekusi alat

Batasan dan keterbatasan

Ketidakcocokan fitur

Keterbatasan skema input

Pembatasan alat

Pembatasan pemformatan pesan

Kompatibilitas model

Mulai cepat

Cara kerja pemanggilan alat terprogram

Konsep inti

Field `allowed_callers`

Field `caller` dalam respons

Siklus hidup container

Contoh alur kerja

Langkah 1: Permintaan awal

Langkah 2: Respons API dengan pemanggilan alat

Langkah 3: Berikan hasil alat

Langkah 4: Pemanggilan alat berikutnya atau penyelesaian

Langkah 5: Respons akhir

Pola lanjutan

Pemrosesan batch dengan loop

Penghentian dini

Pemilihan alat kondisional

Pemfilteran data

Format respons

Pemanggilan alat terprogram

Penanganan hasil alat

Penyelesaian code execution

Penanganan error

Error umum

Kedaluwarsa container selama pemanggilan alat

Error eksekusi alat

Batasan dan keterbatasan

Ketidakcocokan fitur

Keterbatasan skema input

Pembatasan alat

Pembatasan pemformatan pesan

Batas laju

Validasi hasil alat sebelum digunakan

Efisiensi token

Penggunaan dan harga

Praktik terbaik

Desain alat

Kapan menggunakan pemanggilan terprogram

Optimasi kinerja

Pemecahan masalah

Masalah umum

Tips debugging

Mengapa pemanggilan alat terprogram berhasil

Implementasi alternatif

Eksekusi langsung sisi klien

Eksekusi sandbox yang dikelola sendiri

Eksekusi yang dikelola Anthropic

Retensi data

Langkah selanjutnya

Kompatibilitas model

Mulai cepat

Cara kerja pemanggilan alat terprogram

Konsep inti

Field `allowed_callers`

Field `caller` dalam respons

Siklus hidup container

Contoh alur kerja

Langkah 1: Permintaan awal

Langkah 2: Respons API dengan pemanggilan alat

Langkah 3: Berikan hasil alat

Langkah 4: Pemanggilan alat berikutnya atau penyelesaian

Langkah 5: Respons akhir

Pola lanjutan

Pemrosesan batch dengan loop

Penghentian dini

Pemilihan alat kondisional

Pemfilteran data

Format respons

Pemanggilan alat terprogram

Penanganan hasil alat

Penyelesaian code execution

Penanganan error

Error umum

Kedaluwarsa container selama pemanggilan alat

Error eksekusi alat

Batasan dan keterbatasan

Ketidakcocokan fitur

Keterbatasan skema input

Pembatasan alat

Pembatasan pemformatan pesan