停止理由の処理
Claude APIの停止理由を適切に処理する方法について説明します。
Messages APIにリクエストを送信すると、Claudeのレスポンスには、モデルがレスポンスの生成を停止した理由を示すstop_reason
フィールドが含まれます。これらの値を理解することは、異なるレスポンスタイプを適切に処理する堅牢なアプリケーションを構築するために重要です。
APIレスポンスのstop_reason
の詳細については、Messages APIリファレンスを参照してください。
stop_reasonとは?
stop_reason
フィールドは、すべての成功したMessages APIレスポンスの一部です。リクエストの処理における失敗を示すエラーとは異なり、stop_reason
はClaudeがレスポンス生成を正常に完了した理由を教えてくれます。
停止理由の値
end_turn
最も一般的な停止理由です。Claudeが自然にレスポンスを完了したことを示します。
max_tokens
リクエストで指定されたmax_tokens
制限に達したためClaudeが停止しました。
stop_sequence
Claudeがカスタム停止シーケンスの1つに遭遇しました。
tool_use
Claudeがツールを呼び出しており、実行を期待しています。
pause_turn
Claudeが長時間実行される操作を一時停止する必要がある場合に、ウェブ検索などのサーバーツールで使用されます。
refusal
安全上の懸念によりClaudeがレスポンスの生成を拒否しました。
停止理由を処理するベストプラクティス
1. 常にstop_reasonをチェックする
レスポンス処理ロジックでstop_reason
をチェックすることを習慣にしましょう:
2. max_tokensを適切に処理する
トークン制限によりレスポンスが切り詰められた場合:
3. pause_turnのリトライロジックを実装する
一時停止する可能性のあるサーバーツールの場合:
停止理由 vs エラー
stop_reason
の値と実際のエラーを区別することが重要です:
停止理由(成功したレスポンス)
- レスポンス本体の一部
- 生成が正常に停止した理由を示す
- レスポンスには有効なコンテンツが含まれる
エラー(失敗したリクエスト)
- HTTPステータスコード4xxまたは5xx
- リクエスト処理の失敗を示す
- レスポンスにはエラーの詳細が含まれる
ストリーミングの考慮事項
ストリーミングを使用する場合、stop_reason
は:
- 初期の
message_start
イベントではnull
message_delta
イベントで提供される- その他のイベントでは提供されない
一般的なパターン
ツール使用ワークフローの処理
完全なレスポンスの確保
stop_reason
の値を適切に処理することで、異なるレスポンスシナリオを適切に処理し、より良いユーザーエクスペリエンスを提供する、より堅牢なアプリケーションを構築できます。