> Source: https://clickhouse.github.io/loom/ja/reference/operations/run/ (Markdown: https://clickhouse.github.io/loom/ja/reference/operations/run.md)

<!-- i18n: source=docs/reference/operations/run.md blob=4f9606262a494386856be2505b8e7fd3dbb703f0 model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://clickhouse.github.io/loom/reference/operations/run/)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/run/), which is authoritative.

<a id="run-operations"></a>

# `run` オペレーション

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

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

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

<!-- prettier-ignore-start -->

<a id="runbegin"></a>

## `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 をどう扱うか。 |

<a id="runcomplete"></a>

## `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` により有効期限が設定された行数。 |

<a id="runget"></a>

## `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）。 |

<a id="rungrade"></a>

## `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 モードのみ）。 |

<a id="runlist"></a>

## `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 です。 |

<!-- prettier-ignore-end -->
