跳到内容
ClickHouse Loom
Esc
↑↓导航↵打开⌘J预览
本页内容

`run` 操作

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

每个 run.* 操作接受和返回的确切字段。

每个操作都是通过 HTTP 的 POST /v1/<op>,也是 MCP 工具 loom_<op>。身份字段(org、namespace、agent、user_id、session_id)会在传输层能够提供时,根据令牌和 MCP 会话自动填充;对于单用户服务器上不带令牌的 HTTP 调用,除 code.* 和 tracker.*(它们保留各自平面的 org)之外的所有操作都使用该安装的 org,并且在部分操作上还会填充其命名空间和 agent;参见身份与命名空间。操作索引说明了角色、类别以及 MCP 的 all 列表。未知的输入字段仍会被处理,并在 ignored_args 中列出。

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。

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 设置了过期时间的行数。

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)。

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 模式)。

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。

这个页面有帮助吗?