コンテンツにスキップ

未翻訳のページは英語で開き、英語と表示されます。

このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.

実行(Runs)

run とは、「issue 1234 をトリアージする」のような、タスクを 1 回実行することです。run.begin が run を開いて run_id を返します。エージェントはその id を書き込み(memory.set、memory.update、observe.record)に渡します。run.complete は、ステータス、エージェントが依拠したメモリ、および任意でリフレクションを指定して run を閉じます。読み取り(memory.search、memory.ask)でボディに run_id を指定すると、その run 自身の行に絞り込まれます。そのため、読み取りには別の方法でラベルを付けます。HTTP では X-Loom-Run-Id ヘッダー(Python SDK では run_scope)、MCP ではセッション自身の run を使います。成功した run が依拠したメモリは次回以降のランキングで上位になり、失敗した run が依拠したメモリは、それまでに得たブーストを失います。

run が記録する内容

run の行は loom.agent_runs に保存されます。run.get が表示する内容の大半は、読み取り時に他のプレーンから導出されます。

フィールド 保存または導出 ソース
goal, user_request, model, … 保存 run.begin
status, final_response 保存 run.complete(それまでは active)
memories_used 保存 run.complete:エージェント自身が、何に依拠したかを申告した内容
grade, grade_source, … 保存 run.grade(run の終了後)
memories_written 導出 run の run_id を持つ loom.memory の行
recalled, recalled_keys 導出 run_id に紐づく検索トレースログと、run.complete(recalled_keys) の和集合
observations 導出 run_id が付与された、observe.record によるエピソード行
turns, cost_usd 導出 run が開いている間に行われたセッションのターンで、loom.agent_turn_usage にあるもの(Claude Code プラグイン、または cost.record_turns を使うエージェントが書き込みます)
budget_usd, budget_seconds 保存 run.begin(0 = 予算なし)
elapsed_seconds, over_budget 導出 run の開始から終了(または現在)までを、サーバーの時計で計測した値と cost_usd を、予算と比較して求めます

LOOM_SEARCH_TRACE_LOG_ENABLED が無効で、recalled_keys も送信されていない場合、recalled は -1 になります。

予算

run.begin は、任意の budget_usd(モデルの支出)と budget_seconds(run にかけてよい時間)を受け取ります。run.get はこれらを cost_usd および elapsed_seconds と比較し、超過したものを over_budget(cost、time、またはその両方)に列挙します。Loom はエージェントを実行しないため、予算は実行する側へのシグナルであり、停止させるものではありません。

run の支出は、その run が開いていた間にセッションで行われたターンを、各ターン自身の時刻(トランスクリプト由来の turn_at)で集計したものです。そのため budget_usd には session_id が必要です(ない場合は 422)。コストと同様に小数点以下 6 桁で保持されるので、最小値は $0.000001 です。時間は、クライアントが報告した duration_ms に関係なく、サーバーの時計で run の開始から終了までを測ります。予算は run の最初の run.begin で設定してください。

セッションで予算超過のアクティブな run を最初に見つけた run.get は、メンターヒント run_over_budget も返します。プラグインはこれをアドバイスとしてモデルに渡します。終了した run でも over_budget は報告されますが、ヒントは付きません。他のメンターヒントと同様、ヒントはセッションごとに 1 回だけ伝えられ、セッションを送らない呼び出し元(SDK、素の HTTP)は名前空間とウェブプロセスごとに 1 つのセッションを共有します。そのため、判断にはヒントではなく over_budget を使ってください。

