メインコンテンツへスキップ
失敗した実行は、run または continue の呼び出しからスローするか、エラーを返します。一時停止(waiting_for_human)や停止条件(stopped)はエラーではなく、どちらも通常の結果を返します。どの失敗で run.failed イベントも送られるかは言語によって異なるため、失敗の検出をイベントだけに頼らないでください。

失敗した実行の表れ方

失敗時に発生するイベント

すべてのイベントはライフサイクルフックにあります。

エラーの原因を見つける

TypeScript のエラーの型

AgentGatewayError には、status、statusText、headers、body、requestId、generationId、reason、errorType、errorOrigin、failedProviders、failedStatuses と、ルーティングの診断情報があります。失敗した実行とステップは、同じ詳細を errorDetails に保持します。ストリーミング中のレスポンスの途中で起きた失敗は AgentStreamError で、これは code と retryable を持つサブクラスです。 AgentSchemaValidationError は、tool_input、tool_output、tool_event、agent_output のいずれかの target と、バリデーターのエラーを含む details を持ちます。これらは一時的なモデルの失敗ではなく、契約違反として扱ってください。 modelRetry.retryOn などでエラーを分類するには、agentErrorIsRetryable(error)、agentRetryAfterMs(error)、agentErrorIsContextOverflow(error) を使います。

Rust のエラーの型

ランタイムのすべての失敗は AgentError で、message() で読み取ります。Gateway の PhaseoError の値は AgentError に変換されるため、元の Gateway のステータスと本文が必要な場合は、phaseo クライアントを直接呼び出すか、それらを保持する独自の ModelClient を実装してください。

ツールエラーから回復する

デフォルトでは、ツールのエラーは実行を失敗させます。モデルが別の方法を試すのが妥当な場合は、ツールのエラー時の方針を return-to-model にします。エラーはツールの結果 {"error": "..."} になり、実行は続きます。安全でない失敗や回復できない失敗には、デフォルトの fail-run のままにしてください。

キャンセルとタイムアウトを処理する

ツールのタイムアウトやキャンセルが、ツール自身の処理を必ず止めるとは限りません。ツール内の HTTP、データベース、プロセスの呼び出しにはそれぞれ期限を設け、キャンセルまたはタイムアウトした実行は、アプリケーションが新しい実行を始めない限り終了したものとして扱ってください。

中断された TypeScript の実行から回復する

実行がステップの途中でクラッシュまたはキャンセルされた場合、その履歴に結果のないツール呼び出しが残ることがあり、プロバイダーはこれを拒否します。TypeScript の continueRun() は、それらに未実行として応答し、history.repaired を送ります。メッセージを別の場所で再利用する場合は、自分で repairToolHistory(messages) を呼び出してください。

最初に確認すること

  • PHASEO_API_KEY がプロセスに渡され、Gateway クライアントに渡されている。
  • すべてのツールに、一意で安定した ID がある。
  • 承認、拒否、ツール出力に正確なツール呼び出し ID を使っており、人の入力メッセージをツール出力の代わりにしていない。
  • 承認の UI を表示する前、または別のリクエストやワーカーに制御を渡す前に、実行結果全体を保存している。
  • バリデーターが決定的で副作用がなく、失敗した確認を安全に再試行できる。
  • モデルの再試行に上限があり、検証や承認の失敗をむやみに再試行していない。
どのステップが失敗したかを確認するには、ライフサイクルフックで step.started、model.requested、tool.failed を記録してください。ステップを Gateway のログに結び付ける ID についてはオブザーバビリティを参照してください。
最終更新日 2026年11月5日