# AIエージェントをソフトウェアに組み込むプラクティス # Deadline & Budget Cascade｜期限・予算のカスケード伝播 🎯 エージェントが再帰的にサブタスクを生成して、気づけばコストが数十ドルに。「請求事故」を構造的に防ぐ方法があります。 全体の予算と期限を末端ノードまで伝播させれば、各ノードが自分で打ち切り判断できます。 🔥 解決する課題 エージェントの呼出ツリーが深くなると、各ノードは自分がどれだけのリソースを消費してよいか分かりません。高コストなLLM呼び出しが再帰的に積み重なり、請求事故が起きます。計画-反省の自己ループでは、改善の見込みが薄くても無限にリトライを繰り返しえます。根本原因は「全体の予算と期限がローカルな判断に伝わっていない」ことです。 💡 提案パターン Deadline & Budget Cascade（期限・予算のカスケード伝播）は、呼出ツリーのルートでdeadline（期限）とbudget（トークン・コスト・ステップ数の上限）を設定し、子タスクへ委譲するたびに残り枠を差し引いて伝播します。どの末端ノードでも「今の自分に残された時間・コスト」を知っており、枠を使い切る前に縮退・中断・部分結果返却に切り替えられます。deadlineは相対秒でなく絶対時刻で渡し、伝播時のズレを防ぎます。 ✅ 選定条件 使うとき： - エージェントがサブタスクを再帰的に生成、または複数ワーカーに並列委譲する - 1リクエストのコストが予測困難で、上限を置かないと請求事故が起きうる - タスク完了にSLAや期待値がある 使わないとき： - 呼出ツリーが1段で完結し、タイムアウトだけで十分な場合 - バッチジョブなど時間制約がなくコストも固定的な場合 ⚠️ 落とし穴 - deadlineは絶対時刻で渡すこと。相対秒を渡すと伝播のたびにズレが蓄積します（gRPCのgrpc-timeoutと同じ原則） - 子に全予算を渡さず、予備枠（10〜20%）を親に残すこと。子の結果を集約・フォーマットする時間とコストが必要です - 枯渇時の振る舞い（部分結果返却・人間エスカレーション・縮退モデル切替）を事前に決めておくこと。タイムアウト例外を投げるだけではUXが崩壊します 🔧 実装方針 - BudgetContextデータクラスにdeadline_at（絶対時刻）・max_cost_usd・max_steps・max_tokens・depth・max_depthを持たせ、呼出ツリーのルートで初期値を設定します - 子タスクへの委譲時にchild_budgetメソッドで残り枠からfractionを掛けて分配し、伝播マージン（概ね2秒）を差し引きます。予備枠としてルート予算の10〜20%を親に残します - 各ノードはis_exhaustedで残時間・残コスト・残ステップを確認し、枠を使い切る前に縮退・中断・部分結果返却に切り替えます - 並列子タスクではコストは各子の合算、deadlineは最も遅い子で決まることに注意し、分配比率は子タスクの重要度と予測コストで按分します - 予算消費率（consumed/limit比）をメトリクスとして観測し、閾値超過時にアラートを発火させる仕組みを組み込みます #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # Adaptive Timeout & Budget-Bounded Retry｜適応タイムアウト＋予算律速リトライ 🎯 リトライ3回で固定していませんか？LLMリトライ1回で数千トークン消費する世界では、回数でなく予算で律速すべきです。 固定タイムアウト・固定回数リトライは、エージェント時代のエラー処理には力不足です。 🔥 解決する課題 エージェント実行ではツール呼び出し（数秒）とLLM推論（数十秒〜分）でレイテンシ特性が全く異なります。同じタイムアウトで括ると、前者は待ちすぎ・後者は早すぎで切れます。さらに固定3回リトライでも、LLMリトライは1回あたり数千トークンを消費して予算を突き破りえます。429（レート制限）とスキーマ不適合を同じリトライで処理しても、後者は同じプロンプトでは直りません。 💡 提案パターン Adaptive Timeout & Budget-Bounded Retry（適応タイムアウト＋予算律速リトライ）は、操作クラス（ツール呼び出し・LLM推論・セッション全体）ごとにタイムアウトを分けます。リトライは固定回数でなく残りトークン予算で打ち切ります。エラーを一時障害・コンテンツ起因・コンテキスト長超過の3種に分類し、それぞれ指数バックオフ・self-correction・要約分割と対応戦略を切り替えます。予算を一定割合消費したら縮退（軽量モデルへのフォールバック）に移行し、尽きたらfail-fastで停止します。 ✅ 選定条件 使うとき： - LLM・ツール・外部APIなどレイテンシ特性の異なる操作を組み合わせている - リトライ1回あたりのコストが無視できない（LLM推論を含む） - ネットワーク一時障害とコンテンツ起因エラーの両方が発生しうる 使わないとき： - 単発LLM呼び出しのみで固定タイムアウトで十分な場合 - 非冪等な書込のみでリトライ自体が禁止される環境 ⚠️ 落とし穴 - 429応答のRetry-Afterヘッダを無視して自前バックオフだけで攻めると、プロバイダ側でさらに絞られます。必ずRetry-Afterを尊重してください - 非冪等書込のリトライには冪等キーが必須です。冪等キー無しのリトライは二重実行を招きます - self-correctionでエラー文をそのまま詰めすぎるとコンテキストが膨張してコンテキスト長超過に遷移します。エラー要約は200トークン以内に切り詰めましょう 🔧 実装方針 - タイムアウトを操作クラス別に定義します。ツール呼び出しは概ね10〜30秒、LLM推論は全体60〜120秒（ストリーミング時はトークン間5〜15秒）、セッション全体はdeadlineで律速します - エラーを3種に分類し、一時障害（429/5xx/timeout）は指数バックオフ＋ジッタで再送、コンテンツ起因（スキーマ不適合等）はエラー要約をコンテキストに追加してself-correction、コンテキスト長超過は要約・分割で対処します - リトライ上限は固定回数でなく残りトークン予算で判定します。一時障害は予算の90%まで、self-correctionは70%までを上限とします - プロバイダごとに独立したサーキットブレーカ（Closed/Open/Half-Open）を設置し、連続失敗が閾値に達したら遮断して縮退ラダー（軽量モデル→キャッシュ応答→静的フォールバック→fail-fast）を降ります - 全プロバイダが共通インターフェースを実装するプロバイダ抽象化層を設け、フォールバック先の切り替えを呼び出し元に対して透過的にします #AIエージェント# #ソフトウェアアーキテクチャ#

