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

# `run` 操作

<!-- i18n: source=docs/reference/operations/run.md blob=4f9606262a494386856be2505b8e7fd3dbb703f0 model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/run.md)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/run.md), which is authoritative.


每个 `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>`。身份字段（`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)上还会填充其命名空间和 agent；参见[身份与命名空间](/zh-CN/concepts/identities-and-namespaces)。[操作索引](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)说明了角色、类别以及 MCP 的 `all` 列表。未知的输入字段仍会被处理，并在 `ignored_args` 中列出。

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

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

## `run.begin`

在开始处理任务之前，先开启一个 RUN（任务的一次执行）。

`POST /v1/run.begin` · MCP `loom_run_begin` · 角色 `writer` · 幂等 · 已审计

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 执行写入或读取的 agent；在操作允许时，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 此次 run 所属的对话。 |
| `run_id` | `str` | `''` | run 的 id；为空或 "-" 时由服务器生成。 |
| `goal` | `str` | 必填 | 此次 run 要完成的目标，用 agent 自己的话描述；存储在 run 行中。 |
| `user_request` | `str` | `''` | 启动此次 run 的原始请求，原文照录；未提供时为空。 |
| `expected_outcome` | `str` | `''` | 一次成功的 run 应产出的结果；存储下来供日后复查，未提供时为空。 |
| `environment` | `str` | `''` | 标明 run 执行位置的自由文本标签（例如 `ci`、`local`）；按原样存储。 |
| `model` | `str` | `''` | agent 所运行的模型；按原样存储，未提供时为空。 |
| `consumer` | `str` | `''` | 调用方集成的标记，记录在账本行中。 |
| `role` | `str` | `''` | agent 在多 agent run 中的角色：planner、executor、critic，或团队自定的称呼。 |
| `metadata` | `dict[str, Any]` | *（计算得出）* | 存储在 run 上的自由格式键值；如果设置了 `role`，会将其加入其中。 |
| `budget_usd` | `float` | `0.0` | 此次 run 可使用的模型花费上限（美元）；需要 session_id（0 表示不限制，对同一 run_id 重复发送 begin 时保持不变）。 |
| `budget_seconds` | `int` | `0` | 此次 run 可用的秒数（0 表示不限制，对同一 run_id 重复发送 begin 时保持不变）。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `run_id` | `str` | 此次调用所属的 agent run（任务范围）；`'-'` 表示无。 |
| `status` | `Literal['active', 'completed', 'failed', 'cancelled']` | 刚开启的 run 始终为 `active`。 |
| `started_at` | `str` | run 的开始时间，ISO UTC 格式，以 `Z` 结尾；重复发送的 `run_id` 保留第一次的开始时间。 |
| `next` | `str` | 协议提示：该如何处理这个 run_id。 |

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

## `run.complete`

关闭由 run.begin 开启的 run，任务结束时只能调用一次。

`POST /v1/run.complete` · MCP `loom_run_complete` · 角色 `writer` · 写入 · 已审计

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `user_id` | `str` | `'-'` | run 的用户和对话，与 run.begin 接收的一致：限定到单个会话的令牌会据此解析其范围，并且只能完成自己的 run。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `run_id` | `str` | 必填 | 该调用所属的 agent run（任务范围）；`'-'` 表示无。 |
| `status` | `Literal['completed', 'failed', 'cancelled']` | 必填 | run 的结束方式：`completed`、`failed` 或 `cancelled`；同时决定默认的 `outcome`。 |
| `final_response` | `str` | `''` | agent 的最终答案，存储在 run 行中。 |
| `confidence` | `float` | `0.0` | agent 对结果的置信度（0–1），存储在 run 中；0 表示以完全置信度记录会话的结果标签。 |
| `memories_used` | `list[str]` | *(计算得出)* | agent 实际依赖的 memory_keys（是其所召回内容的子集）。 |
| `recalled_keys` | `list[str]` | *(计算得出)* | 该会话的 Loom 工具所提供的记忆键（插件的 PostToolUse hook 会从 loom_search / memory.get 的结果中暂存它们，并在 SessionEnd 时交给本调用）。 |
| `outcome` | `Literal['', 'positive', 'negative', 'none']` | `''` | 应用于 memories_used 的结果。"" 表示由 status 推导：completed → positive，failed → negative，cancelled → none。 |
| `weight` | `int` | `1` | `memories_used` 的每个使用、证据或损害事件所携带的事件计数（1–100）。 |
| `duration_ms` | `int` | `0` | 手动指定的实际耗时；0 表示根据 started_at 计算。 |
| `metadata` | `dict[str, Any]` | *(计算得出)* | 合并到 run 已存储元数据中的键值对；此处给出的键优先。 |
| `reflection` | `RunReflection \| None` | `None` | 可选的过程学习内容，写为一条 `reflection` 记忆（参见 RunReflection）。 |
| `retain` | `Literal['', 'keep', 'demote', 'expire']` | `''` | 对该 run 所写入的行如何处理。'' 表示服务器默认值（settings.memory_run_complete_retain，即 `keep`）。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `run_id` | `str` | 该调用所属的 agent run（任务范围）；`'-'` 表示无。 |
| `status` | `Literal['active', 'completed', 'failed', 'cancelled']` | 关闭 run 时使用的状态。 |
| `duration_ms` | `int` | run 的时长（毫秒）：取调用中的 `duration_ms`，否则为当前时间减去 `started_at`。 |
| `used_applied` | `int` | 解析到有效记忆行的 memories_used 键数量（每个都获得了 `used`）。 |
| `evidence_applied` | `int` | 还收到了一条 positive 结果证据事件的行数。 |
| `harm_applied` | `int` | 收到了一条 negative 结果损害事件的行数。 |
| `memories_written` | `list[str]` | 在此 run_id 下写入的 memory_keys（来自 loom.memory）。 |
| `recalled` | `int` | memory.search 在此 run_id 下返回的不同 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 为该 run 的结果）的过程性记忆数量，即 procedure.evolve 所读取的账本。outcome 为 `none` 时为 0。 |
| `reflection_key` | `str` | 由 `reflection` 写入的反思记忆的 memory_key；没有时为 ""。 |
| `retain` | `str` | 针对该 run 所写入行的保留统计。 |
| `retained` | `int` | 该 run 写入的行中，被 `demote`/`expire` 模式保持不变的行数（已固定、已验证等）；`keep` 模式下为 0。 |
| `demoted` | `int` | 被 `retain=demote` 降低了置信度的行数。 |
| `expiring` | `int` | 被 `retain=expire` 设置了过期时间的行数。 |

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

## `run.get`

回放一次运行：目标、状态、最终响应、它所依赖的记忆、它写入的 memory_keys、它召回和观察到的记忆数量，以及它的模型轮次花费了多少。

`POST /v1/run.get` · MCP `loom_run_get` · 角色 `viewer` · 读取

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `run_id` | `str` | 必填 | 调用所属的 agent 运行（任务范围）；无则填 `'-'`。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `found` | `bool` | 当命名空间中不存在此 id 的运行时为 False；此时其他所有字段均为空。 |
| `run` | `RunRow \| None` | 运行行；未找到时为 `None`。 |
| `recalled` | `int` | 实时推导的值（不存储在行中）：该运行召回、写入、观察到的内容及其花费。 |
| `recalled_keys` | `list[str]` | memory.search 在该运行下返回的 key，加上 hooks 报告为已提供的 key；两者都未知时为空。 |
| `memories_written` | `list[str]` | 在此运行 id 下写入的 key，从 `loom.memory` 实时读取。 |
| `observations` | `int` | 带有此运行 id 标记的情景观察（`observe.record`）数量。 |
| `turns` | `int` | 运行开启期间，该会话在 loom.agent_turn_usage 中的轮次数（由插件的 Stop hook 写入）；当运行没有会话或未安装 hook 时为 0。 |
| `unpriced_turns` | `int` | 其模型不在价格表中的轮次数：每个此类轮次的花费按 0 计算，因此 `cost_usd` 和成本预算都不包含它们。 |
| `cost_usd` | `float` | 这些轮次的模型花费总和，单位为美元；与 `turns` 一样，无数据时为 0。 |
| `elapsed_seconds` | `int` | 从 started_at 到 completed_at 的秒数（运行中则到当前时间），按服务器时钟计算；不是 duration_ms。 |
| `over_budget` | `list[Literal['cost', 'time']]` | 该运行已超出的预算：`cost`（cost_usd > budget_usd）和 `time`（elapsed_seconds > budget_seconds）。 |

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

## `run.grade`

对已关闭（CLOSED）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` | `''` | 给出该评定的原因；作为 `grade_reason` 存储在 run 上。 |
| `ref` | `str` | `''` | 评定所依据的内容：URL、发现键（finding key）或检查运行 id。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `graded` | `int` | 已写入评定的 run 数量（评定结果发生变化的已关闭 run）。 |
| `run_ids` | `list[str]` | 已写入评定的 run 的 id。 |
| `skipped_active` | `int` | 目标中因仍处于活动状态（未关闭）而未处理的 run 数量。 |
| `unchanged` | `int` | 已带有相同评定、来源、原因和 ref 的已关闭 run 数量。 |
| `memories_counted` | `int` | 被评定的 run 所依赖的不同记忆的数量（memories_used）。 |
| `proposals_decided` | `list[RunGradeProposal]` | 由所有者设定的策略根据此次评定做出决定的提案（仅限 auto 模式）。 |

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