制限事項:

  • プロンプトの合間のみ。 Claude Code プラグインはプロンプトのターンをそのプロンプトの終了時に送信するため(エージェントは cost.record_turns で自分で送信することもできます)、コスト予算はプロンプトの合間にチェックされ、単一のヘッドレスプロンプト(claude -p)の支出は終了後にしか表示されません。それらのターンは、エージェント自身の run.complete の後に届いた場合でも集計されます。呼び出しのコストは戻った後にしか分からないため、run は何かが気づく前に、最後のターンのコスト分だけ budget_usd を超えることがあります。
  • クライアントの時計。 この集計ウィンドウは、クライアント側のターン時刻とサーバー側の run 時刻を比較します。時計が数分ずれていると、run の境界付近のターンが誤った run に割り当てられます。ターンは送信時の時刻を保持するため、再送されたターンは最初に属した run に残ります。時刻なし(または解析できない時刻)で送られたターンは、その message_id が記録された時刻、新規であれば現在時刻になります。最初の送信から一瞬のうちに再送した場合は、現在時刻として記録されることがあります。cost.record_turns は、サーバーの時計より 5 秒を超えて先の時刻を持つ受信ターンを turns_dated_ahead として返すため、自分でターンを送る呼び出し元は時計の進みに気づけます。Claude Code プラグインは応答を読まずにターンを送信します。
  • 1 つのセッションに複数の run。 同じセッションで同時に開いている run は同じターンを参照します。入れ子の run は両方に計上され、コスト予算を必要とする並行ワーカーには、それぞれ専用のセッションが必要です。
  • 価格未設定のモデル。 価格表にないモデルのターンのコストは 0 です。run.get はそれらを unpriced_turns で数え、budget_usd には計上しません。
  • MCP。 MCP ツールが提供するのは budget_seconds のみです。モデルは、ターンが記録されるセッション ID を知らないためです。
  • リトライ。 再送された run.begin は、他のリトライと同様に run の行を置き換えます。再指定されなかったセッションと予算は保持され、0 以外の新しい予算は古いものを置き換え、0 は既存の値を保持します。新しい budget_usd は session_id と一緒に送る必要があります(ない場合は 422)。新しい budget_seconds には他に何も必要ありません。run を別のセッションに移す再送 begin は、古いセッションのターン用に設定されたコスト予算を破棄し、時間予算は保持して、その旨を next で伝えます。予算が削除されるのはこの場合だけです。run.begin が送ったものと異なる run_id を返した場合は、その run_id か同じ session_id で再送してください。そうしないと、リトライは新しい run を開きます。

取得されたことは、依拠されたことを意味しない

run.complete では 2 つのリストが送られます。

  • memories_used — エージェントが実際に依拠したキーです。各キーには used 使用イベントが記録され、結果が肯定的な場合は evidence イベント、否定的な場合は harm イベントも記録されます。outcome の既定値は status から決まります。completed は肯定的、failed は否定的、cancelled はどちらでもありません。
  • recalled_keys — 実行中に Loom のツールが返したキーです(Claude Code と Codex のプラグインが loom_search と memory.get の結果から収集して保持し、セッション終了時に送信します)。これらは run.get のために記録されるだけで、評価の対象にはなりません。

返されたものの使われなかった行は何も得ません。検索でヒットしたすべての行を評価すると、上位に表示されたものが無条件に優遇されてしまうためです。usage_fold ワーカーは、これらのイベントを強化項にまとめます。この強化項はメモリ検索の順位付けに使われます。harm イベントは獲得済みのブーストを取り消しますが、その行の書き込み時の基準値が下限となります。そのため、1 回の不適切な実行によって行が本来の関連度を下回ることも、削除されることもありません。

memories_used に指定されたプロシージャのキーには、プロシージャ台帳にも行が追加されます(パスは空で、ok は outcome から決まります)。エージェント自身が procedure.record_run を呼び出す場合は、実行が二重に数えられないよう、そのキーを memories_used に含めないでください。詳しくはプロシージャと学習内容を参照してください。

リフレクション

run.complete(reflection=...) は、what_worked、what_failed、assumptions、lessons、improvements(それぞれ最大 20 項目)、confidence、そして教訓の根拠となる evidence キーを記録します。リフレクションは reflection:<run_id> というキーで、タイプ reflection の 1 件のメモリとして保存されます。

  • 埋め込みが作成されるため、後続の実行は memory.search(memory_type="reflection") で見つけられます。ただし、フィルタなしの検索や memory.ask の対象からは除外されます。
  • what_failed と lessons には、少なくとも 1 つの evidence キーが必要です(指定がない場合は 422 になります)。
  • expires_in_days(デフォルトは 90、0 は無期限)が経過すると失効します。ただし、memory.verify または肯定的な結果によって更新された場合は失効しません。
  • role(planner、executor、critic、または独自の名前)を指定して開始した実行は、リフレクションに role:<role> タグを付けます。これにより、同じロールのエージェントが memory.search(role=...) を実行したときに、そのリフレクションが優先されます。

実行が書き込んだ行はどうなるか

run.complete の retain は、その実行(run)の下で書き込まれたメモリの扱いを決めます。

retain 効果
keep (default) 何も変更されません。
demote 信頼度がその時点で下げられます。
expire LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS 日後(デフォルトは 7)を有効期限として on_expire=demote とともに設定し、memory_expiry_sweep ワーカーがそれを適用します。

ピン留め済み、検証済み、昇格済み、ロック済み、エピソード、リフレクションの各行は、どのモードでも保持されます。また、どのモードでも行が論理削除(tombstone)されることはありません。デフォルト値は LOOM_MEMORY_RUN_COMPLETE_RETAIN で決まります。MCP セッションの暗黙の run は常に keep になります。これは、run を閉じるトランスポートが作業内容を判断できないためです。

評価付きの run

