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 から見えないものに対してだけ、自前のリトライを上に重ねてください。
- リトライする: 接続エラー、429、5xx、不完全なストリーム。ジッターと上限付きの指数バックオフを使います(例:最大 4 回)。
- リトライせず直す: 400、401、402、403、413、422。これらは毎回同じように失敗します。エラーコードとリトライすべき場合を参照してください。
- リトライの予算はタスク単位でも持つ。 呼び出し単位だけではありません。10 ステップがそれぞれ 4 回リトライすれば、40 回の余分な呼び出しになります。
- リトライを使い切ったらフェイルオーバーする。 プロバイダーの障害を乗り切らなければならない実行なら、接続エラー、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 トークンであっても、コンテキストウィンドウの中に収まり続けます。
一晩動かす前のチェックリスト
- クライアントでタイムアウトと
max_retriesを明示的に設定した。 include_usage付きでストリーミングを有効にし、不完全なストリームはリトライする。- タスクごとのリトライ予算と経過時間の上限がある。
- 書き込み、送信、支払いを行うすべてのツールに冪等キーがある。
- ステップごとにアトミックに書き込むチェックポイントがある。
- ステップ番号、所要時間、トークン数、
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 にあります。
