---
title: "長時間動く AI エージェント：タイムアウト・リトライ・チェックポイント | BroadRouter"
description: "LLM エージェントを何時間も動かし続けるために。呼び出しごとのタイムアウト、停止を検知するストリーミング、安全なリトライ、冪等なツール副作用、ステップごとのチェックポイント。"
url: https://broadrouter.com/ja/blog/long-running-agents-timeouts-retries/
lang: ja
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

このページは英語の原文を AI の支援を受けて翻訳したものです。[英語の原文を読む](https://broadrouter.com/blog/long-running-agents-timeouts-retries/)（2026-11-16 更新）。

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

BroadNet Inference チーム · 約 4 分で読めます · 公開日 2026-11-14 · 更新日 2026-11-16

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

## 要点

-   OpenAI Python SDK は既定で 10 分でタイムアウトし、2 回リトライします。エージェントではどちらも明示的に設定してください。
-   data \[DONE\] の前に終わったストリームは不完全な回答です。そのリトライは新しい推論であり、従量課金では再び課金されます。
-   モデル呼び出しは安全にリトライできます。ツールの副作用は、冪等キーがない限り安全ではありません。
-   完了したステップごとにチェックポイントを保存します。メッセージ一覧、ステップ番号、完了した副作用の ID です。
-   プランのセッションでは、リトライに追加料金はかかりませんが、実行中は唯一のリクエスト枠を占有します。

**このページの内容**

1.  エージェントを何時間も動かすと何が壊れますか？
2.  1\. 1 回の呼び出しにどれくらい時間を許すべきですか？
3.  2\. 長時間動くエージェントでなぜストリーミングするのですか？
4.  3\. 何をリトライすべきですか？
5.  4\. ツール呼び出しを冪等にするには？
6.  5\. エージェントのチェックポイントはどう取りますか？
7.  一晩動かす前のチェックリスト
8.  BroadNet Inference の位置づけ

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

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

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

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

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

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

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

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

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

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

```python
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、不完全なストリーム。ジッターと上限付きの[指数バックオフ](https://broadrouter.com/ja/glossary/exponential-backoff/)を使います（例：最大 4 回）。
2.  **リトライせず直す：** 400、401、402、403、413、422。これらは毎回同じように失敗します。[エラーコードとリトライすべき場合](https://broadrouter.com/ja/guides/errors-and-retries/)を参照してください。
3.  **リトライの予算はタスク単位でも持つ。** 呼び出し単位だけではありません。10 ステップがそれぞれ 4 回リトライすれば、40 回の余分な呼び出しになります。
4.  **リトライを使い切ったらフェイルオーバーする。** プロバイダーの障害を乗り切らなければならない実行なら、接続エラー、5xx、レート制限による 429 を 2 つ目のプロバイダーに回します。[LLM API のフェイルオーバー](https://broadrouter.com/ja/blog/llm-api-failover-fallback/)にクライアントコードとサーキットブレーカーがあります。

従量課金では、リトライのたびに新しい推論として再び課金されます。従量課金のキーは 1 分あたり 30 リクエスト、同時実行 4 までなので、リトライの嵐はすぐに[レート制限](https://broadrouter.com/ja/glossary/rate-limit/)に達します。エージェントにどれだけ余裕があるかは[レート制限計算ツール](https://broadrouter.com/tools/llm-rate-limit-calculator/)でわかります。バックオフの詳細は [429 への対処の記事](https://broadrouter.com/ja/blog/handle-llm-api-429-rate-limits/)で扱っています。[無制限プラン](https://broadrouter.com/ja/guides/unlimited-llm-api-sessions/)ではリトライに追加料金はかかりませんが、実行中はセッションの唯一のリクエスト枠を占有します。

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

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

副作用のある呼び出しには、タスクとステップから導いた[冪等キー](https://broadrouter.com/ja/glossary/idempotency-key/)を付け、実行前に確認し、すでに記録されていれば呼び出しを飛ばします。

```python
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\. エージェントのチェックポイントはどう取りますか？

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

```python
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](https://broadrouter.com/ja/models/deepseek-v4.1-flash/) の 1,048,576 トークンであっても、[コンテキストウィンドウ](https://broadrouter.com/ja/glossary/context-window/)の中に収まり続けます。

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

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

複数のエージェントを並べて動かすなら、[定額で並列のコーディングエージェントを動かす](https://broadrouter.com/ja/blog/run-parallel-coding-agents-flat-rate/)と[マルチエージェント構成のコスト](https://broadrouter.com/ja/blog/multi-agent-cost/)も読んでください。

## 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](https://inference.broadnet.ai/plans?utm_source=broadrouter&utm_medium=referral&utm_campaign=ja-blog-long-running-agents-timeouts-retries&utm_content=body) にあります。

関連する無料ツール（英語）

-   [Agent run cost estimator](https://broadrouter.com/tools/agent-run-cost-estimator/) Context growth per step, total tokens and cost of one agent run, with a DeepSeek session comparison.
-   [LLM batch job planner](https://broadrouter.com/tools/llm-batch-job-planner/) Run time, binding limit, cost per model and the flat sessions needed to finish a big job by a deadline.
-   [Flat-rate vs per-token LLM cost calculator](https://broadrouter.com/tools/flat-rate-vs-per-token-calculator/) Break-even between an unlimited plan and paying per token, per agent.
-   [LLM rate limit and concurrency calculator](https://broadrouter.com/tools/llm-rate-limit-calculator/) Which limit binds first: RPM, TPM or concurrency, with Little's law.

[無料ツール（英語）](https://broadrouter.com/tools/)

## この記事の用語

[AI エージェント（AI agent）](https://broadrouter.com/ja/glossary/agent/)

AI エージェントとは、言語モデルが目標に向けて自分で手順を決めるシステムです。どのツールを呼ぶかを決め、結果を読み、最終回答を出すか上限に達するまで繰り返します。決まった箇所でモデルを呼ぶ固定のスクリプトは、ふつうワークフローと呼ばれます。

[トークン（token）](https://broadrouter.com/ja/glossary/token/)

トークンとは、言語モデルが読み書きするテキストの単位です。モデルのトークナイザーが作る単語、単語の一部、句読点、バイト列のいずれかにあたります。LLM API は利用量をトークンで数え、上限を設け、通常はトークン単位で課金します。

[リクエストタイムアウト（request timeout）](https://broadrouter.com/ja/glossary/request-timeout/)

リクエストタイムアウト（request timeout）とは、HTTP クライアントがサーバーを待つ最長時間で、超えるとリクエストを諦めます。通常は接続タイムアウトと読み取りタイムアウトに分かれます。長い回答には時間がかかるため、LLM では読み取りタイムアウトを長めにします。

[レート制限（rate limit）](https://broadrouter.com/ja/glossary/rate-limit/)

レート制限とは、1 分あたりのリクエスト数やトークン数など、一定時間内にクライアントが API を使える量に API 側が設ける上限です。上限を超えたリクエストは、使用量が下回るまで通常 HTTP 429 Too Many Requests で拒否されます。

[指数バックオフ（exponential backoff）](https://broadrouter.com/ja/glossary/exponential-backoff/)

指数バックオフ（exponential backoff）とは、失敗するたびに待ち時間を長くして再試行するリトライ戦略で、通常は上限まで遅延を 2 倍ずつ増やします。各待ち時間にランダムなジッターを加えると、多数のクライアントの再試行が分散し、同時にサーバーへ集中しなくなります。

[冪等キー（idempotency key）](https://broadrouter.com/ja/glossary/idempotency-key/)

冪等キーとは、決済や購入など状態を変えるリクエストにクライアントが付ける一意の値で、通常は UUID などのランダムな ID です。同じキーで同じリクエストが再送されると、サーバーは処理を 2 回実行せず、最初の結果を返します。

[ストリーミング（streaming）](https://broadrouter.com/ja/glossary/streaming/)

ストリーミングとは、言語モデルの応答を最後にまとめて返すのではなく、生成中に小さなチャンクに分けて返す方式です。OpenAI 互換 API では、リクエストで stream を true にすると Server-Sent Events（SSE）でストリーミングされます。

[モデルフォールバック（model fallback）](https://broadrouter.com/ja/glossary/model-fallback/)

モデルフォールバックとは、失敗した LLM リクエストを順序付きリストの別のモデルやプロバイダーで再試行する手法です。きっかけはエラー、レート制限、コンテキスト長エラー、ポリシーによる拒否などで、クライアントか前段のゲートウェイで実行します。

## よくある質問

### エージェントの 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 リクエストしか実行できません。

## 続けて読む

-   [オープンモデルのツール呼び出し：スキーマ、並列呼び出し、リトライ](https://broadrouter.com/ja/blog/tool-calling-open-models/)
-   [マルチエージェント構成の本当のコスト：トークン課金 vs 定額セッション](https://broadrouter.com/ja/blog/multi-agent-cost/)
-   [定額の LLM API で並列コーディングエージェントを動かす方法](https://broadrouter.com/ja/blog/run-parallel-coding-agents-flat-rate/)
-   [LLM API プランの「無制限」は本当は何を意味するのか](https://broadrouter.com/ja/blog/what-unlimited-llm-api-really-means/)
-   [LLM API のフェイルオーバー：自前のコードで別プロバイダーへ切り替える](https://broadrouter.com/ja/blog/llm-api-failover-fallback/)
-   [AI コーディングエージェント 1 回の実行コスト：ステップ数、コンテキストの増加、キャッシュ](https://broadrouter.com/ja/blog/ai-coding-agent-run-cost/)
-   [Claude Code でオープンモデルを使う：プロキシ、ネイティブエンドポイント、制限](https://broadrouter.com/ja/blog/claude-code-with-openai-compatible-models/)
-   [ガイド：BroadNet Inference のエラーコードとリトライすべき場合](https://broadrouter.com/ja/guides/errors-and-retries/)
-   [ガイド：chat completions のストリーミングと接続切断への対処](https://broadrouter.com/ja/guides/streaming-chat-completions/)
-   [ガイド：エージェント向け無制限 LLM API プランのしくみ](https://broadrouter.com/ja/guides/unlimited-llm-api-sessions/)
-   [ガイド：OpenAI Python SDK を BroadNet Inference で使う](https://broadrouter.com/ja/guides/openai-python-sdk/)

実際のワークロードで試してください。新規アカウントには US$5 の初回クレジットがあり、Gemma、文字起こし に使えます。DeepSeek、GLM、Qwen3.8 はチャージが必要です。

[始める](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ja-blog-long-running-agents-timeouts-retries&utm_content=page-cta) ·

**出典**

-   [OpenAI Python SDK README：リトライとタイムアウト（2026-11-14 確認）](https://github.com/openai/openai-python)
-   [BroadNet Inference API リファレンス：エラーとリトライ（英語）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ja-blog-long-running-agents-timeouts-retries&utm_content=sources#errors)
-   [BroadNet Inference API リファレンス：ストリーミングと制限（英語）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ja-blog-long-running-agents-timeouts-retries&utm_content=sources#requests)
-   [BroadNet Inference 無制限プラン（英語）](https://inference.broadnet.ai/plans?utm_source=broadrouter&utm_medium=referral&utm_campaign=ja-blog-long-running-agents-timeouts-retries&utm_content=sources)
