コンテンツにスキップ

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

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

run オペレーション

各 run.* オペレーションが受け取るフィールドと返すフィールドの詳細です。

すべてのオペレーションは、HTTP では POST /v1/<op>、MCP ツールでは loom_<op> として呼び出せます。ID フィールド(org、namespace、agent、user_id、session_id)は、トランスポートが対応している場合、トークンと MCP セッションから補完されます。シングルユーザーサーバーでトークンなしの HTTP 呼び出しを行う場合、code.* と tracker.*(それぞれのプレーンの org を保持します)を除くすべてのオペレーションで、インストールの org が使われます。一部のオペレーションでは、名前空間とエージェントも補完されます。詳細はID と名前空間を参照してください。ロール、種別、MCP の all 一覧については、オペレーション一覧で説明しています。未知の入力フィールドは受け付けられ、ignored_args に名前が記録されます。

run.begin

作業を開始する前に RUN(タスクの1回の実行)を開きます。

POST /v1/run.begin · MCP loom_run_begin · role writer · idempotent · audited

入力フィールド 型 デフォルト 意味
org str 必須 テナント(identity タプルの第1要素)。
namespace str 必須 この op が読み書きする名前空間。
agent str 必須 書き込みまたは読み取りを行うエージェント。op が許可する場合、'-' または '*' は任意のエージェントを意味します。
user_id str '-' 行が属するエンドユーザー。なしの場合は '-'。
session_id str '-' この run が属する会話。
run_id str '' run の id。空または "-" の場合はサーバーが発行します。
goal str 必須 run が目指すこと。エージェント自身の言葉で記述し、run 行に保存されます。
user_request str '' run を開始した元のリクエスト(原文のまま)。指定がない場合は空。
expected_outcome str '' run が成功した場合に得られるべき成果。後のレビューのために保存されます。指定がない場合は空。
environment str '' run の実行場所を表す自由記述のラベル(例:ci、local)。指定どおりに保存されます。
model str '' エージェントが動作しているモデル。指定どおりに保存され、指定がない場合は空。
consumer str '' 呼び出し元インテグレーションのタグ。ledger 行に記録されます。
role str '' マルチエージェント run におけるエージェントの役割(planner、executor、critic、またはチーム独自の呼称)。
metadata dict[str, Any] (算出) run に保存される自由形式のキーと値。role が指定されている場合は、これに追加されます。
budget_usd float 0.0 run が使用できるモデル費用(USD)。session_id が必要です(0 = 制限なし。同じ run_id の begin を再送した場合は値が維持されます)。
budget_seconds int 0 run にかけてよい秒数(0 = 制限なし。同じ run_id の begin を再送した場合は値が維持されます)。
出力フィールド 型 意味
run_id str 呼び出しが属するエージェント run(タスクスコープ)。なしの場合は '-'。
status Literal['active', 'completed', 'failed', 'cancelled'] 開いたばかりの run では常に active。
started_at str run の開始時刻。末尾に Z を付けた ISO UTC 形式。再送された run_id では最初の開始時刻が維持されます。
next str プロトコル上の案内:run_id をどう扱うか。

run.complete

run.begin で開始した実行を終了します。タスクの終了時に必ず1回だけ呼び出してください。

POST /v1/run.complete · MCP loom_run_complete · role writer · write · audited

入力フィールド 型 デフォルト 説明
org str 必須 テナント(識別タプルの最初の要素)。
namespace str 必須 この op が読み書きする名前空間。
user_id str '-' run.begin が受け取ったものと同じ、実行のユーザーと会話。1つのセッションに絞られたトークンは、これらからスコープを解決し、自身の実行のみを完了できます。
session_id str '-' 行が属するセッションまたは会話。なしの場合は '-'。
run_id str 必須 呼び出しが属するエージェントの実行(タスクスコープ)。なしの場合は '-'。
status Literal['completed', 'failed', 'cancelled'] 必須 実行の終了状態:completed、failed、cancelled のいずれか。outcome のデフォルトもこれで決まります。
final_response str '' エージェントの最終的な回答。実行の行に保存されます。
confidence float 0.0 結果に対するエージェントの確信度(0–1)。実行に保存されます。0 の場合、セッションの outcome ラベルが確信度最大で記録されます。
memories_used list[str] (計算値) エージェントが実際に利用した memory_keys(想起したもののサブセット)。
recalled_keys list[str] (計算値) セッションの Loom ツールが返した memory keys。プラグインの PostToolUse フックが loom_search / memory.get の結果から控えておき、SessionEnd で渡します。
outcome Literal['', 'positive', 'negative', 'none'] '' memories_used に適用される outcome。"" の場合は status から決まります:completed → positive、failed → negative、cancelled → none。
weight int 1 memories_used に対する各 usage、evidence、harm イベントが持つイベント数(1–100)。
duration_ms int 0 実時間の上書き。0 の場合は started_at から計算されます。
metadata dict[str, Any] (計算値) 実行の保存済みメタデータにマージされるキーと値。ここで指定したキーが優先されます。
reflection RunReflection \| None None 任意のプロセス学習。reflection メモリとして書き込まれます(RunReflection を参照)。
retain Literal['', 'keep', 'demote', 'expire'] '' この実行が書き込んだ行をどう扱うか。'' の場合はサーバーのデフォルト(settings.memory_run_complete_retain、keep)。
出力フィールド 型 説明
run_id str 呼び出しが属するエージェントの実行(タスクスコープ)。なしの場合は '-'。
status Literal['active', 'completed', 'failed', 'cancelled'] 実行を終了したときの状態。
duration_ms int 実行時間(ミリ秒)。呼び出しの duration_ms、なければ現在時刻から started_at を引いた値。
used_applied int 有効なメモリ行に解決された memories_used のキー数(それぞれに used が付与されます)。
evidence_applied int positive outcome の evidence イベントも受け取った行数。
harm_applied int negative outcome の harm イベントを受け取った行数。
memories_written list[str] この run_id のもとで書き込まれた memory_keys(loom.memory から導出)。
recalled int この run_id のもとで memory.search が返した memory_keys の異なり数。LOOM_SEARCH_TRACE_LOG_ENABLED が必要で、トレースログが無効の場合は -1。
observations int この run_id でタグ付けされたエピソード観測(observe.record)の数。
procedure_runs_recorded int memories_used のうち、procedure.record_run の行(path は空、ok は実行の outcome)が作られた手続きメモリの数。procedure.evolve が読む台帳です。outcome が none の場合は 0。
reflection_key str reflection から書き込まれた reflection の memory_key。ない場合は ""。
retain str この実行が書き込んだ行に対する保持の集計。
retained int この実行が書き込んだ行のうち、demote/expire モードが手を付けなかったもの(ピン留め、検証済みなど)の数。keep では 0。
demoted int retain=demote により confidence が下げられた行数。
expiring int retain=expire により有効期限が設定された行数。

run.get

1 つの run を再生します。目標、ステータス、最終応答、依存したメモリ、書き込んだ memory_keys、想起および観測したメモリの数、モデルのターンにかかったコストを返します。

POST /v1/run.get · MCP loom_run_get · role viewer · read

入力フィールド 型 デフォルト 意味
org str 必須 テナント(identity タプルの最初の要素)。
namespace str 必須 op が読み書きする名前空間。
run_id str 必須 呼び出しが属するエージェントの run(タスクスコープ)。なければ '-'。
出力フィールド 型 意味
found bool この id の run が名前空間に存在しない場合は False。その場合、他のフィールドはすべて空になります。
run RunRow \| None run の行。見つからない場合は None。
recalled int 行には保存されない、その都度算出される値。run が想起、書き込み、観測した内容とそのコスト。
recalled_keys list[str] run のもとで memory.search が返したキーと、フックが提供済みとして報告したキー。どちらも不明な場合は空。
memories_written list[str] この run の id で書き込まれたキー。loom.memory からその都度読み取られます。
observations int この run の id でタグ付けされたエピソード観測(observe.record)。
turns int run が開いている間に行われた、loom.agent_turn_usage 内のセッションのターン(プラグインの Stop フックが書き込む)。run にセッションがない場合やフックが未インストールの場合は 0。
unpriced_turns int モデルが価格表にないターン。各ターンのコストは 0 となるため、cost_usd とコスト予算には含まれません。
cost_usd float それらのターンのモデルコストの合計(USD)。turns と同様、該当がなければ 0。
elapsed_seconds int started_at から completed_at まで(active の間は現在まで)の秒数。サーバーの時計に基づき、duration_ms とは異なります。
over_budget list[Literal['cost', 'time']] run が超過した予算。cost(cost_usd > budget_usd)と time(elapsed_seconds > budget_seconds)。

run.grade

クローズ済みの run に対する判定です。通常は run のクローズから数日後に行われます。たとえば、メンテナーが指摘を確認した、CI が通った、レビュアーが指摘を却下した、といった場合です。

POST /v1/run.grade · MCP loom_run_grade · ロール writer · 冪等 · 監査対象 · MCP の all ツールセットには含まれません

入力フィールド 型 デフォルト 説明
org str 必須 テナント(識別タプルの最初の要素)。
namespace str 必須 この op が読み書きする名前空間。
run_id str '' 判定対象の run。"" または "-" は指定なし。
session_id str '' このセッションのクローズ済みのすべての run。"" または "-" は指定なし。
grade Literal['pass', 'fail'] 必須 判定結果:pass(結果が妥当だった)または fail。
source str 'caller' 判定を行った主体:maintainer、ci、reviewer、judge など(自由記述、短く)。
reason str '' 判定の理由。run に grade_reason として保存されます。
ref str '' 判定の根拠:URL、指摘のキー、チェック実行 ID など。
出力フィールド 型 説明
graded int 判定が書き込まれた run の数(判定結果が変わったクローズ済みの run)。
run_ids list[str] 判定が書き込まれた run の ID。
skipped_active int まだアクティブ(クローズされていない)ため、対象から除外された run の数。
unchanged int すでに同じ判定、source、reason、ref を持っていたクローズ済みの run の数。
memories_counted int 判定された run が参照した個別のメモリの数(memories_used)。
proposals_decided list[RunGradeProposal] この判定に基づき、オーナーが設定したポリシーが決定した提案(auto モードのみ)。

run.list

名前空間のエージェント実行(run)のページと、その一致件数(total)を、フィルタとソートを適用して返します。

POST /v1/run.list · MCP loom_run_list · ロール viewer · 読み取り · MCP の all ツールセットには含まれません

入力フィールド 型 デフォルト 意味
org str 必須 テナント(アイデンティティタプルの最初の要素)。
namespace str 必須 op が読み取りまたは書き込みを行う名前空間。
agent str '' このエージェントの run のみ。"", "*" または "-" は全エージェント。
session_id str '' このセッションの run のみ。"", "*" または "-" は全セッション。
status Literal['', 'active', 'completed', 'failed', 'cancelled'] '' このステータスの run のみ。"" は全ステータスを一覧します。
limit int 50 order_by の順で最大この件数の run。サーバー側の上限は 200 です。
offset int 0 ページの前にスキップする run の数(0-100,000)。デフォルトは 0 で、最初のページです。
order_by Literal['started_desc', 'started_asc', 'duration_desc', 'duration_asc', 'relied_on_desc', 'relied_on_asc'] 'started_desc' 開始時刻、所要時間(実行中は 0)、または依拠したメモリ数でソートします。デフォルトは新しい順です。
q str '' goal、run id、エージェントのいずれかにこのテキストを含む run のみ(大文字小文字を区別しません)。"" はフィルタなしです。
memory_activity Literal['', 'with', 'without'] '' Runs ページは、メモリに依拠せず、メモリも書き込まなかった run を折りたたみます。
grade Literal['', 'ungraded', 'graded', 'pass', 'fail'] '' ungraded / graded / 判定結果(pass、fail)。"" は全 run です。
fields list[str] \| None None 呼び出し側が読み取る出力フィールド(行モデルに対して解決されるホワイトリスト。未知の名前は 422)。未指定の場合は全フィールドです。
出力フィールド 型 意味
runs list[RunRow] order_by の順に並んだ一致する run(デフォルトでは started_at の新しい順)。fields が指定された場合はそれに射影されます。
total int \| None フィルタに一致する run の数。最初のページ以降の満杯のページでは null です。