status は run が終了したことを示し、評価(grade)はその結果が妥当だったかどうかを示します。評価は、CI が通ったときやレビュアーがプルリクエストを却下したときなど、数日後に付くことがよくあります。run.grade は grade(pass または fail)、source(maintainer、ci、reviewer など、自由なテキスト)、reason、ref(URL、finding key、check run id)を受け取り、1 つの run_id、または 1 つの session_id(たとえば pr_1234)に属するすべての終了済み run を対象にします。再評価すると判定は置き換わります。同じ source からの同じ判定では何も変わりません。アクティブな run は対象外です。

評価付きの run の memories_used に含まれるメモリは、すべてその評価に対して集計されます。この集計値が、memory.proposals で試用中の各ファクト(memory.set(proposed=true) の行)の横に表示されます。Loom が集計値に基づいて提案を決定するのは、名前空間の所有者が proposal_policy.mode を auto に設定した場合だけです。どちらのモードでも、書き込み権限を持つ任意のエージェントが memory.proposal_decide で決定できます。メモリの書き込みを参照してください。

run.list(grade="ungraded") は、まだ判定が付いていない終了済みの run を一覧します。

MCP セッションには、要求しなくても暗黙の run が付きます。最初の run スコープのツール呼び出しで run が開始され、DELETE /mcp または mcp_session_run_sweep ワーカーがそれを閉じます(MCPを参照)。sweep が閉じるのは、environment='mcp' で metadata.implicit が true、かつ id が mcp- に 40 桁の 16 進文字を続けた形(トランスポートだけが作る形)のアクティブな run です。run のトークンによる呼び出し(トークンを記録しない run では、誰の呼び出しでも)が LOOM_MCP_SESSION_RUN_IDLE_SECONDS の間その run に届かなかったとき、sweep はそれを閉じます。run は呼び出し元のデフォルト名前空間に置かれるため、その読み手に見える内容もその名前空間に限られます。goal はラベル mcp session (<agent>) であり、呼び出しのテキストは入りません(読み取りのクエリは、呼び出し元が読める任意の名前空間に及ぶ可能性があるためです)。memories_written には、その名前空間への書き込みだけが載ります(それ以外の書き込みにも、その run_id は付きます)。run を閉じても何も判定しません。outcome は none で、サーバーのデフォルトの retain モードにかかわらず、メモリは保持されます。したがって、2 つの close が競合しても(2 台のホストでの sweep や DELETE)、最悪の場合、同じ completion が 2 回書き込まれるだけです。

run が複数の web プロセスにまたがる仕組み。run の id は、呼び出し元の org、トークンの subject、Mcp-Session-Id のハッシュです。そのため、サーバーのどのプロセスも同じセッションに対して同じ run を指し、同じセッション id を送っても他のトークンがその run を指すことはできません。プロセスは、セッションで最初に受理された run スコープの呼び出しで run を登録し、begin 行をバックグラウンドで書き込みます(await する insert では、ClickHouse Cloud 上でその呼び出しが数秒止まってしまいます)。ゲートに拒否された呼び出しは run 行を書きません。行が見つからなかった 2 つのプロセスがそれぞれ最初の begin を書いた場合は、開始が早いほうとその所有者が優先されます(最初の begin の行バージョンは開始時刻から逆算して減っていき、以降の書き込みはすべてそれを上書きします)。各プロセスは、キャッシュした run を台帳と照合する頻度を 1 分に最大 1 回とし、その間に DELETE や sweep が閉じていた場合は run を再オープンします。DELETE は、どのプロセスに届いても id によって run を閉じ、close はその id への書き込みを、誰が閉じるかに関係なくすべて集計します。begin 行が書き込まれる前に別のプロセスへ届いた DELETE は、閉じる対象が見つかりません。その後 begin が書き込まれて open の run ができ、アイドルになった時点で sweep がそれを閉じます。短いリトライでは数秒かかる begin をカバーできず、run を一度も持たなかったすべてのセッションの DELETE を遅らせてしまうためです。再オープンされた run は元の started_at を保つため、sweep に閉じられた後に再オープンされた run の duration_ms は、セッションの最初の呼び出しから、空白期間も含めて数えた値になります。消去(erasure)によって行が削除され、チェックで行がまったく見つからなかった場合は、その時点で開始する新しい run が始まります。そのため、消去より前の日付の run が戻ってくることはありません。

オペレーション

オペレーション ロール 内容
run.begin writer run を開始します:goal(必須)、user_request、expected_outcome、run_id(空または -:自動生成)、session_id、role、model、metadata。同じ run_id を再送すると行が置き換えられます。MCP トランスポートの形式の ID(mcp- と 40 桁の 16 進数)には、別の ID が割り当てられます。
run.complete writer run を一度だけ終了します:status、memories_used、recalled_keys、outcome、reflection、retain。冪等ではありません。2 回完了すると使用イベントが 2 回追加されます。
run.get viewer 1 件の run を、有効な派生データとともに返します。
run.list viewer run の 1 ページ分を返します。agent、session_id、status、grade、q、memory_activity で絞り込めます(with はメモリを利用または書き込んだ run を残し、without は何も使わなかった run を残します。絞り込みは limit の前に適用されます)。
run.grade writer 終了済みの run、またはセッションの run に pass / fail の評価を付けます。

