Alat server

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 (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 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 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 berikutnya.

Loop sisi server dan pause_turn

Saat 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 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-5-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-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 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 yang Anda lakukan pada loop retry apa pun.

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 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 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 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 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: