# キューとメッセージブローカーでAI Agentを非同期に動かす CURRENT_STATUS: CURRENT OBSERVATION: SPEC_ONLY FRESHNESS: CURRENT PAGE_TYPE: reference CANONICAL_URL: /tools/ea-232-ai-agent CLAIM_IDS: none EVIDENCE_IDS: EVD-EA-232-URL-55784620EADE, EVD-EA-232-URL-610FBD2EE3C2, EVD-EA-232-URL-9E493C29EF9B, EA-232-CURRENT-APPROVAL, EA-232-CURRENT-BODY-READBACK UNKNOWN_IDS: EA-232-UNKNOWN-01 OPS_IDS: none ## Summary キューは、依頼を受け付ける処理と、AIや外部ツールで実行する処理を時間的に分離します。待ち行列に入れたことは、業務が完了したことではありません。また、再配信や再試行は通常の故障回復経路です。Agentがメール送信や発注を行う場合は、メッセージの配送保証と、業務上の作用を一度に抑える制御を分けて設計します。 ## Current judgment Amazon SQSのstandard queueは、保存したメッセージのコピーが再び配信される可能性を説明し、アプリケーションの冪等性を求めています[S1]。visibility timeoutは、受信済みメッセージを一時的に見えなくする期間です。期限内に削除しなければ再配信され得ます。絶対的な重複排除や外部処理のロックを保証するものではありません[S2: Handling failures / Understanding visibility timeout]。 ## Scope キューとメッセージブローカーでAI Agentを非同期に動かす ## Confirmed - Amazon SQSのstandard queueは、保存したメッセージのコピーが再び配信される可能性を説明し、アプリケーションの冪等性を求めています[S1]。visibility timeoutは、受信済みメッセージを一時的に見えなくする期間です。期限内に削除しなければ再配信され得ます。絶対的な重複排除や外部処理のロックを保証するものではありません[S2: Handling failures / Understanding visibility timeout]。 Apache Kafkaの設計文書は、トランザクションで入力offsetと出力topicを対応させる方法を説明する一方、外部システムへの書込みでは、その出力とconsumer位置を協調させる必要があると区別しています[S3: Message Delivery Semantics]。Kafka内のexactly-once処理という性質を、任意のHTTP APIや銀行・メール等の副作用へ延長しません。 ## UNKNOWN - EA-232-UNKNOWN-01: 今回、実ブローカーへの負荷試験や外部APIの副作用試験は実施していません。製品別の配信モード・保持・quota・順序・トランザクション構成、実APIの冪等性、障害時の再配信率、組織固有の容量はUNKNOWNです。上の制御表は設計案であり、そのまま配置すれば一回性を保証する共通実装ではありません。原本の停止・取消と、すでに外部へ到達した作用の取消も分けます。 ## Evidence - EVD-EA-232-URL-55784620EADE (RESEARCH): [S1] AWS, SQS at-least-once delivery. — https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/standard-queues-at-least-once-delivery.html - EVD-EA-232-URL-610FBD2EE3C2 (RESEARCH): [S2] AWS, SQS visibility timeout. — https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html - EVD-EA-232-URL-9E493C29EF9B (RESEARCH): [S3] Apache Kafka 4.2, Design / Message Delivery Semantics. — https://kafka.apache.org/42/design/design/ - EA-232-CURRENT-APPROVAL (RESEARCH): 現行本文の監査・revision対応 - EA-232-CURRENT-BODY-READBACK (IMPL): 現行本文の収録照合 ## Failure / limits | 失敗 | 制御 | 読み戻す証拠 | | --- | --- | --- | | worker停止で再配信 | operation単位の冪等性と結果照合 | 外部結果と処理記録の対応 | | 長い推論中にvisibility失効 | 作業単位を短くし、必要時に期限更新 | 更新失敗と二重workerの有無 | | 古いworkerが遅れて書込む | 対象版・世代を使う条件付き更新 | 新しい結果が上書きされないこと | | retryが外部障害を増幅 | 上限、backoff、jitter、受付制御 | 試行回数、429、待ち時間 | | 認可失敗を反復 | 永続失敗として隔離し責任者へ | 期限・権限の失敗原因 | | DLQへ移して放置 | owner、修正条件、再投入手順を定義 | 受領・解決・再投入結果 | ackは、どの状態まで永続化したら行うかを明示します。AIの文章が得られた時点、承認された時点、外部作用が確認された時点は異なります。実行前の計画作成と実行を別メッセージに分ける場合も、承認された計画hashと実際の入力が一致することを確認します。 ## PUBLIC_CLAIM キューは、依頼を受け付ける処理と、AIや外部ツールで実行する処理を時間的に分離します。待ち行列に入れたことは、業務が完了したことではありません。また、再配信や再試行は通常の故障回復経路です。Agentがメール送信や発注を行う場合は、メッセージの配送保証と、業務上の作用を一度に抑える制御を分けて設計します。 ## ESTABLISHED Amazon SQSのstandard queueは、保存したメッセージのコピーが再び配信される可能性を説明し、アプリケーションの冪等性を求めています[S1]。visibility timeoutは、受信済みメッセージを一時的に見えなくする期間です。期限内に削除しなければ再配信され得ます。絶対的な重複排除や外部処理のロックを保証するものではありません[S2: Handling failures / Understanding visibility timeout]。 Apache Kafkaの設計文書は、トランザクションで入力offsetと出力topicを対応させる方法を説明する一方、外部システムへの書込みでは、その出力とconsumer位置を協調させる必要があると区別しています[S3: Message Delivery Semantics]。Kafka内のexactly-once処理という性質を、任意のHTTP APIや銀行・メール等の副作用へ延長しません。 ## DESIGN_BOUNDARY SQSのような作業キューでは、処理が終わったメッセージをacknowledge・削除する設計が中心になります。Kafkaのようなログでは、保存された記録とconsumer groupの読取位置を管理し、再読込が可能です。これらは概念の違いであり、製品を二つの箱へ完全に分類するものではありません。Pub/Sub、Service Bus、NATS等を選ぶ場合も、採用する配信方式と構成ごとに同じ確認を行います。 | 確認する契約 | Agent運用で必要になる理由 | | --- | --- | | 配送・保持 | 再配信、保持期限、障害時の依頼消失を扱う | | 順序 | 同じ顧客・案件の変更順を守る範囲を決める | | 同時実行 | worker数だけでなく外部APIと人の承認容量を守る | | 再試行 | retry可能な失敗と結果不明・永続失敗を分ける | | 隔離 | 不正形式や権限不足の案件をDLQ等へ分ける | | 再生 | 修正後に何を再実行し、何を照合だけにするか決める | 製品名から保証を推定せず、queue種別、partition・message group、保持期間、ack条件、consumer設定、DLQ設定を固定します。順序を保証する単位を大きくすると、先頭の一件が後続を止める可能性があります。並列化のために単位を小さくすると、関連する操作が競合し得ます。 ## MESSAGE_AND_EFFECT_CONTRACT 以下は辞典が提案する最小契約です。メッセージには業務operation ID、メッセージID、試行ID、tenant、依頼者、対象資源、対象版、入力locator/hash、期限、必要な権限・承認の参照を持たせます。モデルが作ったJSONを、そのまま権限のある命令として受け取りません。workerは実行時に依頼の有効性と認可を再確認します。 業務operation IDは、同じ意図の再試行で維持します。試行IDは変えます。外部APIが冪等性keyを提供するなら、その有効範囲・保存期間・入力不一致時の動作を確認します。アプリの「処理済み」記録と外部作用の間には障害の隙間があるため、記録しただけで作用の一回性を保証しません。 たとえば発注APIが成功した直後にworkerが停止し、ackできなかった場合、メッセージは再配信される可能性があります。次のworkerは再発注を先に行わず、operation IDで外部の成立結果を照合します。既に成立なら記録を補って完了にし、不成立が確認できた場合だけ再試行します。照合できなければ結果不明のまま担当者へ渡します。timeoutを失敗と決めつけた再送が、二重発注を起こします。 ## FAILURE_AND_CONTROL | 失敗 | 制御 | 読み戻す証拠 | | --- | --- | --- | | worker停止で再配信 | operation単位の冪等性と結果照合 | 外部結果と処理記録の対応 | | 長い推論中にvisibility失効 | 作業単位を短くし、必要時に期限更新 | 更新失敗と二重workerの有無 | | 古いworkerが遅れて書込む | 対象版・世代を使う条件付き更新 | 新しい結果が上書きされないこと | | retryが外部障害を増幅 | 上限、backoff、jitter、受付制御 | 試行回数、429、待ち時間 | | 認可失敗を反復 | 永続失敗として隔離し責任者へ | 期限・権限の失敗原因 | | DLQへ移して放置 | owner、修正条件、再投入手順を定義 | 受領・解決・再投入結果 | ackは、どの状態まで永続化したら行うかを明示します。AIの文章が得られた時点、承認された時点、外部作用が確認された時点は異なります。実行前の計画作成と実行を別メッセージに分ける場合も、承認された計画hashと実際の入力が一致することを確認します。 ## BACKPRESSURE_AND_OBSERVABILITY キュー長だけでなく、最古の待機時間、到着率、実処理時間、再配信率、DLQ滞留、結果不明件数、外部APIの残り容量を観測します。高価な長文依頼と短い依頼を同じ一件として数えると容量を誤ります。token量、添付サイズ、必要なtool回数等を補助情報にし、受付と同時実行を制限します。 モデル・prompt・tool定義が変わった後の再生では、旧メッセージの入力と新しい実装が同じ意味で処理できるかを確認します。過去の承認を無条件に使い回しません。payloadに秘密情報を大量に入れず、権限と保存期間を管理できる原本参照を利用します。ログにもtokenや機密本文を無制限に複製しません。 ## LIMITATIONS_AND_OPEN_UNKNOWN 今回、実ブローカーへの負荷試験や外部APIの副作用試験は実施していません。製品別の配信モード・保持・quota・順序・トランザクション構成、実APIの冪等性、障害時の再配信率、組織固有の容量はUNKNOWNです。上の制御表は設計案であり、そのまま配置すれば一回性を保証する共通実装ではありません。原本の停止・取消と、すでに外部へ到達した作用の取消も分けます。 ## SAFE_WORDING 「非同期受付と再配信を前提に、対象構成で結果照合を実装・検証した」と表現します。「キューへ入ったので完了」「exactly-onceなので二重作用はない」とは記しません。Agentの成功報告を信用せず、業務側の結果をreadbackします。 ## SOURCES_AND_PROVENANCE - [S1] AWS, SQS at-least-once delivery. https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/standard-queues-at-least-once-delivery.html （2026-10-20確認、製品仕様） - [S2] AWS, SQS visibility timeout. https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html （同日確認、製品仕様） - [S3] Apache Kafka 4.2, Design / Message Delivery Semantics. https://kafka.apache.org/42/design/design/ （同日確認、OSS開発主体による設計説明） - 旧記録: R1R-004-EA0232、退避Doc 1Vd0BP7G2UyPDRQs_-8dPvTgQ78Tk6kcVGuMJjqNdr84 tab t.0:6543–7028。先行成果未発見という所在記録であり、完成調査として使用していません。旧candidate 1GqJI_GN42oCiWfC7AwTksmGO2vUPSd41は2026-10-20の実取得でmanifestなし・空payloadと確認。旧内容を推測せず、新identityで本記事を作成しました。 NEXT: /agent/start.json STOP: This is a knowledge projection, not an execution order.