Menangani alasan berhenti
Ketika Anda membuat permintaan ke Messages API, respons Claude menyertakan field stop_reason yang menunjukkan mengapa model berhenti menghasilkan responsnya. Memahami nilai-nilai ini sangat penting untuk membangun aplikasi yang robust yang menangani berbagai jenis respons dengan tepat.
Untuk detail tentang stop_reason dalam respons API, lihat referensi Messages API.
Apa itu stop_reason?
Field stop_reason adalah bagian dari setiap respons Messages API yang berhasil. Tidak seperti error, yang menunjukkan kegagalan dalam memproses permintaan Anda, stop_reason memberi tahu Anda mengapa Claude berhasil menyelesaikan generasi responsnya.
{
"id": "msg_01234",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Here's the answer to your question..."
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 100,
"output_tokens": 50
}
}Nilai stop reason
end_turn
Alasan berhenti yang paling umum. Menunjukkan Claude menyelesaikan responsnya secara alami.
if response.stop_reason == "end_turn":
# Proses respons yang lengkap
print(response.content[0].text)Respons kosong dengan end_turn
Terkadang Claude mengembalikan respons kosong (tepat 2-3 token tanpa konten) dengan stop_reason: "end_turn". Ini biasanya terjadi ketika Claude menginterpretasikan bahwa giliran asisten sudah selesai, terutama setelah hasil tool.
Penyebab umum:
- Menambahkan blok teks segera setelah hasil tool (Claude belajar mengharapkan pengguna selalu menyisipkan teks setelah hasil tool, jadi ia mengakhiri gilirannya untuk mengikuti pola)
- Mengirim respons Claude yang sudah selesai kembali tanpa menambahkan apa pun (Claude sudah memutuskan sudah selesai, jadi akan tetap selesai)
Cara mencegah respons kosong:
# SALAH: Menambahkan teks segera setelah tool_result
messages = [
{"role": "user", "content": "Calculate the sum of 1234 and 5678"},
{"role": "assistant", "content": [
{
"type": "tool_use",
"id": "toolu_123",
"name": "calculator",
"input": {"operation": "add", "a": 1234, "b": 5678}
}
]},
{"role": "user", "content": [
{
"type": "tool_result",
"tool_use_id": "toolu_123",
"content": "6912"
},
{
"type": "text",
"text": "Here's the result" # Jangan tambahkan teks setelah tool_result
}
]}
]
# BENAR: Kirim hasil tool langsung tanpa teks tambahan
messages = [
{"role": "user", "content": "Calculate the sum of 1234 and 5678"},
{"role": "assistant", "content": [
{
"type": "tool_use",
"id": "toolu_123",
"name": "calculator",
"input": {"operation": "add", "a": 1234, "b": 5678}
}
]},
{"role": "user", "content": [
{
"type": "tool_result",
"tool_use_id": "toolu_123",
"content": "6912"
}
]} # Hanya tool_result, tanpa teks tambahan
]
# Jika Anda masih mendapat respons kosong setelah memperbaiki hal di atas:
def handle_empty_response(client, messages):
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=messages
)
# Periksa apakah respons kosong
if (response.stop_reason == "end_turn" and
not response.content:
# SALAH: Jangan hanya coba lagi dengan respons kosong
# Ini tidak akan berhasil karena Claude sudah memutuskan sudah selesai
# BENAR: Tambahkan prompt lanjutan dalam pesan user BARU
messages.append({"role": "user", "content": "Please continue"})
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=messages
)
return responsePraktik terbaik:
- Jangan pernah menambahkan blok teks segera setelah hasil tool - Ini mengajarkan Claude untuk mengharapkan input pengguna setelah setiap penggunaan tool
- Jangan coba lagi respons kosong tanpa modifikasi - Hanya mengirim respons kosong kembali tidak akan membantu
- Gunakan prompt lanjutan sebagai pilihan terakhir - Hanya jika perbaikan di atas tidak menyelesaikan masalah
max_tokens
Claude berhenti karena mencapai batas max_tokens yang ditentukan dalam permintaan Anda.
# Permintaan dengan token terbatas
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=10,
messages=[{"role": "user", "content": "Explain quantum physics"}]
)
if response.stop_reason == "max_tokens":
# Respons terpotong
print("Response was cut off at token limit")
# Pertimbangkan membuat permintaan lain untuk melanjutkanstop_sequence
Claude menemukan salah satu urutan berhenti kustom Anda.
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
stop_sequences=["END", "STOP"],
messages=[{"role": "user", "content": "Generate text until you say END"}]
)
if response.stop_reason == "stop_sequence":
print(f"Stopped at sequence: {response.stop_sequence}")tool_use
Claude memanggil tool dan mengharapkan Anda untuk menjalankannya.
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=[weather_tool],
messages=[{"role": "user", "content": "What's the weather?"}]
)
if response.stop_reason == "tool_use":
# Ekstrak dan jalankan tool
for content in response.content:
if content.type == "tool_use":
result = execute_tool(content.name, content.input)
# Kembalikan hasil ke Claude untuk respons akhirpause_turn
Digunakan dengan server tools seperti pencarian web ketika Claude perlu menjeda operasi yang berjalan lama.
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=[{"type": "web_search_20250305", "name": "web_search"}],
messages=[{"role": "user", "content": "Search for latest AI news"}]
)
if response.stop_reason == "pause_turn":
# Lanjutkan percakapan
messages = [
{"role": "user", "content": original_query},
{"role": "assistant", "content": response.content}
]
continuation = client.messages.create(
model="claude-sonnet-4-5",
messages=messages,
tools=[{"type": "web_search_20250305", "name": "web_search"}]
)refusal
Claude menolak menghasilkan respons karena masalah keamanan.
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[{"role": "user", "content": "[Unsafe request]"}]
)
if response.stop_reason == "refusal":
# Claude menolak merespons
print("Claude was unable to process this request")
# Pertimbangkan mengubah frasa atau memodifikasi permintaanJika Anda sering mengalami alasan berhenti refusal saat menggunakan Claude Sonnet 4.5 atau Opus 4.1, Anda dapat mencoba memperbarui panggilan API Anda untuk menggunakan Sonnet 4 (claude-sonnet-4-20250514), yang memiliki pembatasan penggunaan berbeda. Pelajari lebih lanjut tentang memahami filter keamanan API Sonnet 4.5.
Untuk mempelajari lebih lanjut tentang penolakan yang dipicu oleh filter keamanan API untuk Claude Sonnet 4.5, lihat Memahami Filter Keamanan API Sonnet 4.5.
model_context_window_exceeded
Claude berhenti karena mencapai batas jendela konteks model. Ini memungkinkan Anda meminta token maksimum yang mungkin tanpa mengetahui ukuran input yang tepat.
# Permintaan dengan token maksimum untuk mendapatkan sebanyak mungkin
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=64000, # Token output maksimum model
messages=[{"role": "user", "content": "Large input that uses most of context window..."}]
)
if response.stop_reason == "model_context_window_exceeded":
# Respons mencapai batas jendela konteks sebelum max_tokens
print("Response reached model's context window limit")
# Respons masih valid tetapi dibatasi oleh jendela konteksAlasan berhenti ini tersedia secara default di Sonnet 4.5 dan model yang lebih baru. Untuk model sebelumnya, gunakan header beta model-context-window-exceeded-2025-08-26 untuk mengaktifkan perilaku ini.
Praktik terbaik untuk menangani stop reasons
1. Selalu periksa stop_reason
Biasakan untuk memeriksa stop_reason dalam logika penanganan respons Anda:
def handle_response(response):
if response.stop_reason == "tool_use":
return handle_tool_use(response)
elif response.stop_reason == "max_tokens":
return handle_truncation(response)
elif response.stop_reason == "model_context_window_exceeded":
return handle_context_limit(response)
elif response.stop_reason == "pause_turn":
return handle_pause(response)
elif response.stop_reason == "refusal":
return handle_refusal(response)
else:
# Tangani end_turn dan kasus lainnya
return response.content[0].text2. Tangani respons terpotong dengan baik
Ketika respons terpotong karena batas token atau jendela konteks:
def handle_truncated_response(response):
if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
# Opsi 1: Peringatkan pengguna tentang batas spesifik
if response.stop_reason == "max_tokens":
message = "[Response truncated due to max_tokens limit]"
else:
message = "[Response truncated due to context window limit]"
return f"{response.content[0].text}\n\n{message}"
# Opsi 2: Lanjutkan generasi
messages = [
{"role": "user", "content": original_prompt},
{"role": "assistant", "content": response.content[0].text}
]
continuation = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=messages + [{"role": "user", "content": "Please continue"}]
)
return response.content[0].text + continuation.content[0].text3. Implementasikan logika retry untuk pause_turn
Untuk server tools yang mungkin berhenti sementara:
def handle_paused_conversation(initial_response, max_retries=3):
response = initial_response
messages = [{"role": "user", "content": original_query}]
for attempt in range(max_retries):
if response.stop_reason != "pause_turn":
break
messages.append({"role": "assistant", "content": response.content})
response = client.messages.create(
model="claude-sonnet-4-5",
messages=messages,
tools=original_tools
)
return responseStop reasons vs. errors
Penting untuk membedakan antara nilai stop_reason dan error sebenarnya:
Stop reasons (respons berhasil)
- Bagian dari body respons
- Menunjukkan mengapa generasi berhenti secara normal
- Respons berisi konten yang valid
Errors (permintaan gagal)
- Kode status HTTP 4xx atau 5xx
- Menunjukkan kegagalan pemrosesan permintaan
- Respons berisi detail error
try:
response = client.messages.create(...)
# Tangani respons berhasil dengan stop_reason
if response.stop_reason == "max_tokens":
print("Response was truncated")
except anthropic.APIError as e:
# Tangani error sebenarnya
if e.status_code == 429:
print("Rate limit exceeded")
elif e.status_code == 500:
print("Server error")Pertimbangan streaming
Ketika menggunakan streaming, stop_reason adalah:
nulldalam eventmessage_startawal- Disediakan dalam event
message_delta - Tidak disediakan dalam event lainnya
with client.messages.stream(...) as stream:
for event in stream:
if event.type == "message_delta":
stop_reason = event.delta.stop_reason
if stop_reason:
print(f"Stream ended with: {stop_reason}")Pola umum
Menangani alur kerja tool use
def complete_tool_workflow(client, user_query, tools):
messages = [{"role": "user", "content": user_query}]
while True:
response = client.messages.create(
model="claude-sonnet-4-5",
messages=messages,
tools=tools
)
if response.stop_reason == "tool_use":
# Jalankan tools dan lanjutkan
tool_results = execute_tools(response.content)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
else:
# Respons akhir
return responseMemastikan respons lengkap
def get_complete_response(client, prompt, max_attempts=3):
messages = [{"role": "user", "content": prompt}]
full_response = ""
for _ in range(max_attempts):
response = client.messages.create(
model="claude-sonnet-4-5",
messages=messages,
max_tokens=4096
)
full_response += response.content[0].text
if response.stop_reason != "max_tokens":
break
# Lanjutkan dari tempat berhenti
messages = [
{"role": "user", "content": prompt},
{"role": "assistant", "content": full_response},
{"role": "user", "content": "Please continue from where you left off."}
]
return full_responseMendapatkan token maksimum tanpa mengetahui ukuran input
Dengan alasan berhenti model_context_window_exceeded, Anda dapat meminta token maksimum yang mungkin tanpa menghitung ukuran input:
def get_max_possible_tokens(client, prompt):
"""
Dapatkan sebanyak mungkin token dalam jendela konteks model
tanpa perlu menghitung jumlah token input
"""
response = client.messages.create(
model="claude-sonnet-4-5",
messages=[{"role": "user", "content": prompt}],
max_tokens=64000 # Atur ke token output maksimum model
)
if response.stop_reason == "model_context_window_exceeded":
# Mendapat token maksimum yang mungkin berdasarkan ukuran input
print(f"Generated {response.usage.output_tokens} tokens (context limit reached)")
elif response.stop_reason == "max_tokens":
# Mendapat tepat token yang diminta
print(f"Generated {response.usage.output_tokens} tokens (max_tokens reached)")
else:
# Penyelesaian alami
print(f"Generated {response.usage.output_tokens} tokens (natural completion)")
return response.content[0].textDengan menangani nilai stop_reason dengan benar, Anda dapat membangun aplikasi yang lebih robust yang menangani skenario respons berbeda dengan baik dan memberikan pengalaman pengguna yang lebih baik.