Alat server

Alat yang dieksekusi di server berbagi mekanisme berikut: blok server_tool_use, kelanjutan pause_turn, giliran yang mencampur alat server dan klien, kelayakan Zero Data Retention (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 di server berjalan. Bidang id-nya 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 tersebut secara internal. Anda melihat panggilan dan hasilnya dalam respons, tetapi Anda tidak menangani eksekusinya. Berbeda dengan 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 melalui 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 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",
    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-5",
        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: 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_use yang alatnya belum berjalan, dan API mengembalikan kesalahan 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 alasan berhenti yang berbeda, dengan membatasi jumlah kelanjutan seperti yang Anda lakukan pada loop percobaan ulang lainnya.

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 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 berskema Anthropic seperti alat Bash. Ketika itu terjadi, API tidak menjalankan alat server. API langsung 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 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 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 sedang menunggu akan gagal dengan 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), 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 melalui 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 berikutnya, 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 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 pengambilan web 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 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, dan giliran yang hanya berisi 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 pencarian web (web_search_20250305) dan pengambilan web (web_fetch_20250910) memenuhi syarat untuk Zero Data Retention (ZDR).

Versi _20260209 dan yang lebih baru dengan pemfilteran dinamis secara default tidak memenuhi syarat ZDR karena pemfilteran dinamis bergantung pada eksekusi kode secara internal.

Untuk menggunakan alat server _20260209 atau yang lebih baru dengan ZDR, nonaktifkan pemfilteran dinamis dengan menyetel "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: langsung oleh Claude ("direct"), dari dalam kontainer 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-versi ini memerlukan allowed_callers: ["direct"]; tanpanya API mengembalikan kesalahan validasi yang meminta Anda menyetelnya.



Pemfilteran domain

Alat server yang mengakses web menerima parameter allowed_domains dan blocked_domains untuk mengontrol domain mana yang dapat dijangkau Claude. Keduanya adalah bidang 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 disertakan secara otomatis (example.com mencakup docs.example.com).
• Subdomain spesifik membatasi hasil hanya pada subdomain tersebut (docs.example.com hanya mengembalikan hasil dari subdomain itu, 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).
• Pengambilan web hanya mencocokkan pada domain: entri yang menyertakan path tidak pernah cocok dengan URL pengambilan web.
• 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 400 invalid_request_error.



Pemfilteran dinamis dengan eksekusi kode

Versi _20260209 dan yang lebih baru dari pencarian web dan pengambilan web 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 lengkap dalam satu event content_block_start, tanpa delta.

Lihat Streaming 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 tindak lanjut 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