尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
run 操作
每个 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。 |