BroadRouter

長時間動くエージェント:崩れないタイムアウト、リトライ、チェックポイント

BroadNet Inference チーム · 約 4 分で読めます · 公開日 · 更新日

モデル呼び出しは使い捨て、エージェントの状態は永続的と考えます。呼び出しごとにタイムアウトを設け、ストリーミングで停止を検知し、429・5xx・切れたストリームは上限付きバックオフで再試行し、副作用のあるツールに冪等キーを付けます。各ステップ後にメッセージ一覧を保存し、クラッシュ後は直前から再開します。

5 分で終わるエージェントなら失敗を無視できます。5 時間動くエージェントは、タイムアウト、429、途切れたストリーム、そしておそらく再起動にも遭遇します。長時間動くエージェントに関する解説の多くはワークフローエンジンを勧めますが、必要ないかもしれません。この記事では、素のエージェントループを何時間も動かし続けるための 5 つの習慣を、OpenAI Python SDK のコードとともに紹介します。

エージェントを何時間も動かすと何が壊れますか?

障害 見え方 対処する習慣
呼び出しが固まる、遅い 何分も応答がない 呼び出しごとのタイムアウト、ストリーミング
レート制限や過負荷 429、5xx バックオフ付きの上限あるリトライ
ストリームの切断 [DONE] の前に接続が終わる 不完全とみなし、呼び出しをリトライ
副作用の重複 リトライ後にツールが 2 回動く 冪等キー
プロセスのクラッシュやデプロイ エージェントがステップ 1 からやり直す ステップごとのチェックポイント

1. 1 回の呼び出しにどれくらい時間を許すべきですか?

OpenAI Python SDK の README によると、リクエストは既定で 10 分後にタイムアウトし、特定のエラーは 2 回リトライされます。エージェントでは、知らないうちに挙動が変わらないよう、どちらも自分で設定してください。

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"],
                timeout=300, max_retries=4)

タイムアウトはデータから決めます。1 日分、すべての呼び出しの所要時間を記録し、成功した呼び出しのうち最も遅いものより十分長く設定します。大きなプロンプトは出力が始まるまでに時間がかかり、推論モデルは書き始める前に考えます。毎秒約 100 トークン だと、8,000 出力トークンだけで 1 分以上かかります。止まらないループが一晩中走り続けないよう、タスクごとにも別途経過時間の予算を設けてください。

2. 長時間動くエージェントでなぜストリーミングするのですか?

ストリーミングは、モデルが作業している間に信号をくれます。ストリーミングなしでは、遅い呼び出しと死んだ接続は、タイムアウトが発火するまで見分けがつきません。ストリーミングがあれば、チャンクが届くのが見え、最後のチャンクでトークン使用量も得られます。

BroadNet のストリーミングのルール:文字どおりの data: [DONE] 行まで読みます。その前に接続が閉じたら、回答は不完全です。X-Request-ID を記録し、新しいリクエストを送るかどうかを判断します。ストリーミングの詳しいガイド。

def call_streaming(messages, tools=None):
    parts, done = [], False
    stream = client.chat.completions.create(
        model="broadnet/glm-5.3", messages=messages, tools=tools, stream=True,
        stream_options={"include_usage": True}, max_tokens=8000)
    for chunk in stream:
        if chunk.choices and chunk.choices[0].finish_reason:
            done = True
        if chunk.choices and chunk.choices[0].delta.content:
            parts.append(chunk.choices[0].delta.content)
    if not done:
        raise IncompleteStream()   # retry the whole call
    return "".join(parts)

このスケッチはテキストだけを集めます。ツール呼び出しをストリーミングする場合は、delta.tool_calls も index ごとに蓄積してください。

3. 何をリトライすべきですか?

SDK はすでに接続エラー、408、409、429、5xx をリトライします。不完全なストリームのように SDK から見えないものに対してだけ、自前のリトライを上に重ねてください。

  1. リトライする: 接続エラー、429、5xx、不完全なストリーム。ジッターと上限付きの指数バックオフを使います(例:最大 4 回)。
  2. リトライせず直す: 400、401、402、403、413、422。これらは毎回同じように失敗します。エラーコードとリトライすべき場合を参照してください。
  3. リトライの予算はタスク単位でも持つ。 呼び出し単位だけではありません。10 ステップがそれぞれ 4 回リトライすれば、40 回の余分な呼び出しになります。
  4. リトライを使い切ったらフェイルオーバーする。 プロバイダーの障害を乗り切らなければならない実行なら、接続エラー、5xx、レート制限による 429 を 2 つ目のプロバイダーに回します。LLM API のフェイルオーバーにクライアントコードとサーキットブレーカーがあります。

従量課金では、リトライのたびに新しい推論として再び課金されます。従量課金のキーは 1 分あたり 30 リクエスト、同時実行 4 までなので、リトライの嵐はすぐにレート制限に達します。エージェントにどれだけ余裕があるかはレート制限計算ツールでわかります。バックオフの詳細は 429 への対処の記事で扱っています。無制限プランではリトライに追加料金はかかりませんが、実行中はセッションの唯一のリクエスト枠を占有します。

