未翻訳のページは英語で開き、英語と表示されます。
このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.
長時間のエージェント実行のトレースと再開
長時間の実行(300 個のファイルの処理、リポジトリのクロール、計画の実行)は、クラッシュ、コンテキストウィンドウの枯渇、デプロイ、一時停止などで途中で止まることがあります。実行の run_id をキーとするワーキングメモリのブロックが、進捗を ClickHouse に保持します。新しいプロセスはそれを読み戻し、最後に完了した作業単位から続行します。別個のチェックポイントストアは不要です。
パターン
- タスクに対して安定した
run_id(ジョブ id、計画 id など)を選びます。 - 作業単位ごとに
checkpoint(state, run_id=...)を呼びます。stateは新しいプロセスが続行するために必要なもの(完了した項目の id、カーソル、JSON 文字列など)です。 - 起動時に
resume(run_id=...)を呼びます。Noneは新規の実行を意味します。それ以外の場合は、チェックポイントが完了済みとしているものをスキップします。
flowchart LR
A["start: resume(run_id)"] -->|None| B[fresh run]
A -->|state| C[skip completed items]
B --> D[do one unit]
C --> D
D --> E["checkpoint(state, run_id)"]
E -->|more work| D
E -->|finished| F["delete('checkpoint', run_id)"]
Python SDK の場合
from loom import Agent
RUN = "reindex-catalog"
async def process(agent: Agent, items: list[str]) -> None:
done = set((await agent.working_memory.resume(run_id=RUN) or "").split())
for item in items:
if item in done:
continue
await do_work(item)
done.add(item)
await agent.working_memory.checkpoint(" ".join(sorted(done)), run_id=RUN)
checkpoint と resume は、ブロック checkpoint に対する working_memory.set と working_memory.get です(block_key= で変更できます)。checkpoint は呼ぶたびに前回の内容を上書きします。
Warning: デフォルトの
char_limitは 4,096 文字です(sdk/python/loom/working_memory.pyのDEFAULT_CHAR_LIMIT)。状態は小さく保つか、状態へのポインタを保存してください。大きなブロブはcontext.offloadに置き、そのblob_keyをチェックポイントに入れます。
タスクが完了したら、チェックポイントを削除します。
await agent.working_memory.delete("checkpoint", run_id=RUN)
1 つのスナップショットではなく進捗ログが必要な場合は、working_memory.append(..., run_id=RUN) でブロックに追記し、working_memory.render(run_id=RUN) でブロックを読み戻します。
MCP の場合
working_memory.set(loom_working_memory_set)は coding、atomic、all のツールセットに登録されており、readonly と assistant を除くその他のすべてのツールセットでは loom_op 経由で実行されます。working_memory.get はどのツールセット(all を含む)にも登録されていません。{"op": "working_memory.get", "arguments": {...}} を指定して loom_op から呼び出してください。エージェントは次のように動作します。
- 各ステップの後に、
run_idとblock_key="checkpoint"を指定してworking_memory.setを呼びます。 - 起動時に、同じ
run_idとblock_keyを指定してworking_memory.getを呼びます。
run_id が異なる 2 つの実行が、互いのチェックポイントを参照することはありません。
チェックポイントを保持するプレーン
| 状態 | プレーン | 理由 |
|---|---|---|
| 小さな再開用カーソル(完了した id、オフセット) | ワーキングメモリ | 正確なキーで読み戻される。ステップごとに上書きされる。埋め込みは行われない |
| 大きな部分結果やステップの出力 | context.offload ブロブ |
ブロックの上限を超える内容を summary と ttl_seconds 付きで保持する。context.fetch で読み取る |
| 実行が確立した主張 | memory.set |
永続的で、埋め込まれ、後の想起のためにランク付けされる |
調査エージェントガイドでは、あらゆる種類のエージェントの状態をそれぞれのプレーンに対応付けています。
実行内容のトレース
run.begin/run.completeは実行そのものを記録します。目標、ステータス、依存したメモリ(memories_used)、振り返りが対象です。run.getは、その実行が想起したキー、書き込んだメモリ、ターン、コストとともに実行を返します(実行)。- 実行が書き込んだメモリには、その
run_idが付きます。memory.search(run_id=...)でそれらに絞り込めます。 conversation.createとconversation.appendはrun_idを受け取るため、実行のトランスクリプトがそれに紐づきます(会話とセッション)。LOOM_SEARCH_TRACE_LOG_ENABLED=true(デフォルトはオフ)を設定すると、memory.search_trace_log(run_id=...)が、その実行が行ったすべての検索とその返却内容を一覧表示します(デバッグ)。
Loom はプロセス内の変数をスナップショットしません。チェックポイントが保持するのは、そこに入れたものだけです。
仕組み
loom.working_memory は、(org, namespace, agent, user_id, session_id, run_id, block_key) で並べられた ReplacingMergeTree(version) です。checkpoint を呼ぶたびに行の新しいバージョンが書き込まれ、読み取りは最新のものに集約されます。run_id はソートキーに含まれるため、2 つの実行は 2 つの行になります。