# AIエージェント開発の意思決定ポイント # タイムアウト｜Timeout 🎯 ポイント 「全部30秒」のタイムアウト、まだ使っていませんか？ AIエージェントでは、ツール呼び出しは数秒、LLM推論は数十秒、セッション全体は数十分。レイテンシ特性が全く異なる操作が組み合わさるため、一律のタイムアウトでは機能しません。層ごとに分けるのが第一歩です。 📋 概要 タイムアウトは、エージェントが特定の操作の完了を待つ最大時間を制御するダイヤルです。従来のWebサービスではHTTPリクエストに30秒程度を設ければ済みましたが、AIエージェントでは1リクエストが長く、レイテンシのばらつきが大きく、プロバイダの可用性も不安定です。 タイムアウトが短すぎると一時的な遅延で正常な処理を殺し、長すぎると障害を隠蔽してリソースを無駄に占有します。操作クラスごとにタイムアウトを分け、さらに観測データに基づいて動的に調整する仕組みが理想です。 🔍 意思決定のポイント タイムアウトの値はlatency_budget（ユーザーや下流システムがどれだけ待てるか）を最も強く反映します。少なくとも3層に分けて設定するのが基本です 📐 1. ツール呼び出し層 — 外部API・DB・ファイル操作。ツール種別ごとにさらに細分化も 2. LLM推論層 — 入力トークン数とモデル負荷で大きく変動。小型/大型モデルで応答時間が10倍異なることも 3. セッション全体層 — 「ユーザーがこのタスクに何分待てるか」から逆算 各操作のP99（99パーセンタイル）を観測し、安全係数1.5〜2.0倍を掛けた値が出発点です。P99がまだない立ち上げ初期は目安値から始め、1〜2週間の運用データで切り替えます。 💡 要点と詳細 目安値 📊 - ツール呼び出し（一般） → 10〜30秒。DBクエリは5秒でも長い場合あり - LLM推論（全体） → 60〜120秒。長文生成タスクは上限引き上げ - LLM推論（トークン間） → 5〜15秒。ストリーミング時のプロバイダ障害早期検出に有効 - LLM推論（TTFT） → 15〜30秒。入力が長いほど延びる - セッション全体 → 数分〜数十分。対話型は短く、調査・分析型は長く ストリーミングを使う場合は、全体タイムアウトよりトークン間タイムアウトの方が本質的な監視指標です 🔍 正常な推論では数百ミリ秒〜数秒間隔でトークンが返るため、15秒の無応答はプロバイダ側の異常を強く示唆します。 ⚖️ トレードオフ タイムアウトが短すぎると、複雑な推論タスクでLLMが高品質な回答を生成している途中で処理が中断されます ⏱️ Chain of Thoughtが深くなる正当なケースや、大量コンテキストの入力処理中にタイムアウトすることも。ピーク時のプロバイダ遅延で断続的に失敗し、リトライの連鎖が始まります。 タイムアウトが長すぎると、プロバイダが応答しないまま数分間スレッドが占有され、他のリクエストが詰まります 🚫 ハングしたツール呼び出しが放置され、ユーザーは「いつ終わるか分からない」最も苦痛な状態に。障害の検出も遅れます。 タイムアウト値の変更はリトライ戦略に直結します。短くすれば発火頻度が上がり、リトライが増えます。リトライ予算やセッション全体の予算と一体で調整する必要があります。 🛠️ ユースケース 対話型チャットアシスタント 💬 ユーザーが数秒以内の応答を期待。ツール3〜5秒、LLM推論15〜30秒（ストリーミングで即座にトークンを返し始める）、セッション全体60〜120秒。体感レイテンシの短縮にストリーミングが効果的です。 調査・分析エージェント 🔬 数分の処理が許容される。ツール10〜60秒、LLM推論60〜180秒、セッション全体5〜30分。タイムアウトよりコスト・ステップ数の予算が主要な制約に。 自動コードレビューエージェント 💻 大きな差分では入力トークンが数万に達し、TTFTが延びる。入力トークン数に応じてTTFTタイムアウトを動的に調整する仕組みが有効です。 タイムアウトとキャンセルは異なります ⚠️ タイムアウトはクライアント側で待つのを止めるだけで、プロバイダ側の処理は続行されている可能性があります。課金はプロバイダ側の処理量に基づくため、キャンセルリクエストも送信することを推奨します。 #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # Synchronous Edge Agent｜同期エッジ 🎯 キャッチーなメッセージ LLMエージェント、まず「同期で返せないか？」を考えていますか？ 非同期キューやチェックポイントに飛びつく前に、シンプルな同期HTTPで完結できないか検討しましょう。実際のユースケースの大半は、それで十分です。 🔥 解決する課題 エージェントアーキテクチャの議論はすぐに非同期キュー・チェックポイント・オーケストレータへ進みがちです。しかし多くのタスクは「LLM1回＋軽いツール」で済みます。軽量タスクに重い実行基盤を持ち込むと、運用コスト・デプロイ複雑性・デバッグ難度が不必要に跳ね上がります。 💡 提案パターン Synchronous Edge Agent（同期エッジ）は、単発のLLM推論と軽量ツール0〜2回を1つの同期HTTPリクエスト内で完結させる、最もシンプルな実行方式です。状態はインコンテキストのみで、チェックポイントもキューも不要です。テキスト分類・情報抽出・単純Q&A・要約・構造化出力生成など「数秒で終わる確実な処理」に最適です。タイムアウトはLLM呼び出し単位でp99実測値に基づいて設定し、モデル選択もレイテンシ予算の関数として決定します。迷ったらまずここから始めてください。 ✅ 選定条件 使うとき： - 処理が概ね5〜10秒以内に終わる（対面）、またはAPI連携で30秒以内 - LLM呼び出しは1回、ツール呼び出しは0〜2回の軽量処理 - 途中再開や人間承認が不要 使わないとき： - 処理が30秒を超えうる、または所要時間が読めない場合 - 複数ツールの多段呼び出しや計画・反省ループが必要な場合 - 不可逆な副作用（決済・データ削除等）を伴う場合 ⚠️ 落とし穴 - タイムアウトはHTTPサーバ全体でなくLLM呼び出し単位で設定すること。全体タイムアウトだけではLLMがハングしてワーカースレッドを占有し続けます - 同期枠内でのリトライは0〜1回に限ること。リトライを重ねるとクライアントが先にタイムアウトします - サーバーレス環境ではコールドスタートがレイテンシ予算を食うため、Provisioned Concurrencyやウォームアップで対処が必要です 🔧 実装方針 - クライアントからのHTTPリクエストをAPI Gateway経由でハンドラが受け取り、1つのリクエスト-レスポンスサイクル内で処理を完結させます。外部キューやチェックポイントストアは登場しません - タイムアウトはHTTPサーバ全体ではなくLLM呼び出し単位で設定し、その値はlatency_budgetから導出します。p95/p99の実測値に基づいて調整します - モデル選択もレイテンシ予算の関数として決定します。分類・抽出には軽量モデル、生成にはミッド〜フラグシップを選びます - 構造化出力（JSON Schema等）を使い、レスポンスの軽量検証を常にONにします。意味検証はレイテンシに余裕がある場合のみ追加します - 対面UIで生成が長文になる場合はSSEストリーミングを併用し、体感レイテンシを短縮します #AIエージェント# #ソフトウェアアーキテクチャ#