4. ツール呼び出しを冪等にするには?

モデル呼び出しには副作用がありません。ツール呼び出しにはあり得ます。send_invoice が実行された後、ステップを保存する前にエージェントがクラッシュすると、再起動したエージェントはもう一度送ってしまいます。

副作用のある呼び出しには、タスクとステップから導いた冪等キーを付け、実行前に確認し、すでに記録されていれば呼び出しを飛ばします。

def run_side_effect(task_id, step, call, store):
    key = f"{task_id}:{step}:{call.id}"
    if store.done(key):
        return store.result(key)       # already ran: return the saved result
    result = execute(call)             # pass key to the API if it supports one
    store.save(key, result)
    return result

多くの決済 API やメッセージング API は冪等キーのヘッダーを受け付けます。対応している場合は、自分のキーをそのまま渡してください。

5. エージェントのチェックポイントはどう取りますか?

完了したステップごとに、メッセージ一覧、ステップ番号、副作用のキーを保存します。起動時には、最新のチェックポイントがあれば読み込みます。

def save_checkpoint(path, step, messages):
    tmp = path + ".tmp"
    with open(tmp, "w") as f:
        json.dump({"step": step, "messages": messages}, f)
    os.replace(tmp, path)   # atomic on the same filesystem

一時ファイルに書いてからリネームすれば、書き込み中にクラッシュしても中途半端なチェックポイントは残りません。非常に長いセッションでは、要約もチェックポイントに含めてください。古いやり取りを短い要約に置き換えれば、再開したエージェントが巨大な履歴を読み直さずに済みます。これで DeepSeek V4.1 Flash の 1,048,576 トークンであっても、コンテキストウィンドウの中に収まり続けます。

一晩動かす前のチェックリスト

  1. クライアントでタイムアウトと max_retries を明示的に設定した。
  2. include_usage 付きでストリーミングを有効にし、不完全なストリームはリトライする。
  3. タスクごとのリトライ予算と経過時間の上限がある。
  4. 書き込み、送信、支払いを行うすべてのツールに冪等キーがある。
  5. ステップごとにアトミックに書き込むチェックポイントがある。
  6. ステップ番号、所要時間、トークン数、X-Request-ID をログに残す。

複数のエージェントを並べて動かすなら、定額で並列のコーディングエージェントを動かすとマルチエージェント構成のコストも読んでください。

BroadNet Inference の位置づけ

BroadNet Inference は標準的な chat completions のストリーミングを使い、ログに残せる X-Request-ID ヘッダーを返し、どのエラーをリトライすべきかを文書化しているので、上のパターンはそのまま使えます。一日中動くエージェント向けには、無制限プランがセッションあたり月 $60 で DeepSeek V4.1 Flash のトークン計量をなくし、リトライが無料になります。ただし、Meteor の 1 時間は購入から 1 時間後に、Orbit の 1 週間は 7 日後に終わるので、長いジョブはその期間内に終えるか、更新される Full Moon のセッションに移す必要があります。プランは inference.broadnet.ai/plans にあります。

よくある質問

エージェントの LLM API 呼び出しのタイムアウトは何秒にすべきですか?

正当な呼び出しのうち最も遅いものが収まる長さで、固まった呼び出しを捕まえられる短さです。OpenAI Python SDK の既定は 10 分です。多くのエージェントはストリーミングを使って呼び出しごとに 2〜5 分とし、タスクごとに別途経過時間の上限を設けています。

エージェントがリトライすべき LLM API エラーはどれですか?

接続エラー、429、5xx は、ジッター付きの上限ある指数バックオフでリトライします。400、401、402、403、413、422 はリトライせずに原因を直してください。BroadNet では、失敗ごとに X-Request-ID ヘッダーも記録します。

chat completion をリトライしても安全ですか?

モデル呼び出し自体には副作用がないので安全ですが、新しい推論であり、従量課金では再び課金されます。危険なのはツールです。ツールが冪等キーを使っていなければ、リトライしたステップが同じメールを 2 回送ることがあります。

クラッシュ後にエージェントを再開するには?

完了したステップごとにメッセージ一覧とステップ番号を保存し、実行前に副作用の ID を書き込み、起動時に読み込みます。エージェントは最後に保存したステップから再開します。

長時間動くエージェントには無制限プランが必要ですか?

必要ではありませんが、従量課金ではリトライや長い文脈の費用が積み重なります。BroadNet の無制限プランでは DeepSeek V4.1 Flash にトークンの計量がないため、リトライに追加料金はかかりません。ただし各セッションは引き続き 1 度に 1 リクエストしか実行できません。

Markdown で読むChatGPT に聞くClaude に聞くPerplexity に聞く