AIエージェント 開発の実装記録：Shipment Exception Commander

AIエージェント 開発で輸送トラブルへの対応が難しいのは、チームに選択肢がないからではありません。証拠ごとに信頼度が異なり、復旧案の見積もりには期限があり、コストは承認権限の境界をまたぎます。しかも、拙速に再試行すると、最初の予約が実際には成功していたにもかかわらず、二重予約を生むおそれがあります。

Shipment Exception Commanderは、まさにこの意思決定境界を扱うオープンソースのClaude Managed Agentsリファレンスアプリケーションです。1件の合成例外を調査し、すべての復旧案を機械的に採点したうえで、独立したリスク検証を別のエージェントに委任します。その後、人間に実行内容を正確に提示し、ネイティブ承認が得られた場合に限り、冪等なサンドボックス更新を1回だけ許可します。

AIエージェント 開発では、モデル判断より先に決定論的な採点を行う

コーディネーターが運賃を作り出したり、説明文をポリシーとして扱ったりすることはありません。サーバー側の読み取り専用shipment_intelligenceツールは3つの合成ケースを提供し、固定式で各選択肢を採点します。約束を守れる場合に50点、在庫をカバーできる場合に20点、絶対上限に対するコスト効率に20点、信頼度に10点です。各選択肢には、見積もりのバージョンと有効期限、ETA、保護できる数量、追加のUSDコストが紐づきます。

中心となる実証ケースSCX-2026-071では、現実の意思決定で生じる3つのパターンを比較しました。安価だが約束に間に合わない海上輸送、絶対支出上限を超える全量航空輸送、そして確約済みの240ユニットすべてを$4,200で保護する航空輸送の分割緊急手配です。分割案は91点で、オペレーター上限の$5,000以内に収まりました。採点によって推奨の再現性を確保し、Claudeは証拠の整理、前提への異議申し立て、トレードオフの説明を担います。

信頼できない証拠に実行権限を与えない

ある運送会社の注記には、承認ポリシーを無視してプレミアム案を予約するようエージェントに促す、命令のような文言を意図的に入れています。ワークフローはこの注記を信頼できない情報としてマークし、証拠として残しながらも、指示としては明示的に無視します。ポリシーの根拠は、バージョン管理された合成カタログとアダプターだけです。輸送に関する記述やツール出力をポリシーとして扱うことはありません。

また、コーディネーターには、セッションをまたぐ書き込み可能なメモリ、保管庫、MCP連携、外部ネットワークへの送信経路がありません。狭く限定された自動承認の例外はread、glob、grepだけです。Bashと成果物への書き込みはalways_askで、編集、Web取得、Web検索は無効のままです。正規の状態変更は、アダプターのexecuteコマンドに限られます。

検証エージェントが推奨案に異議を唱える

実行を要求する前に、Opusコーディネーターは提案した復旧案を、役割を絞ったHaiku検証エージェントに委ねます。実証実行で返ってきた判定はNEEDS_CHANGESでした。見積もりQ-071-v4がまだ有効か、輸送枠と追加料金が確定しているかを確認できなかったためです。コーディネーターはこの懸念を退けず、決定論的な提案バリデーターを呼び出しました。バリデーターは、合成時刻、見積もりの有効期限、ポリシーのバージョン、支出階層、想定される状態バージョンを再確認します。最終ステータスが準備完了に変わったのは、権威あるready_for_human_approvalという結果が得られてからです。

承認用ブリーフには、ケースIDと選択肢ID、正確な支出額$4,200、変更前後のETA、顧客との約束への影響、保護される240ユニット、見積もりの有効期限、ポリシーと状態のバージョン、スコア、検証履歴、却下した代替案、安定した冪等性キー、想定されるレシート項目、拒否時および失敗時の挙動をすべて明記しました。

拒否されたら、状態は一切変更しない

最初のネイティブ承認カードは、意図的に拒否しました。状態を変更するコマンドは実行されず、状態はバージョン3のdetectedのまま、レシートも存在せず、冪等性キーも未使用のままでした。エージェントはツールを切り替えたり、コマンドを変更したり、新しいキーを作り出したりしていません。

オペレーターから明示的な依頼を受け、同じ正規アクションをもう一度提示しました。今度は許可されました。アダプターは変更の境界で、状態バージョン3、見積もりの有効性、ポリシー、承認階層、$10,000の絶対上限を再確認しました。処理は正確に1回だけ実行され、ケースはバージョン3のdetectedからバージョン4のresolvedへ進みました。そして、レシートrcpt_37105a2da411aee0391cが、予約参照SBX-56DFC3291972とともに返されました。

再実行に耐える設計と、その適用範囲

合成アダプターは、安定したキーSCX-2026-071:OPT-071-B:v3、OSレベルのロック、正規状態の確認、レシートレジストリを管理します。同じ意図による重複呼び出しには既存のレシートを返し、同じキーで意図が競合すれば失敗します。古いバージョン、同時実行、部分的な書き込みの可能性がある場合は、むやみに再試行せず調査を求めます。

