未翻訳のページは英語で開き、英語と表示されます。
このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 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 です。 |