Alat server

Halaman ini mencakup mekanika bersama alat yang dieksekusi server: blok server_tool_use, kelanjutan pause_turn, pertimbangan ZDR, dan penyaringan domain. Untuk alat individual, lihat referensi alat.

Blok server_tool_use

Blok server_tool_use muncul dalam respons Claude ketika alat yang dieksekusi server berjalan. Bidang id menggunakan awalan srvtoolu_ untuk membedakannya dari panggilan alat klien:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01A2B3C4D5E6F7G8H9",
  "name": "web_search",
  "input": { "query": "latest quantum computing breakthroughs" }
}

API mengeksekusi alat secara internal. Anda melihat panggilan dan hasilnya dalam respons, tetapi Anda tidak menangani eksekusi. Tidak seperti blok tool_use klien, Anda tidak perlu merespons dengan tool_result. Blok hasil muncul segera setelah blok server_tool_use dalam giliran asisten yang sama.

Loop sisi server dan pause_turn

Saat menggunakan alat server seperti pencarian web, API dapat mengembalikan alasan penghentian pause_turn, menunjukkan bahwa API telah menjeda giliran yang berjalan lama.

Berikut cara menangani alasan penghentian pause_turn:

# Initial request with web search
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    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}],
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # Send the continuation request
    continuation = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)

Saat menangani pause_turn:

• Lanjutkan percakapan: Teruskan respons yang dijeda kembali apa adanya dalam permintaan berikutnya untuk membiarkan Claude melanjutkan gilirannya
• Modifikasi jika diperlukan: Anda dapat secara opsional memodifikasi konten sebelum melanjutkan jika Anda ingin mengganggu atau mengalihkan percakapan
• Pertahankan status alat: Sertakan alat yang sama dalam permintaan kelanjutan untuk mempertahankan fungsionalitas

ZDR dan allowed_callers

Versi dasar pencarian web (web_search_20250305) dan pengambilan web (web_fetch_20250910) memenuhi syarat untuk Zero Data Retention (ZDR).

Versi _20260209 dengan penyaringan dinamis bukan memenuhi syarat ZDR secara default karena penyaringan dinamis bergantung pada eksekusi kode secara internal.

Untuk menggunakan alat server _20260209 dengan ZDR, nonaktifkan penyaringan dinamis dengan menetapkan "allowed_callers": ["direct"] pada alat:

{
  "type": "web_search_20260209",
  "name": "web_search",
  "allowed_callers": ["direct"]
}

Ini membatasi alat hanya untuk pemanggilan langsung, melewati langkah eksekusi kode internal.

Penyaringan domain

Alat server yang mengakses web menerima parameter allowed_domains dan blocked_domains untuk mengontrol domain mana yang dapat dijangkau Claude.

Saat menggunakan filter domain:

• Domain tidak boleh menyertakan skema HTTP/HTTPS (gunakan example.com bukan https://example.com)
• Subdomain secara otomatis disertakan (example.com mencakup docs.example.com)
• Subdomain spesifik membatasi hasil hanya ke subdomain itu (docs.example.com mengembalikan hanya hasil dari subdomain itu, bukan dari example.com atau api.example.com)
• Subpath didukung dan cocok dengan apa pun setelah path (example.com/blog cocok dengan example.com/blog/post-1)
• Anda dapat menggunakan allowed_domains atau blocked_domains, tetapi tidak keduanya dalam permintaan yang sama

Dukungan wildcard:

• Hanya satu wildcard (*) yang diizinkan per entri domain, dan harus muncul setelah bagian domain (di path)
• Valid: example.com/*, example.com/*/articles
• Tidak valid: *.example.com, ex*.com, example.com/*/news/*

Format domain yang tidak valid mengembalikan kesalahan alat invalid_tool_input.

Penyaringan dinamis dengan eksekusi kode

Versi _20260209 dari pencarian web dan pengambilan web menggunakan eksekusi kode secara internal untuk menerapkan filter dinamis terhadap hasil pencarian.

Streaming acara alat server

Acara alat server streaming sebagai bagian dari aliran SSE normal. Blok server_tool_use dan hasilnya tiba sebagai acara content_block_start dan content_block_delta, dengan cara yang sama teks dan panggilan alat klien stream.

Lihat Streaming untuk referensi acara lengkap. Halaman alat individual mendokumentasikan nama acara khusus alat di mana mereka berbeda.

Permintaan batch

Semua alat server mendukung pemrosesan batch. Lihat Pemrosesan batch.

Langkah berikutnya