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

> ECSでエージェントを停止するとSIGTERM後にstopTimeout（Fargateは最大120秒）でSIGKILLされます。長時間処理を壊さない受付停止・待機・中断記録の設計を整理します。

- Canonical: https://kuucorp.com/blog/ecs-agent-draining-sigterm-long-request/
- Date: 2026-11-16
- Last modified: 2026-11-16
- Publisher: Kuu株式会社 (https://kuucorp.com)

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

## 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. 再開側は[冪等性設計](/blog/agent-idempotency-at-least-once-design/)に従い、実行済みの副作用を再実行しない

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

## 規模別の留意点（SMB / エンタープライズ）

### SMB

デプロイ頻度が低いなら、まず `stopTimeout` を処理時間に合わせ、中断時のジョブ状態を1か所に記録するだけで効果があります。伴走が必要なら [AIOps支援](https://kuucorp.com/services/ai-ops/) をご利用ください。

### エンタープライズ

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

## 参考

- [Amazon ECS task lifecycle](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-lifecycle-explanation.html)
- [Optimize load balancer connection draining parameters for Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/load-balancer-connection-draining.html)
- [Amazon ECS task definition parameters for Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html)
- [Edit target group attributes for your Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/edit-target-group-attributes.html)

## まとめ

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