再試行可能メタデータと部分結果

ツールやMCPサーバーが失敗すると、モデルは次に何をするかを判断しなければなりません。"Operation failed"のような汎用的なステータスからは判断材料を得られないため、安全な選択肢は中止するか推測することだけになります。

構造化されたエラーは、行き止まりを判断可能な状態に変えます。再試行すべきでしょうか、失敗を回避する経路に振り分けるべきでしょうか、それとも人間にエスカレーションすべきでしょうか。このレッスンでは、それを可能にする4つのメタデータフィールド、errorCategory、isRetryable、attempted_query、partial_resultsについて学びます。

構造化されたMCPエラーはすべて、1つのブール値isError: trueから始まります。これは、ツールの結果がデータではなく失敗であることを明確に示すシグナルです。

このフラグがないと、モデルはエラーメッセージを正当な回答として扱い、失敗を結果であるかのように喜んで要約してしまう可能性があります。このフラグがゲートとなり、後続の復旧ロジック全体を有効にします。

errorCategoryは、呼び出しが失敗した理由を分類し、モデルが適切に振り分けられるようにします。標準的なカテゴリは次の4つです。

• transient — 一時的な障害（タイムアウト、レート制限）。再試行する価値がある可能性が高いものです。
• validation — 入力の形式が不正です。リクエストを修正し、むやみに再試行しないでください。
• business — ドメインルールによって阻止されました（例：注文がすでに発送済み）。
• permission — 呼び出し元に権限がありません。再試行しても解決しないため、エスカレーションまたは再認証を行います。

カテゴリは戦略を決めるものであり、それだけで判断を完了させるものではありません。

isRetryableは、再試行すれば成功する可能性があるかどうかを明示するイエス・ノーの情報です。カテゴリと組み合わせて使いますが、より明確なシグナルを表します。

transientのタイムアウトは通常、isRetryable: trueです。validationエラーはisRetryable: falseです。不正な入力をそのまま再試行しても、また失敗するだけだからです。重要なのは、これによりサブエージェントが、あらゆる小さな障害をコーディネーターへ伝播させるのではなく、transient障害をローカルで復旧できることです。

試験でも重要な微妙な違いがあります。アクセスの失敗は、有効な空の結果と同じではありません。

• isError: true + transient → クエリを実行できませんでした。再試行を検討してください。
• isError: false + 空のリスト → クエリは正常に実行され、本当に一致するものがありません。再試行は無意味で、リソースの浪費です。

汎用エラーでは、この違いが曖昧になります。構造化されたメタデータを使えば、「調べられなかった」と「調べたが何もなかった」を明確に区別できます。

attempted_queryには、ツールが実行しようとした内容、つまりSQL、API呼び出し、検索文字列などが正確に記録されます。これは2つの役割を果たします。

• モデルがフィードバックを生かして再試行できます。元の意図とエラーを渡すことで、修正されたクエリを作成できます。
• プロヴナンスに利用できます。実際に何を問い合わせたのか、主張と出典の追跡関係を保持できます。

覚えておいてください。フィードバック付きの再試行で修正できるのは、形式上または構造上の誤りです。情報が単にソースに存在しない場合は、何度問い合わせ直しても役に立ちません。

複数ステップまたは複数ソースにまたがる処理が途中で失敗しても、失敗前に行った作業には価値があります。partial_resultsは、その結果を引き継ぎます。

5つのソースを検索する調査サブエージェントが、5つ目でタイムアウトしたとします。4つの成功した結果とエラーを返せば、コーディネーターは処理を続けられます。1つが失敗したからといって、すべてを破棄する必要はありません。1つの失敗でワークフロー全体を中止してはいけません。

このメタデータにより、ハブアンドスポーク型システムで明確な2段階の戦略を実現できます。

• サブエージェント内でtransient障害をローカルに復旧する — isRetryableのものを静かに再試行します。
• 回復不能な失敗をコーディネーターへエスカレーションする — 失敗の種類、試行したクエリ、部分的な結果を含む完全な構造化コンテキストを渡します。

エラー処理と振り分けを担うのはコーディネーターです。ただし、サブエージェントが単なる例外や無言の応答ではなく、構造化されたシグナルを渡して初めて、適切に振り分けられます。

エラーを構造化された出力として定義する場合は、スキーマのルールを慎重に適用してください。フィールドは常に存在する場合にのみ必須にするべきです。ハードな失敗ではpartial_resultsが空であったり存在しなかったりすることが多いため、必須にすると、モデルがスキーマを満たすためにエントリを捏造する可能性があります。

errorCategoryには、「other」の値を含むenumと、自由記述の詳細フィールドを使用してください。これにより、現在の分類を明確に保ちながら、まだ遭遇していない失敗パターンにも拡張できます。

メタデータはモデルを確率的に（約90%）誘導します。しかし、失敗が金銭、法務、安全に関わる場合、それだけでは不十分です。

PostToolUse hookを使って、モデルが結果を見る前にツールの結果を傍受し、ポリシーを決定論的に（100%）適用してください。たとえば返金ツールでerrorCategoryがpermissionの場合、再試行をブロックしてエスカレーションを強制します。プロンプトどおりに動作することを任せてはいけません。

失敗に対して最もしてはいけないことは、隠すことです。避けるべき失敗モードは2つあります。

• サイレントな抑制 — エラーを握りつぶし、空の結果や作り上げた結果を返します。これではモデルは、本当に「一致なし」なのか、クエリが壊れていたのかを区別できません。
• 1つの処理経路が失敗しただけでワークフロー全体を中止する — それまでに得た部分的な結果をすべて捨てることになります。

構造化されたエラーは、どちらの問題も解決します。失敗を表面化すると同時に、成功した部分も保持できるからです。

構造化されたエラーは、失敗を振り分け可能な判断に変えます。

• isError — 復旧ロジックを有効にするゲートです。
• errorCategory — transient / validation / business / permission（+ 「other」）によって戦略を決めます。
• isRetryable — 明示的な再試行のヒントです。transient障害はローカルで復旧します。
• attempted_query — フィードバック付きの再試行とプロヴナンスを可能にします（情報が本当に存在しない場合には役立ちません）。
• partial_results — 有用なデータを引き継ぎます。1つの失敗でワークフロー全体を中止してはいけません。

必須にするのは常に存在するフィールドだけにし、金銭・法務・安全に関わる失敗は決定論的なフックで保護し、エラーを決して黙って抑制しないでください。これがアーキテクトレベルのエラーハンドリングです。