Qoder Agent SDK は、タスクの失敗、SDK の失敗、プロセスの終了を別々に通知します。すべての失敗を例外として扱わず、利用できる最も具体的なシグナルを処理してください。
Result メッセージの
将来のランタイムで Result subtype が追加される可能性があります。未知の subtype と
TypeScript の
現在の qodercli ランタイムは、次の数値コードを正規化し、TypeScript と Python の SDK では
SDK 例外は、アプリケーションがセッションを設定、開始、制御、または継続できなかったことを示します。Agent の失敗 Result とは別です。
Java のモデル選択コールバックのタイムアウトは例外としてアプリケーションに渡されないため、
起動後に認証情報の期限切れが判明した場合は、
Java SDK 独自の例外はすべて非検査例外の
次のエラーコードはセッションが終了したことを示します:
カーソルを閉じると、所属するクエリまたはセッションが非同期に閉じられます。例外とエラーコードの一覧は Java 例外一覧を参照してください。
SDK を使用するアプリケーションは、通常、プロセス終了コードで分岐せず、Result と SDK 例外を処理します。終了コードは主に Transport の診断、または SDK 外で qodercli を直接起動する場合に使用します。
その他の終了コードやシグナルは、OS、カスタムランタイム、子プロセスから発生する場合があります。TypeScript は
障害調査に役立つ情報として、次を保持します。
error_code と qodercli プロセスの終了コードは、別の番号体系です。一方の値をもう一方の表と照合しないでください。
推奨する処理順序
- SDK が
resultを返すか、例外を送出するまでメッセージを処理します。 - Result では、最初に
subtypeとis_errorを確認します。error_codeが存在する場合のみ、より具体的な復旧処理の選択に使用します。 - メッセージ反復全体を囲んで SDK 例外を捕捉します。例外クラスとフィールドから、設定、ランタイム、Transport の問題を診断します。
- セッション ID、Result subtype、エラーコード、例外名を記録します。認証情報やソースコード全体は、デフォルトでは記録しないでください。
Result subtype
subtype | 意味 | 推奨する対応 |
|---|---|---|
success | Agent がターンを完了した | result を読み、セッションを続けるか閉じる |
error_during_execution | 実行、モデル、サービス、認証、または回復不能なツールエラーで停止した | errors を確認し、利用可能なら error_code を使う。一時的な原因だけを再試行する |
error_max_turns | 設定された最大ターン数に達した | ループやブロックされたツールを確認し、さらにターンが必要な場合だけ上限を増やす |
errors を記録するフォールバック分岐を用意し、この表がすべてを網羅すると仮定しないでください。
Result を処理する
TypeScript の SDKResultMessage.error_code は任意の number | string、Python の ResultMessage は任意の数値コードを公開します。TypeScript は CLI が返した storage_insufficient などの文字列コードや未知のコードをそのまま保持します。フィールドが存在する場合に使用し、ユーザー向けエラーテキストを解析してコードを取り出さないでください。
Java の ResultMessage にはエラーコードのフィールドがありません。outcome() は正規化した結果 SUCCESS、ERROR、UNKNOWN を返し、wireSubtype()、wireIsError()、errors() はそれぞれ subtype、is_error、errors に対応します。error_code が必要な場合は rawJson() から読み取ります。
Result エラーコード
現在の qodercli ランタイムは、次の数値コードを正規化し、TypeScript と Python の SDK では message.error_code で返すことがあります。Java では ResultMessage.rawJson() の error_code フィールドから読み取ります。このフィールドは任意です。また、qodercli は表にない数値サービスコードをそのまま返すことがあります。未知の値はログに残し、subtype と errors をフォールバックとして使用してください。
認証とクォータ
| コード | 意味 | 推奨する対応 |
|---|---|---|
105 | ログインまたは Access Token の期限切れ | 有効な認証情報を取得して新しいセッションを作成し、認証期限切れコールバックを登録する |
110 | 1 日の使用量上限に到達 | 使用期間のリセットを待つか、アカウント上限を確認する |
113 | 使用クォータを消費済み | クォータとプランを確認し、条件を変えずにすぐ再試行しない |
114 | 無料トライアルアカウントの上限に到達 | アカウントの利用資格またはアップグレードを確認する |
115 | 無料ユーザーのクォータに到達 | クォータの更新を待つか、アップグレードを確認する |
116 | チーム管理者の Credits を消費済み | チーム管理者が Credits を補充または調整する |
117 | チームメンバーの Credits を消費済み | チーム管理者に Credits の割り当てまたは補充を依頼する |
118 | 個人の Credits を消費済み | Credits を補充するか、利用可能なアカウントを使用する |
119 | 選択したモデルの無料使用上限に到達 | 利用可能なモデルへ切り替えるか、更新を待つか、プランを確認する |
122 | Billing Group の Credits 上限に到達 | 請求管理者にグループ上限の確認を依頼する |
リクエストとポリシー
| コード | 意味 | 推奨する対応 |
|---|---|---|
406 | 機密コンテンツまたはモデルの拒否によりリクエストがブロックされた | タスクまたは入力を変更し、同じ内容を再試行しない |
416 | 要求した範囲またはリクエスト形式を満たせない | errors を確認し、要求範囲を縮小または修正する |
430 | 要求した機能がサポートされていない | 互換性のある SDK/qodercli へ更新するか、サポートされる機能を使用する |
47902 | Agent の最大ターン数に到達 | 上限を増やす前に、ループ、権限、ツール障害を確認する |
48716 | Hook が Agent の実行をブロックした | 対象 Hook の判断を確認し、Hook またはタスクを修正する |
80411 | 入力コンテンツが長すぎる | プロンプト、添付ファイル、保持するコンテキストを減らす |
80412 | 画像または文書が多すぎる | メディア添付の数を減らして再試行する |
サービスとモデルランタイム
| コード | 意味 | 推奨する対応 |
|---|---|---|
500 | リクエストまたはネットワーク障害 | 接続を確認し、回数を制限した指数バックオフで再試行する |
10408 | リクエストのタイムアウト | バックオフして再試行し、繰り返す場合はタスクを小さくする |
10500 | モデルサービスの内部エラー | 後から再試行し、サポートへの問い合わせではセッション ID を残す |
10605 | モデルリクエストがキュー待ち | qodercli は通常待機して再試行する。Result に届いた場合は後から再試行する |
SDK 例外
SDK 例外は、アプリケーションがセッションを設定、開始、制御、または継続できなかったことを示します。Agent の失敗 Result とは別です。
| 状況 | TypeScript | Python | Java | 重要なフィールド |
|---|---|---|---|---|
| 認証が未設定 | code: "auth_not_configured" を持つ Error | code: "auth_not_configured" を持つ Error | InvalidOptionsException | code、Java の getCode() |
| PAT 環境変数がない | AuthAccessTokenEnvVarError | AuthAccessTokenEnvVarError | AuthenticationException | code、Java の getCode() |
| Service Account 環境変数がない | AuthServiceAccountEnvVarError | AuthServiceAccountEnvVarError | — | code |
| qodercli が見つからない、または起動できない | QoderCliProcessError | CLINotFoundError / CLIConnectionError | CliNotFoundException、RuntimeInstallException、またはエラーコード CLI_START_FAILED の QoderException | メッセージ、TypeScript の stderr、Python のパス/メッセージ、Java の getCode() |
| qodercli が予期せず終了した | QoderCliProcessError | ProcessError | CliProcessException。終了コード 41 の場合は AuthenticationException | exitCode / exit_code、stderr、TypeScript の signal、Java の getExitCode()、getStderrTail() |
| モデル選択コールバックのタイムアウト | ModelPolicyTimeoutError | ModelPolicyTimeoutError | 例外を投げない。表の後の説明を参照 | timeoutMs / timeout_ms |
| プロトコルバージョンの不一致 | ProtocolVersionMismatchError | ProtocolVersionMismatchError | ProtocolVersionMismatchException | CLI と SDK のプロトコルバージョン |
| ランタイムに必要な機能がない | UnsupportedCliCapabilityError | UnsupportedCliCapabilityError | UnsupportedCliCapabilityException | capability、Java の capabilityState() |
| 初期化完了前に CLI が失敗 Result を返す | QoderCliInitializationError | — | — | message、code、result |
catch では捕捉できません。SDK はエラーコード MODEL_RESOLUTION_TIMEOUT を CLI に返し、診断リスナーに inbound_control_request_failed イベントを送ります。その detail には error=MODEL_RESOLUTION_TIMEOUT が含まれます。このケースを検出するには DiagnosticsListener を登録し、このターンの結果は ResultMessage.outcome() で処理して、ERROR の場合は errors() を読み取ってください。
TypeScript の startup() と query.initializationResult() は、初期化完了前に CLI が失敗 Result を返すと QoderCliInitializationError を送出します。message は CLI のエラーテキスト、code は任意の数値または文字列の error_code、result は元の Result を保持します。キャンセルは AbortError として扱われます。初期化完了後の失敗は引き続き Result メッセージとして返されます。
TypeScript と Python の SDK で共通する機械可読な認証設定コードは次のとおりです。
code | 意味 |
|---|---|
auth_not_configured | 認証方式が指定されていない |
auth_access_token_env_var_not_configured | 設定した PAT 環境変数が存在しない |
auth_service_account_env_var_not_configured | 設定した Service Account 環境変数が存在しない |
onAuthExpired / on_auth_expired を使用し、有効な認証情報で新しいセッションを作成してください。Java にはこのコールバックがないため、AuthenticationException として処理します。SDK 認証を参照してください。
例外とエラーコード(Java)
Java SDK 独自の例外はすべて非検査例外の QoderException を継承しており、getCode() で安定したエラーコードを取得できます。引数エラーと設定エラーは呼び出し時に同期的に投げられます。たとえば build() の検証に失敗すると InvalidOptionsException が投げられます。起動時と実行中の失敗は、メッセージカーソルの hasNext() / next()、consume() が返す stage、その他の非同期メソッドが返す stage から通知されます。join() で待機すると CompletionException に包まれるため、getCause() で元の例外を取り出します。
SDK は自動で再試行せず、組み込み例外の isRetryable() はすべて false を返します。よくあるエラーコードの扱い方は次のとおりです。
| エラーコード | 対処 |
|---|---|
INVALID_OPTIONS | 設定を修正する。再試行しても意味はない |
AUTHENTICATION_FAILED、CLI_AUTH_FATAL | 認証情報またはアカウントの権限を修正してから、新しいクエリまたはセッションを作成する |
CLI_NOT_FOUND、RUNTIME_INSTALL_FAILED、CLI_START_FAILED、UNSUPPORTED_SECURE_SECRET_TRANSPORT | CLI のパス、マネージド CLI のダウンロード、起動環境を確認する。トラブルシューティングを参照 |
CLI_PROCESS_FAILED | getExitCode() と getStderrTail() を記録する |
UNSUPPORTED_CLI_CAPABILITY | 現在の CLI は呼び出した機能をサポートしていない。CLI を自分で指定している場合は SDK がマネージドする固定バージョンに切り替え、そうでなければその機能を使わない |
SESSION_CLOSED | リソースは閉じられている。呼び出しをやめ、必要なら新しいセッションを作成する |
MESSAGE_STREAM_ALREADY_CONSUMED | 各メッセージストリームは 1 回しか消費できない。openCursor() と consume() は合わせて 1 回しか呼べない |
SPOOL_CAPACITY_EXCEEDED | 未消費のメッセージがバッファの上限を超えた。メッセージストリームを速やかに読み取る |
QUERY_WRITE_FAILED(単発クエリの入力が CLI に書き込まれなかった)、CONTROL_WRITE_FAILED(制御リクエストまたはレスポンスが CLI に書き込まれなかった)、TURN_ACCOUNTING_FAILED(ターンの状態をこれ以上処理できない)、MESSAGE_DELIVERY_FAILED(バッファ内のメッセージをデコードできなかった)。元のセッションは使い続けられません。ハンドルを閉じ、getCause() で原因を記録してください。会話を続ける場合は、元のセッション ID で SessionOptions.Builder.resume(String) を使って新しいセッションを作成します。
MessageCursor.hasNext() または next() でブロックしているスレッドが割り込まれると ConsumerInterruptedException が投げられ、スレッドの割り込みフラグはセットされたままになります。読み取りをやめる場合はカーソルを閉じます。
Java
qodercli プロセス終了コード
SDK を使用するアプリケーションは、通常、プロセス終了コードで分岐せず、Result と SDK 例外を処理します。終了コードは主に Transport の診断、または SDK 外で qodercli を直接起動する場合に使用します。
| 終了コード | 意味 |
|---|---|
0 | プロセスの正常終了 |
1 | 一般または未分類の失敗 |
41 | 認証失敗。設定されている場合、SDK は認証期限切れコールバックも呼び出す。Java ではエラーコード CLI_AUTH_FATAL の AuthenticationException として報告される |
42 | 無効な入力またはコマンドライン引数 |
44 | 致命的なサンドボックスエラー |
52 | 致命的な設定エラー |
53 | 致命的なターン上限エラー |
54 | 致命的なツール実行エラー |
130 | キャンセルまたは割り込み |
QoderCliProcessError.exitCode と .signal、Python は ProcessError.exit_code で利用可能な終了コードを公開し、Java は CliProcessException.getExitCode() で公開します。
ログとサポート
障害調査に役立つ情報として、次を保持します。
- SDK の言語とバージョン
- 利用できる場合は
system/initメッセージの qodercli バージョン session_id、Resultsubtype、任意のerror_code、errors- 例外クラス、機械可読な
code、プロセス終了コード、シグナル - 初期化前、ツール呼び出し中、Result の後のどこで失敗したか
次のステップ
- SDK 認証 — 認証情報の設定と期限切れの処理
- 権限 — ツールの拒否と承認動作の理解
- Hooks — Hook による実行ブロックの診断
- セッション制御 — 実行中セッションの中断と管理
- SDK References — 各言語の正確な型の確認