greencloudvps 年額$15 VPS さらに１台追加契約したよ Budget KVM Sale 2048MB RAM 20GB NVMe RAID-10 Hard drive 1 core @ EPYC Rome CPU 1 IPv4 /64 IPv6 2TB Bandwidth 10Gbps Port Linux OS Phoenix, AZ Location で年払い$15は激安 #VPS# #仮想専用サーバー#

# Claude Agent SDKの便利で実践的な使い方 🎛 エージェントの暴走が心配ですか？ターン数・予算・努力レベルで実行を細かく制御できます。 ループ実行の制御（ターン・予算・努力レベル）は、`max_turns`・`max_budget_usd`・`effort` でエージェントの実行範囲を制限し、コストとレイテンシを最適化する機能です。 📌 タイトル：ループの実行方法を制御する 🔗 URL： 🧩 概要 `max_turns` でツール呼び出し回数の上限、`max_budget_usd` で実行コストの上限、`effort` でモデルの思考の深さを設定します。オープンエンドな指示でも予算上限で安全に打ち切れます。 🛠 使い方 `query()` のオプションに `max_turns=30`、`max_budget_usd=1.0`、`effort="medium"` を設定します。`model="claude-sonnet-4-6"` でモデルを明示指定できます。 🏗 実践的な使い方 ・本番エージェントの暴走防止に `max_turns=30` と `max_budget_usd=1.0` を設定します。「このコードベースを改善して」のようなオープンエンドな指示でも安全に打ち切れます。 ・`effort` を `low`（ファイル検索・一覧）/ `medium`（定型編集）/ `high`（リファクタ・デバッグ）/ `xhigh`（Opus 4.7 推奨のエージェンティックコーディング）/ `max`（多段問題の深い分析）と使い分けます。 ・小型・高速モデルが必要なサブタスクには `model="claude-sonnet-4-6"` を明示指定し、コスト効率を上げます。 💡 ユースケース 🛡 オープンエンドなタスクの安全な予算制限 ⚡ タスク難度に応じた effort レベルの最適化 💰 サブタスクへの軽量モデル適用によるコスト削減 ⚠️ 注意点 `max_turns` を超過すると `error_max_turns` で終了します。`resume` で上限を上げて再開可能です。`effort` は `xhigh` 以上で Opus 4.7 が推奨されます。 #ClaudeAgentSDK# #AI#