## `run.list`

返回某个命名空间下 agent 运行记录的一页结果及匹配总数（`total`），支持过滤和排序。

`POST /v1/run.list` · MCP `loom_run_list` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `''` | 仅返回该 agent 的运行；"""*" 或 "-" 表示所有 agent。 |
| `session_id` | `str` | `''` | 仅返回该会话的运行；"""*" 或 "-" 表示所有会话。 |
| `status` | `Literal['', 'active', 'completed', 'failed', 'cancelled']` | `''` | 仅返回处于该状态的运行；"" 列出所有状态。 |
| `limit` | `int` | `50` | 按 `order_by` 顺序最多返回这么多条运行；服务器上限为 200。 |
| `offset` | `int` | `0` | 在该页之前跳过的运行数（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` | `''` | 仅返回目标、运行 id 或 agent 中包含该文本的运行，不区分大小写；"" 表示不过滤。 |
| `memory_activity` | `Literal['', 'with', 'without']` | `''` | 运行页面会折叠既未依赖也未写入记忆的运行。 |
| `grade` | `Literal['', 'ungraded', 'graded', 'pass', 'fail']` | `''` | `ungraded` / `graded` / 评定结果（`pass`、`fail`）；"" 表示所有运行。 |
| `fields` | `list[str] \| None` | `None` | 调用方要读取的输出字段（按行模型解析的白名单；未知名称会返回 422）；未设置时返回所有字段。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `runs` | `list[RunRow]` | 按 `order_by` 顺序匹配的运行（默认按 `started_at` 最新的在前），若指定了 `fields` 则只包含这些字段。 |
| `total` | `int \| None` | 匹配过滤条件的运行数；第一页之后的满页结果中为 null。 |

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