本番パターン

フレームワークの強力な機能は、障害パターンとして覚えると理解しやすくなります。以下の各項目は、本番で実際に起こる障害の種類と具体的な仕組みを示しており、単なる標語ではありません。

複数ステップ操作の部分的な失敗

Failure: 1つ目のステップは成功し、2つ目は失敗したため、エージェントはどの副作用がすでに発生したか判断できません。

Mechanism: ワークフローを、明示的な補償パスを持つ1つのアクションにまとめます。利用可能な復旧アクションとともに f.error() を返し、安全にリトライできるかをエージェントに推測させないでください。トランザクションや冪等性キーはハンドラーとデータベース側に置きます。

パラメーターの幻覚

Failure: モデルが tenantId、emailAddress、その他のもっともらしいフィールドを作り出します。

Mechanism: すべてのアクションスキーマは厳格です。不明なキーはミドルウェアとハンドラーの前に拒否され、送信された内容と期待された内容を <validation_error> で説明します。テナントの識別情報はツール入力ではなく、必ず ctx から取得します。

リクエストの集中

Failure: 多数のエージェントが同じ遅い上流サービスをリトライし続け、コネクタ自身のリソースを使い果たします。

Mechanism: .concurrency({ maxActive, maxQueue }) は実行中と待機中の処理を制限します。容量がいっぱいになるとリトライ案内付きで SERVER_BUSY を返します。上流のタイムアウトと、テナントまたはトークン単位のレートリミッターを組み合わせてください。

コンテキストウィンドウの超過

Failure: コレクションのレスポンスが大きすぎて、モデルが重要な行を失い、誤った判断をします。

Mechanism: Presenterの .agentLimit() はシリアライズ前に切り詰め、非表示にした行数とフィルターを使う案内を含む要約を先頭に追加します。.enableSelect() により、モデルはトップレベルのフィールドだけを要求できます。出力バイトガードは、最後のテキストレスポンスが大きすぎる場合に検出します。

ミューテーション後の古いデータ

Failure: 書き込みが成功した後も、エージェントは自分のコンテキスト内で古い読み取り結果を見ます。

Mechanism: 読み取りには .cached() または .stale()、書き込みには .invalidates('domain.pattern') を付けます。状態同期レイヤーは説明を装飾し、最初のブロックに無効化マーカーを出し、ミューテーション成功後にだけリソース更新を公開します。

盲目的なリトライループ

Failure: エラーが「失敗」としか伝えないため、モデルが同じ無効な呼び出しを繰り返します。

Mechanism: toolError(code, { suggestion, availableActions, retryAfter }) は構造化されたXML復旧契約を出力します。次のアクション名と待ち時間が明示され、型付きクライアントは MCPFusionClientError に解析できます。

モデルへのデータ漏えい

Failure: ハンドラーが、モデルに見せてはいけないフィールドを含むデータベース行を返します。

Mechanism: allowlistスキーマと .redactPII() を持つPresenterを付けます。宣言されていないフィールドは検証済み出力に入らず、宣言済みの機密パスはネットワークに送るクローン上でマスクされます。result.data を @mcpfusion/testing でテストしてください。

破壊的操作の競合

Failure: 2つのエージェントが同時に返金、ワークフロー遷移、同じレコードの更新を行います。

Mechanism: f.mutation() はデフォルトでアクションを破壊的とし、builderはアクション単位のFIFOミューテーションシリアライザーを作成します。ドメイン層にも冪等性を追加してください。シリアライズは呼び出し順を制御しますが、外部の決済APIを冪等にはしません。

運用チェックリスト

Deploy の前に、次を確認します。

• 厳格な入力とコンテキストからのテナント識別情報
• ドメインデータを返すすべてのツールへのPresenter
• すべてのコレクションへの上限
• 上流呼び出しへの同時実行制限とレート制限
• 書き込み時の無効化
• 想定エラーの復旧フィールド
• CIでのlockfileとテスト
• 生のシークレットを保存しないテレメトリーと監査シンク

次のステップ

• Testing: 各項目を回帰テストにする
• Contracts: CIでドリフトを防ぐ
• Security pipeline: 実行順序を確認する