Alat server

Alat yang dieksekusi server memiliki mekanisme yang sama: blok server_tool_use, kelanjutan pause_turn, giliran yang mencampur alat server dan klien, kelayakan "Zero Data Retention" (Retensi Data Nol), atau ZDR, dan pemfilteran domain. Untuk alat individual, lihat referensi alat.



Blok server_tool_use

Blok server_tool_use muncul dalam respons Claude ketika alat yang dieksekusi server dijalankan. 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 mengeksekusi alat 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 menggunakan alat server seperti pencarian web, API mengeksekusi panggilan alat dalam loop agentik sisi server. Pada giliran yang berjalan lama, API mungkin menjeda loop tersebut dan mengembalikan stop reason pause_turn.

Berikut cara menangani stop reason pause_turn:

client = anthropic.Anthropic()

# Permintaan awal dengan pencarian web
response = client.messages.create(
    model="claude-opus-4-8",
    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}],
)

# Periksa apakah respons memiliki stop_reason 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-4-8",
        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: Kirim 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_use yang alatnya belum dijalankan, dan API mengembalikan error validasi jika alat tersebut tidak ada dalam kelanjutan.
• Ulangi sesuai kebutuhan: Giliran yang dilanjutkan dapat dijeda lagi. Periksa stop_reason pada setiap respons dan lanjutkan hingga Anda mendapatkan stop reason yang berbeda, dengan membatasi jumlah kelanjutan seperti halnya loop retry lainnya.

Untuk nilai stop_reason lainnya dan pola penanganan umum, lihat Stop reason dan fallback.



Mencampur alat server dan alat klien dalam satu giliran

Claude dapat memanggil alat server dan alat klien dalam grup panggilan alat paralel yang sama, misalnya, web_fetch bersama dengan alat yang didefinisikan pengguna. Alat klien adalah alat apa pun yang dieksekusi oleh kode Anda dan yang menghasilkan blok tool_use, baik itu didefinisikan pengguna maupun alat klien dengan skema Anthropic seperti alat Bash. Ketika itu terjadi, API tidak menjalankan alat server. API segera mengembalikan respons agar Anda dapat menjalankan alat klien terlebih dahulu:

• stop_reason adalah "tool_use", bukan "pause_turn".
• content berisi blok server_tool_use dan blok tool_use klien, tetapi tidak ada blok hasil untuk alat server: panggilan tersebut belum selesai.
• Tidak ada penanda lain. Deteksi status ini dengan mencari blok server_tool_use yang id-nya tidak memiliki blok hasil yang cocok dalam respons. Blok mcp_tool_use dari konektor MCP berperilaku dengan cara yang sama. Panggilan alat server yang sudah memiliki blok hasilnya dalam respons yang sama telah 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 kontennya hanya berisi 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 menunggu akan gagal dengan error 400 yang pesannya diakhiri 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 ditangguhkan (untuk eksekusi kode yang dijeda, melanjutkannya), dan kemudian 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 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, dan kemudian respons berikutnya sebagai pesan assistant lainnya, dengan cara yang sama seperti Anda mengakumulasi pertukaran penggunaan alat lainnya.

`web_fetch` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_fetch_tool_result` block

`tool_use` ids were found without `tool_result` blocks immediately after: toolu_01PjgRJLbXrXEMZwDNYLnBqk. Each `tool_use` block must have a corresponding `tool_result` block in the next message.

Perbedaannya dengan pause_turn: Respons pause_turn juga dapat berakhir dengan blok server_tool_use yang belum dijalankan, tetapi tidak pernah meninggalkan blok tool_use klien yang menunggu Anda, jadi 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 blok tool_result klien alih-alih mengirim ulang respons. Dalam kedua kasus, API menjalankan alat server yang tertunda di 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-4-8", max_tokens=1024, 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-4-8",
        max_tokens=1024,
        tools=tools,
        messages=[
            *messages,
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": tool_results},
        ],
    )
    # Jika web_fetch ditangguhkan, ia berjalan 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 dengan hanya blok tool_use klien mengambil jalur kelanjutan yang sama, dan giliran dengan hanya panggilan alat server tidak memerlukan blok tool_result klien dari Anda: blok hasilnya biasanya sudah ada, dan yang kembali dalam keadaan ditangguhkan, seperti respons pause_turn, dikirim ulang apa adanya.



ZDR dan allowed_callers

Versi dasar dari 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 tersebut:

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

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

allowed_callers mengontrol bagaimana alat dapat dipanggil: secara 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"]; tanpa itu API mengembalikan error validasi yang menyatakan 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.com alih-alih https://example.com).
• Subdomain secara otomatis disertakan (example.com mencakup docs.example.com).
• Subdomain spesifik membatasi hasil hanya ke subdomain tersebut (docs.example.com hanya mengembalikan hasil dari subdomain tersebut, bukan dari example.com atau api.example.com).
• Subpath didukung untuk pencarian web dan mencocokkan apa pun setelah path (example.com/blog cocok dengan example.com/blog/post-1).
• Web fetch hanya mencocokkan berdasarkan domain: entri yang menyertakan path tidak pernah cocok dengan URL web fetch.
• Anda dapat menggunakan allowed_domains atau blocked_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 invalid_request_error 400.



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-stream 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-stream seperti blok tool_use klien: event content_block_start diikuti oleh event input_json_delta. Blok hasil tiba lengkap dalam satu event content_block_start, tanpa delta.

Lihat Streaming untuk referensi event lengkap. Halaman alat individual mendokumentasikan nama event spesifik alat jika berbeda.



Permintaan batch

Semua alat server mendukung pemrosesan batch. Dalam batch, loop agentik berjalan sama seperti untuk 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 mencakup memperkaya dataset dengan informasi dari web, memeriksa sekumpulan besar dokumen terhadap sumber terkini, dan menjalankan kode analisis pada banyak file.



Langkah selanjutnya