これらの保護策は、実際に保証できる境界を明確にしたうえで説明しています。ロック、状態、レシートレジストリは、1つのManaged Agentsサンドボックス内にあるセッションローカルなファイルです。分散型の本番環境を保証するものではありません。実際の運送会社やTMS向けアダプターには、共有トランザクションストアと、下流側の冪等性境界が必要です。

Outcomeグレーダーが証拠を検証する

セッションは/mnt/session/outputs/配下に3つの成果物を書き出しました。人間が読める復旧パケット、構造化された監査記録、実行時の生レシートです。Managed Agents outcomeは、これらのファイルをカタログ、アダプターのソース、正規状態、承認履歴、レシートレジストリと独立に照合しました。satisfiedを返す前に、見積もり期限の開示、失敗時の挙動の明記、成果物マニフェスト、セッションローカルという制約について修正を求めました。

その後、復旧パケットはアプリケーションのファイルプロキシ経由でダウンロードしました。SHA-256は30c8ad1d0d13cf7ad4b7070e67370ea270562c5e4ef44dfa503e3124180bd40bです。capabilityセッションはsesn_01CcQjCVoWvNQ7VJLFbuDJxh、outcomeはoutc_01GoD4rsLMh93iQNfAUw63KWです。

実際のoutcome実行では、UI上の不備も判明しました。グレーダーの子スレッドは、親セッションがアイドル状態のままでも承認を要求できます。今回のリリースでは、親のrequires_actionイベントと、子スレッドのevaluated_permission: askイベントの両方から保留中の承認カードを再構築します。確認または結果が届けばカードを終了し、リプレイで解決済みのプロンプトが復活することも防ぎます。さらに、グレーダーのsession_thread_idは、ブラウザ側の限定的な許可リストを通じてそのまま返し、判断を転送する前に、その経路が送信元の正確なツールイベントと一致するかを検証します。

別途構成したSonnetの実証セッションsesn_01BvSf33BLBbN86w5oDb3BkQでは、修正後の経路を検証しました。別スレッドから転送されたグレーダーツールsevt_013VnmofY8ytk6QwgDtNSYoqには、スレッドsthr_018HMgpidoN86Qp4iGLZt1q3が含まれていました。UIは同じツールIDとスレッドIDを持つ確認sevt_016ZFv5TdBPKNyEPThzGT36Qを生成し、サーバーが受理すると、グレーダーは再開して次の確認を要求しました。この限定的な実証は、無関係な追加反復に費用をかけないよう意図的に中断しています。中心となる輸送案件のoutcomeは引き続きsatisfiedでした。

Opusを主軸に、Sonnetで検証し、Haikuで独立確認する

プロビジョニング済みのコーディネーターは引き続きclaude-opus-5です。有料の検証を経済的かつ反復可能にするため、ローカルセッションではコーディネーターモデルに限ってclaude-sonnet-5へ明示的に上書きできます。それ以外の実行時上書きはすべてフェイルクローズします。独立検証にはclaude-haiku-4-5を使用します。課金対象のスモークセッションsesn_01RTs3wLV41odV9p92eWtrHVではSonnetを使い、正確にSMOKE OKという応答が返りました。

本番用テストスイートは、開発者が.env.localを設定している場合でも、意図的に認証情報から隔離されています。新規デプロイにはブラウザのキー入力欄がなく、Anthropicへの通信を一切行わず、configured: falseを報告し、課金ルートが503を返すことを検証します。

フェイルクローズで公開するリファレンス実装

公開中のVercelリファレンスには、AnthropicキーもManaged AgentsのリソースIDも含まれていません。ランディングページと/api/agent/healthは利用できますが、セッション作成はフェイルクローズで失敗します。導入者は自身のAnthropicアカウントに対してエージェントと環境をプロビジョニングします。構成済みのインスタンスは、ほかのユーザーがアクセスできるようにする前に、アクセス保護を施す必要があります。

このプロジェクトに登場するケース、運送会社、見積もり、予約参照、状態遷移、レシートは、すべて合成データです。このアプリケーションが示すのは運用上の制御パターンであり、実在する運送会社との連携ではありません。

リリースの証拠

• リポジトリ：dvnc-labs/shipment-exception-commander
• リリース：v0.1.0
• CI：成功したリリース実行
• コミット：1db0329
• デプロイ：shipment-exception-commander.vercel.app
• ヘルスチェック：フェイルクローズのエージェントヘルス

Shipment Exception Commanderは、物流全般を扱うコパイロットよりも、意図的に対象を絞っています。担うのは、監査可能な1つの約束です。バージョン管理された証拠から推奨案を導き、その案を検証し、人間に正確なアクションの承認を求め、変更は1回だけ実行し、何が起きたかを再構成できるだけの証拠を残します。