Alat server
Bekerja dengan alat yang dijalankan oleh Anthropic: blok server_tool_use, kelanjutan pause_turn, giliran campuran alat server dan klien, serta pemfilteran domain.
Alat yang dieksekusi server berbagi mekanisme berikut: blok server_tool_use, kelanjutan pause_turn, giliran yang mencampur alat server dan klien, kelayakan “Zero Data Retention” (Retensi Data Nol), atau ZDR, serta pemfilteran domain. Untuk masing-masing alat, lihat Referensi alat.
Blok server_tool_use
Blok server_tool_use muncul dalam respons Claude ketika alat yang dieksekusi server berjalan. Field id-nya menggunakan prefiks srvtoolu_ untuk membedakannya dari panggilan alat klien:
{
"type": "server_tool_use",
"id": "srvtoolu_01A2B3C4D5E6F7G8H9",
"name": "web_search",
"input": { "query": "latest quantum computing breakthroughs" }
}API menjalankan alat tersebut secara internal. Anda melihat panggilan dan hasilnya dalam respons, tetapi Anda tidak menangani eksekusinya. Tidak seperti blok tool_use klien, Anda tidak perlu merespons dengan tool_result. Blok hasil alat (misalnya, web_search_tool_result untuk pencarian web) mengikuti blok server_tool_use dalam giliran asisten yang sama, dipasangkan berdasarkan tool_use_id. Jika Claude memanggil salah satu alat klien Anda pada saat yang sama, blok server_tool_use muncul tanpa hasilnya, dan respons berakhir dengan stop_reason: "tool_use". API menjalankan alat tersebut ketika Anda mengembalikan blok tool_result klien dalam permintaan Anda berikutnya.
Loop sisi server dan pause_turn
Saat Anda menggunakan alat server seperti pencarian web, API mengeksekusi panggilan alat dalam “agentic loop” (loop agentik) sisi server. Pada giliran yang berjalan lama, API mungkin menjeda loop tersebut dan mengembalikan alasan berhenti pause_turn.
Berikut cara menangani alasan berhenti pause_turn:
client = anthropic.Anthropic()
# Permintaan awal dengan pencarian web
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
}
],
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)
# Periksa apakah respons memiliki alasan berhenti pause_turn
if response.stop_reason == "pause_turn":
# Lanjutkan percakapan dengan konten yang dijeda
messages = [
{
"role": "user",
"content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
},
{"role": "assistant", "content": response.content},
]
# Kirim permintaan lanjutan
continuation = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=messages,
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)
print(continuation)
else:
print(response)Saat menangani pause_turn:
- Lanjutkan percakapan: Kirimkan kembali respons yang dijeda apa adanya dalam permintaan berikutnya agar Claude dapat melanjutkan gilirannya.
- Pertahankan status alat: Sertakan alat yang sama dalam permintaan kelanjutan. Giliran yang dijeda dapat berakhir dengan blok
server_tool_useyang alatnya belum berjalan, dan API mengembalikan error validasi jika alat tersebut tidak ada dalam kelanjutan. - Pertahankan container: Jika respons menyertakan
container, seperti halnya dengan alat eksekusi kode, kirimkan kembali ID-nya dalam permintaan kelanjutan. Tanpanya, permintaan akan berjalan di container baru, dan file dari bagian sebelumnya dalam giliran tersebut akan hilang. - Ulangi sesuai kebutuhan: Giliran yang dilanjutkan dapat dijeda lagi. Periksa
stop_reasonpada setiap respons dan lanjutkan hingga Anda mendapatkan alasan berhenti yang berbeda, dengan membatasi jumlah kelanjutan seperti yang Anda lakukan pada loop percobaan ulang apa pun. Simpan setiap respons yang dijeda dimessages, secara berurutan. Kelanjutan hanya berisi konten baru, sehingga permintaan yang tidak menyertakan respons yang dijeda sebelumnya akan kehilangan pekerjaan tersebut dan dapat mengembalikan kesalahan 400.
Untuk nilai stop_reason lainnya dan pola penanganan umum, lihat Alasan berhenti dan fallback.
Mencampur alat server dan alat klien dalam satu giliran
Claude dapat memanggil alat server dan alat klien dalam kelompok panggilan alat paralel yang sama, misalnya, web_fetch bersama dengan alat yang ditentukan pengguna. Alat klien adalah alat apa pun yang dijalankan oleh kode Anda dan menghasilkan blok tool_use, baik yang ditentukan pengguna maupun alat klien dengan skema Anthropic seperti alat Bash. Ketika hal itu terjadi, API tidak menjalankan alat server. API langsung mengembalikan respons sehingga Anda dapat menjalankan alat klien terlebih dahulu:
stop_reasonadalah"tool_use", bukan"pause_turn".contentberisi blokserver_tool_usedan bloktool_useklien, tetapi tidak ada blok hasil untuk alat server: panggilan tersebut belum selesai.- Tidak ada penanda lain. Deteksi status ini dengan mencari blok
server_tool_useyangid-nya tidak memiliki blok hasil yang cocok dalam respons. Blokmcp_tool_usedari konektor MCP berperilaku dengan cara yang sama. Panggilan alat server yang sudah memiliki blok hasilnya dalam respons yang sama sudah selesai dan tidak memerlukan apa pun dari Anda.
{
"stop_reason": "tool_use",
"content": [
{
"type": "text",
"text": "I'll fetch the article and check your system at the same time."
},
{
"type": "server_tool_use",
"id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
"name": "web_fetch",
"input": { "url": "https://example.com/article" }
},
{
"type": "tool_use",
"id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
"name": "run_command",
"input": { "command": "uname -a" }
}
]
}Untuk melanjutkan giliran, jalankan alat klien dan kirim pesan pengguna yang isinya hanya blok tool_result, satu untuk setiap blok tool_use dalam respons tersebut. Pertahankan array tools yang sama: permintaan lanjutan yang tidak lagi mendefinisikan alat server yang sedang menunggu akan gagal dengan 400 yang pesannya berakhir dengan but no `web_fetch` tool was provided.
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
"content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
}
]
}API melampirkan hasil Anda ke giliran asisten yang masih terbuka, menjalankan alat server yang ditunda (untuk eksekusi kode yang dijeda, melanjutkannya), lalu membiarkan Claude melanjutkan. Untuk alat server yang dipanggil Claude secara langsung, respons berikutnya dimulai dengan blok hasil yang menjawab id server_tool_use dari respons sebelumnya, diikuti oleh konten yang baru dihasilkan dan stop_reason yang baru:
{
"stop_reason": "end_turn",
"content": [
{
"type": "web_fetch_tool_result",
"tool_use_id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
"content": {
"type": "web_fetch_result",
"url": "https://example.com/article",
"content": {
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "Full text content of the article..."
}
}
}
},
{
"type": "text",
"text": "The article argues that... and your machine is running Linux..."
}
]
}Blok server_tool_use dan blok hasilnya dipasangkan berdasarkan tool_use_id, bukan berdasarkan posisi: dalam alur ini keduanya tiba dalam dua respons yang berbeda, dan blok server_tool_use tidak diulang dalam respons kedua. Pada permintaan selanjutnya, simpan seluruh pertukaran dalam array messages Anda secara berurutan: respons pertama sebagai pesan assistant, pesan pengguna tool_result, lalu respons berikutnya sebagai pesan assistant lainnya, dengan cara yang sama seperti Anda mengakumulasi pertukaran penggunaan alat lainnya.
Perbedaannya dengan pause_turn: Respons pause_turn juga dapat berakhir dengan blok server_tool_use yang belum berjalan, tetapi tidak pernah meninggalkan blok tool_use klien yang menunggu Anda, sehingga Anda melanjutkannya dengan mengirim ulang konten asisten apa adanya. Respons yang meninggalkan blok tool_use klien yang menunggu Anda tidak pernah memiliki stop_reason berupa pause_turn: ketika Claude berhenti untuk memanggil alat Anda, stop_reason adalah tool_use, dan Anda melanjutkannya dengan mengirim kembali respons tersebut beserta pesan pengguna baru yang berisi blok tool_result klien. Dalam kedua kasus, API menjalankan alat server yang tertunda pada awal permintaan berikutnya.
Contoh berikut mengaktifkan web fetch bersama dengan alat run_command yang didefinisikan pengguna dan menangani respons campuran:
client = anthropic.Anthropic()
tools = [
{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5},
{
"name": "run_command",
"description": "Run a shell command on this computer and return its output.",
"input_schema": {
"type": "object",
"properties": {
"command": {"type": "string", "description": "The command to run"}
},
"required": ["command"],
},
},
]
messages = [
{
"role": "user",
"content": "Summarize https://example.com/article and run uname -a to tell me what system this is on.",
}
]
response = client.messages.create(
model="claude-opus-5-5", max_tokens=4096, tools=tools, messages=messages
)
tool_results = [
{
"type": "tool_result",
"tool_use_id": block.id,
# Jalankan alat Anda di sini. Contoh ini mengembalikan string tetap.
"content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux",
}
for block in response.content
if block.type == "tool_use"
]
if response.stop_reason == "tool_use" and tool_results:
# Blok server_tool_use tanpa blok hasil dalam respons ini belum selesai; hasilnya tiba di respons berikutnya.
# Kirim kembali hanya blok tool_result klien, dengan alat yang sama.
continuation = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
tools=tools,
messages=[
*messages,
{"role": "assistant", "content": response.content},
{"role": "user", "content": tool_results},
],
)
# Jika web_fetch ditunda, ia dijalankan pada permintaan ini dan
# web_fetch_tool_result-nya adalah blok pertama dari continuation.content.
print(continuation)
else:
print(response)Kode ini juga benar ketika Claude tidak mencampur kedua jenis panggilan. Giliran yang hanya berisi blok tool_use klien mengambil jalur kelanjutan yang sama. Giliran yang hanya berisi panggilan alat server tidak memerlukan blok tool_result klien dari Anda, karena blok hasilnya biasanya sudah ada. Jika giliran tersebut kembali dalam keadaan ditangguhkan, misalnya sebagai respons pause_turn, kirim ulang apa adanya.
ZDR dan allowed_callers
Versi dasar pencarian web (web_search_20250305) dan web fetch (web_fetch_20250910) memenuhi syarat untuk Zero Data Retention (ZDR).
Versi _20260209 dan yang lebih baru dengan pemfilteran dinamis tidak memenuhi syarat ZDR secara default karena pemfilteran dinamis bergantung pada eksekusi kode secara internal.
Untuk menggunakan alat server _20260209 atau yang lebih baru dengan ZDR, nonaktifkan pemfilteran dinamis dengan mengatur "allowed_callers": ["direct"] pada alat:
{
"type": "web_search_20260209",
"name": "web_search",
"allowed_callers": ["direct"]
}Ini membatasi alat hanya untuk panggilan langsung, melewati langkah eksekusi kode internal.
allowed_callers mengontrol bagaimana alat dapat dipanggil: langsung oleh Claude ("direct"), dari dalam container eksekusi kode (misalnya, "code_execution_20260120"), atau keduanya. Versi _20260209 dari alat web secara default hanya menggunakan pemanggil eksekusi kode; versi sebelumnya secara default menggunakan ["direct"]. Pada model yang tidak mendukung pemanggilan alat terprogram, versi ini memerlukan allowed_callers: ["direct"]; tanpanya API mengembalikan kesalahan validasi yang meminta Anda untuk mengaturnya.
Pemfilteran domain
Alat server yang mengakses web menerima parameter allowed_domains dan blocked_domains untuk mengontrol domain mana yang dapat dijangkau Claude. Keduanya adalah field pada objek alat:
{
"type": "web_search_20250305",
"name": "web_search",
"allowed_domains": ["example.com", "docs.python.org"]
}Saat menggunakan filter domain:
- Domain tidak boleh menyertakan skema HTTP/HTTPS (gunakan
example.comalih-alihhttps://example.com). - Subdomain secara otomatis disertakan (
example.commencakupdocs.example.com). - Subdomain spesifik membatasi hasil hanya pada subdomain tersebut (
docs.example.comhanya mengembalikan hasil dari subdomain tersebut, bukan dariexample.comatauapi.example.com). - Subpath didukung untuk pencarian web dan cocok dengan apa pun setelah path (
example.com/blogcocok denganexample.com/blog/post-1). - Web fetch hanya mencocokkan domain: entri yang menyertakan path tidak pernah cocok dengan URL web fetch.
- Anda dapat menggunakan
allowed_domainsataublocked_domains, tetapi tidak keduanya dalam permintaan yang sama.
Dukungan wildcard:
- Wildcard (
*) tidak diizinkan dalam domain itu sendiri, hanya dalam path setelahnya. - Valid:
example.com/*,example.com/*/articles - Tidak valid:
*.example.com,ex*.com
Format domain yang tidak valid ditolak pada saat permintaan dengan 400 invalid_request_error.
Untuk daftar domain dan pengaturan organisasi Anda dalam sesi Claude Managed Agents, lihat Membatasi domain pencarian web dan web fetch.
Pemfilteran dinamis dengan eksekusi kode
Versi _20260209 dan yang lebih baru dari pencarian web dan web fetch menggunakan eksekusi kode secara internal untuk menerapkan filter dinamis terhadap hasil pencarian.
Streaming event alat server
Event alat server di-streaming sebagai bagian dari alur “server-sent events” (event yang dikirim server), atau SSE, yang normal. Blok server_tool_use yang dipanggil Claude secara langsung di-streaming seperti blok tool_use klien: event content_block_start diikuti oleh event input_json_delta. Blok hasil tiba secara lengkap dalam satu event content_block_start, tanpa delta.
Lihat Streaming pesan untuk referensi event lengkap. Halaman alat individual mendokumentasikan nama event khusus alat jika berbeda.
Permintaan batch
Semua alat server mendukung pemrosesan batch. Dalam batch, loop agentik berjalan sama seperti pada permintaan sinkron, dengan batas iterasi per giliran yang lebih tinggi. Jika loop mencapai batas tersebut, respons berakhir dengan stop_reason: "pause_turn"; Anda dapat melanjutkannya dengan mengirimkan permintaan lanjutan dengan konten yang dikembalikan. Lihat Alat server dan loop agentik untuk detailnya.
Beban kerja batch yang umum meliputi memperkaya dataset dengan informasi dari web, memeriksa sekumpulan besar dokumen terhadap sumber terkini, dan menjalankan kode analisis pada banyak file.
Langkah selanjutnya
Perbaiki error penggunaan alat yang paling umum dengan tabel diagnostik gejala-ke-perbaikan.
Telusuri web dan kutip hasilnya.
Ambil dan baca konten dari URL tertentu untuk memperkaya konteks Claude dengan konten web langsung.
Jalankan kode Python dan Bash dalam container sandbox untuk menganalisis data, menghasilkan file, dan melakukan iterasi pada solusi.
Temukan dan muat alat sesuai permintaan.
Apakah halaman ini membantu?