約 3 分で読めます

ECSで実行中のエージェントを安全に停止する設計

デプロイやスケールインのたびに、数分かかるエージェントのツール実行が途中で消える。ECSの標準設定は短い応答のWebアプリを前提にしており、長時間処理にそのまま流用すると中断が構造的に起きます。台数の増減指標はオートスケーリング設計に譲り、本稿は「止める側」の手順だけを扱います。

ECSはタスクをどの順序で止めるのか

ECSは登録解除、SIGTERM、stopTimeout待機後のSIGKILLの順にタスクを停止します。

公式のタスクライフサイクルでは、ELBターゲットグループへの登録解除はDEACTIVATING状態で行われます。続くSTOPPINGで、コンテナにはイメージの STOPSIGNAL(既定はSIGTERM)が送られ、タスク定義の stopTimeout が過ぎるとSIGKILLが送られます。

設計上の要点は2つです。

  • 受付停止(ALB側)と終了シグナル(プロセス側)は別の機構で、アプリは自分で「新規を受けない」状態に入る必要がある
  • SIGKILLはプロセスが何をしていても届く。待機の上限は stopTimeout で決まる

stopTimeoutとderegistration delayは何秒に設定すべきか

stopTimeoutは既定30秒で上限120秒、ALBの待機は既定300秒です。

タスク定義の stopTimeout は、未指定なら30秒、最大値は120秒です(Fargateはプラットフォームバージョン1.3.0以降のLinux)。ALBの deregistration_delay.timeout_seconds の既定は300秒で、deregistration中のターゲットには新規リクエストが送られず、進行中のリクエストの完了を待ちます。

公式のドレイン最適化ガイドは、応答が1秒未満のサービスでこの値を5秒に短縮する例を示しますが、低速アップロードやストリーミングのような長時間リクエストでは5秒にしてはならないと明記しています。エージェントの長いSSE接続やツール実行は後者に当たります。

次の関係を満たすように揃えます。

  1. 想定最長の処理時間が stopTimeout の範囲に収まるなら、その値に合わせる
  2. 収まらない処理は、待ち切る設計をやめて「中断を記録して再開できる」設計にする
  3. deregistration delayは、接続が閉じるまでの待ちであって処理完了の保証ではない

120秒を超える処理を「待てば終わる」前提にしないことが最重要です。無停止は保証されません。

SIGTERMを受けたエージェントは何をすべきか

SIGTERMを受けたら新規受付を止め、進行中の処理を待ち、残りは中断状態を永続化して終了します。

公式の例(Node.jsの server.close())は、リスニングを止めて進行中のリクエストに応答し、イベントループが空になれば終了する、という基本形です。エージェントではこれに状態の保全を足します。

  1. シグナルを受けたら、新規タスクの受付フラグを落とし、ヘルスチェックを失敗させる
  2. 進行中のLLM呼び出し・ツール実行を、残り時間(stopTimeout から安全マージンを引いた値)まで待つ
  3. 残り時間が尽きる前に、未完了ジョブのID・直近のチェックポイント・実行済みツール呼び出しを外部ストアへ書く
  4. 再開側は冪等性設計に従い、実行済みの副作用を再実行しない

コンテナ側の確認事項もあります。シェル経由で起動するとSIGTERMがアプリに届かないことがあるため、アプリが確実にシグナルを受けるエントリポイントになっているかを検証します。長時間処理の永続化を基盤側で担うなら、Durable Executionの採用も選択肢です。

規模別の留意点(SMB / エンタープライズ)

SMB

デプロイ頻度が低いなら、まず stopTimeout を処理時間に合わせ、中断時のジョブ状態を1か所に記録するだけで効果があります。伴走が必要なら AIOps支援 をご利用ください。

エンタープライズ

複数チームが同一クラスタを共有する場合、stopTimeout の上限(Fargateは120秒)を超えるジョブをどう扱うかを全体の標準にします。中断記録の形式とキューへの差し戻しを共通基盤に寄せる設計は、RDE で支援しています。

参考

まとめ

ECSの停止は、ターゲット登録解除、SIGTERM、stopTimeout 後のSIGKILLの順で進みます。長時間のエージェント処理では、待ち切る前提を捨て、受付停止・待機・中断記録の3点をアプリ側に実装してください。停止設計のご相談は Kuu株式会社 までお問い合わせください。

関連記事

AIエージェントのカオスエンジニアリング——障害注入設計パターンLinked billingでエンドカスタマーに課金する設計Claude組織webhookの受信設計と取りこぼし対策Claude APIの429を3種に分類する再試行設計