run.list は order_by(開始時刻、所要時間、利用したメモリ数のいずれかを昇順または降順で指定します。デフォルトは started_desc、新しい順です)と offset(最大 100,000)でページングします。q は、ゴール、run id、エージェントのいずれかに指定したテキストを含む run を、大文字小文字を区別せずに残します。total は絞り込みに一致するすべての run の件数です。2 ページ目以降の満杯のページでは、そのページだけでは判断できないため null になります。

フィールドの全一覧はオペレーションリファレンスを参照してください。memory.outcome_run は、キーを指定せずにまとめて評価する呼び出し元向けに、run の下で呼び出された各メモリについて helped / hurt の結果を 1 件ずつ記録します。

例

Python SDK の run.scope は、ブロックに入るときに実行(run)を開き、抜けるときに閉じます。ブロック内で memory.ask の回答が引用したキーと、used() に渡したキーが memories_used になります。例外が発生した場合、実行は failed(outcome は negative)として閉じられ、その後に例外が伝播します。ブロック内の書き込みには、その実行の id が付与されます。

from loom import Agent

async with Agent(org="acme", namespace="support", agent="triage-bot") as agent:
    async with agent.run.scope(goal="Answer ticket 4411: refund policy for annual plans") as run:
        answer = await agent.memory.ask("what is the refund policy for annual plans?")
        run.used("policy/refunds/annual")  # relied on beyond what the answer cited
        run.final_response = answer["answer"]

    replay = await agent.run.get(run.run_id)
    print(replay["run"]["status"], replay["memories_written"], replay["recalled"])

    # Later, once the customer confirmed the answer was right:
    await agent.run.grade("pass", run_id=run.run_id, source="support-lead")

HTTP では、ライフサイクルは 2 回の呼び出しで構成されます。

curl -sX POST "$LOOM_BASE_URL/v1/run.begin" -H "Authorization: Bearer $LOOM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"org":"acme","namespace":"support","agent":"triage-bot","goal":"Answer ticket 4411"}'
# → {"run_id":"…","status":"active","started_at":"…","next":"…"}

curl -sX POST "$LOOM_BASE_URL/v1/run.complete" -H "Authorization: Bearer $LOOM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"org":"acme","namespace":"support","run_id":"…","status":"completed",
       "memories_used":["policy/refunds/annual"]}'

Agent(auto_run=True)(またはクライアント環境の LOOM_AUTO_RUN=on)を指定すると、最初のメモリ操作の呼び出しで実行が遅延的に開かれ、以降のすべての呼び出しがその実行に紐づけられ、Agent を閉じるときに outcome none で完了されます。そのため、評価の加点も減点も行われません。実行下での書き込みはその実行にスコープされ、別の実行の行を言い換えた内容は統合されず duplicate として保存されるため、この設定はデフォルトでは無効です。

設定

設定 効果
LOOM_MEMORY_RUN_COMPLETE_RETAIN 呼び出しで retain モードが指定されていない場合に使われるモード(keep)。
LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS retain=expire が有効期限を何日先に設定するか(7 日)。
LOOM_SEARCH_TRACE_LOG_ENABLED すべての検索を run_id ごとに記録します。recalled はこの記録から導出されます。クエリテキストをログに残すため、デフォルトではオフです。
LOOM_USAGE_FOLD_ENABLED used / evidence / harm イベントをランキングに反映する usage_fold ワーカー。
LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT, …_HALF_LIFE_DAYS 検索で、利用実績が行をどの程度、どのくらいの期間押し上げるか。

設定:重複排除と有効期限、 ワーカー、 メモリ検索 も参照してください。

制限

  • memories_used と recalled_keys は、それぞれ最大 500 個のキーを受け付けます。goal は最大 2,000 文字です。
  • memories_used のキーのうち、有効な行に解決されないものは何も得られません。レスポンスの used_applied は、解決されたキーの数を示します。
  • run.complete は冪等ではありません。完了を再試行すると使用イベントが二重に計上されるため、完了は一度だけ行ってください。
  • SDK の run.scope は、ledger をベストエフォートで書き込みます。run.complete が失敗しても、ブロック自体の例外が隠されることはありません。そのため、完了に失敗した run は active のままになります。
  • turns と cost_usd は、run に session_id がない場合、またはクライアントがターンの使用量を報告しない場合は 0 になります。これらは、run が開いている間に行われたターンだけを集計します。

関連ドキュメント