Las páginas sin traducir se abren en inglés y se indican como inglés.
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Operaciones de run
Los campos exactos que recibe y devuelve cada operación run.*.
Cada op es POST /v1/<op> sobre HTTP y la herramienta MCP loom_<op>. Los campos de identidad (org, namespace, agent, user_id, session_id) se rellenan a partir del token y de la sesión MCP cuando el transporte puede hacerlo; en una llamada HTTP sin token en un servidor de un solo usuario, se usa la org de la instalación en todas las ops excepto code.* y tracker.* (que conservan la de su plano), y en algunas ops también su espacio de nombres y su agente; consulta identidades y espacios de nombres. El índice de operaciones explica el rol, el tipo y el listado all de MCP. Los campos de entrada desconocidos se atienden y se nombran en ignored_args.
run.begin
Abre una RUN (una ejecución de una tarea) ANTES de empezar a trabajar en ella.
POST /v1/run.begin · MCP loom_run_begin · rol writer · idempotente · auditado
| Campo de entrada | Tipo | Valor por defecto | Significado |
|---|---|---|---|
org |
str |
obligatorio | El tenant (primer elemento de la tupla de identidad). |
namespace |
str |
obligatorio | El espacio de nombres que la op lee o escribe. |
agent |
str |
obligatorio | El agente que escribe o lee; '-' o '*' significa cualquier agente donde la op lo permita. |
user_id |
str |
'-' |
El usuario final al que pertenece la fila; '-' si no hay ninguno. |
session_id |
str |
'-' |
La conversación a la que pertenece esta run. |
run_id |
str |
'' |
El id de la run; vacío o "-" = el servidor genera uno. |
goal |
str |
obligatorio | Lo que la run se propone hacer, en palabras del agente; se almacena en la fila de la run. |
user_request |
str |
'' |
La solicitud original que inició la run, textual; vacío si no se indica. |
expected_outcome |
str |
'' |
Lo que debería producir una run exitosa; se almacena para revisarlo después, vacío si no se indica. |
environment |
str |
'' |
Etiqueta de texto libre de dónde se ejecuta la run (p. ej. ci, local); se almacena tal cual. |
model |
str |
'' |
El modelo sobre el que corre el agente; se almacena tal cual, vacío si no se indica. |
consumer |
str |
'' |
La etiqueta de la integración que llama, registrada en la fila del ledger. |
role |
str |
'' |
El rol del agente en una run con varios agentes: planner, executor, critic, o el término propio del equipo. |
metadata |
dict[str, Any] |
(calculado) | Pares clave/valor libres almacenados en la run; si se indica role, se añade a ellos. |
budget_usd |
float |
0.0 |
Gasto en modelos, en USD, que la run puede alcanzar; requiere un session_id (0 = sin límite, se conserva si se reenvía el begin del mismo run_id). |
budget_seconds |
int |
0 |
Segundos que puede durar la run (0 = sin límite, se conserva si se reenvía el begin del mismo run_id). |
| Campo de salida | Tipo | Significado |
|---|---|---|
run_id |
str |
La run del agente (ámbito de la tarea) a la que pertenece la llamada; '-' si no hay ninguna. |
status |
Literal['active', 'completed', 'failed', 'cancelled'] |
Siempre active para una run recién abierta. |
started_at |
str |
Cuándo empezó la run, en ISO UTC con una Z; un run_id reenviado conserva el primer inicio. |
next |
str |
Indicación del protocolo: qué hacer con el run_id. |
run.complete
Cierra una ejecución abierta con run.begin; llámalo EXACTAMENTE UNA VEZ cuando la tarea termine.
POST /v1/run.complete · MCP loom_run_complete · rol writer · escritura · auditado
| Campo de entrada | Tipo | Valor por defecto | Significado |
|---|---|---|---|
org |
str |
obligatorio | El tenant (primer elemento de la tupla de identidad). |
namespace |
str |
obligatorio | El espacio de nombres que la op lee o escribe. |
user_id |
str |
'-' |
El usuario y la conversación de la ejecución, tal como los recibió run.begin: un token limitado a una sesión resuelve su alcance a partir de estos valores y solo completa su propia ejecución. |
session_id |
str |
'-' |
La sesión o conversación a la que pertenece la fila; '-' si no hay ninguna. |
run_id |
str |
obligatorio | La ejecución del agente (alcance de la tarea) a la que pertenece la llamada; '-' si no hay ninguna. |
status |
Literal['completed', 'failed', 'cancelled'] |
obligatorio | Cómo terminó la ejecución: completed, failed o cancelled; también determina el outcome por defecto. |
final_response |
str |
'' |
La respuesta final del agente; se almacena en la fila de la ejecución. |
confidence |
float |
0.0 |
La confianza del agente en el resultado (0–1), almacenada en la ejecución; 0 registra la etiqueta de resultado de la sesión con confianza total. |
memories_used |
list[str] |
(calculado) | memory_keys en las que el agente se apoyó realmente (un subconjunto de lo que recuperó). |
recalled_keys |
list[str] |
(calculado) | Las memory keys que las herramientas de Loom de la sesión SERVIRON (el hook PostToolUse del plugin las guarda a partir de los resultados de loom_search / memory.get y las entrega en SessionEnd). |
outcome |
Literal['', 'positive', 'negative', 'none'] |
'' |
Resultado que se aplica a memories_used. "" lo deriva de status: completed → positive, failed → negative, cancelled → none. |
weight |
int |
1 |
Número de eventos que aporta cada evento de uso, evidencia o daño de memories_used (1–100). |
duration_ms |
int |
0 |
Sobrescritura del tiempo real; 0 = se calcula a partir de started_at. |
metadata |
dict[str, Any] |
(calculado) | Claves y valores que se combinan con los metadatos almacenados de la ejecución; las claves indicadas aquí prevalecen. |
reflection |
RunReflection \| None |
None |
Aprendizaje de proceso opcional, escrito como una memoria reflection (consulta RunReflection). |
retain |
Literal['', 'keep', 'demote', 'expire'] |
'' |
Qué ocurre con las filas que escribió esta ejecución. '' = el valor por defecto del servidor (settings.memory_run_complete_retain, keep). |
| Campo de salida | Tipo | Significado |
|---|---|---|
run_id |
str |
La ejecución del agente (alcance de la tarea) a la que pertenece la llamada; '-' si no hay ninguna. |
status |
Literal['active', 'completed', 'failed', 'cancelled'] |
El estado con el que se cerró la ejecución. |
duration_ms |
int |
Duración de la ejecución en milisegundos: duration_ms de la llamada o, si no, ahora menos started_at. |
used_applied |
int |
Claves de memories_used que se resolvieron a una fila de memoria activa (cada una recibió used). |
evidence_applied |
int |
Filas que además recibieron un evento de evidencia de resultado positivo. |
harm_applied |
int |
Filas que recibieron un evento de daño de resultado negativo. |
memories_written |
list[str] |
memory_keys escritas bajo este run_id (derivadas de loom.memory). |
recalled |
int |
memory_keys distintas que memory.search devolvió bajo este run_id; requiere LOOM_SEARCH_TRACE_LOG_ENABLED; -1 cuando el registro de trazas está desactivado. |
observations |
int |
Observaciones episódicas (observe.record) etiquetadas con este run_id. |
procedure_runs_recorded |
int |
Memorias procedimentales de memories_used que obtuvieron una fila de procedure.record_run (path vacío, ok = el resultado de la ejecución); es el registro que lee procedure.evolve. 0 con un resultado none. |
reflection_key |
str |
memory_key de la reflexión escrita a partir de reflection; "" si no hay ninguna. |
retain |
str |
Recuentos de retención sobre las filas que escribió esta ejecución. |
retained |
int |
Filas escritas por esta ejecución que el modo demote/expire dejó intactas (fijadas, verificadas, …); 0 con keep. |
demoted |
int |
Filas cuya confianza se redujo con retain=demote. |
expiring |
int |
Filas a las que retain=expire asignó una caducidad. |
run.get
Reproduce una ejecución: el objetivo, el estado, la respuesta final, las memorias en las que se apoyó, las memory_keys que escribió, cuántas memorias recuperó y observó, y cuánto costaron sus turnos de modelo.
POST /v1/run.get · MCP loom_run_get · role viewer · read
| Campo de entrada | Tipo | Valor por defecto | Significado |
|---|---|---|---|
org |
str |
obligatorio | El tenant (primer elemento de la tupla de identidad). |
namespace |
str |
obligatorio | El espacio de nombres que la op lee o escribe. |
run_id |
str |
obligatorio | La ejecución del agente (ámbito de la tarea) a la que pertenece la llamada; '-' si no hay ninguna. |
| Campo de salida | Tipo | Significado |
|---|---|---|
found |
bool |
False cuando no existe ninguna ejecución con este id en el espacio de nombres; todos los demás campos quedan entonces vacíos. |
run |
RunRow \| None |
La fila de la ejecución; None si no se encuentra. |
recalled |
int |
Derivaciones en vivo (no se almacenan en la fila): lo que la ejecución recuperó, escribió, observó y costó. |
recalled_keys |
list[str] |
Las claves que memory.search devolvió dentro de la ejecución, más las claves que los hooks informaron como servidas; vacío cuando no se conoce ninguna. |
memories_written |
list[str] |
Las claves escritas bajo el id de esta ejecución, leídas en vivo de loom.memory. |
observations |
int |
Observaciones episódicas (observe.record) etiquetadas con el id de esta ejecución. |
turns |
int |
Los turnos de la sesión en loom.agent_turn_usage (los escribe el hook Stop del plugin) realizados mientras la ejecución estuvo abierta; 0 cuando la ejecución no tiene sesión o el hook no está instalado. |
unpriced_turns |
int |
Los turnos cuyo modelo no figura en la tabla de precios: cada uno cuesta 0, por lo que cost_usd y un presupuesto de costo no los incluyen. |
cost_usd |
float |
Costo total del modelo en USD de esos turnos; 0 igual que en turns. |
elapsed_seconds |
int |
Segundos desde started_at hasta completed_at (hasta ahora mientras está activa), según el reloj del servidor; no es duration_ms. |
over_budget |
list[Literal['cost', 'time']] |
Los presupuestos que la ejecución ha superado: cost (cost_usd > budget_usd) y time (elapsed_seconds > budget_seconds). |
run.grade
Un veredicto sobre una ejecución CERRADA, normalmente días después: un maintainer confirmó el hallazgo, CI pasó o un revisor lo rechazó.
POST /v1/run.grade · MCP loom_run_grade · rol writer · idempotente · auditado · no figura en el toolset all de MCP
| Campo de entrada | Tipo | Valor por defecto | Significado |
|---|---|---|---|
org |
str |
obligatorio | El tenant (primer elemento de la tupla de identidad). |
namespace |
str |
obligatorio | El espacio de nombres que la op lee o escribe. |
run_id |
str |
'' |
La ejecución a calificar; "" o "-" = ninguna. |
session_id |
str |
'' |
Todas las ejecuciones cerradas de esta sesión; "" o "-" = ninguna. |
grade |
Literal['pass', 'fail'] |
obligatorio | El veredicto: pass (el resultado se sostuvo) o fail. |
source |
str |
'caller' |
Quién calificó: maintainer, ci, reviewer, judge… (texto libre, corto). |
reason |
str |
'' |
Por qué se dio la calificación; se almacena en la ejecución como grade_reason. |
ref |
str |
'' |
En qué se basa la calificación: una URL, una clave de hallazgo, un id de check run. |
| Campo de salida | Tipo | Significado |
|---|---|---|
graded |
int |
Ejecuciones cuya calificación se escribió (una ejecución cerrada cuyo veredicto cambió). |
run_ids |
list[str] |
Ids de las ejecuciones cuya calificación se escribió. |
skipped_active |
int |
Ejecuciones del objetivo que se dejaron sin tocar porque aún están activas (no cerradas). |
unchanged |
int |
Ejecuciones cerradas que ya tenían esta calificación, fuente, motivo y ref. |
memories_counted |
int |
Memorias distintas en las que se apoyaron las ejecuciones calificadas (memories_used). |
proposals_decided |
list[RunGradeProposal] |
Propuestas sobre las que la política definida por el propietario decidió con esta calificación (solo en modo auto). |
run.list
Una página de las ejecuciones de agente de un espacio de nombres y su cantidad de coincidencias (total), filtradas y ordenadas.
POST /v1/run.list · MCP loom_run_list · rol viewer · lectura · no aparece en el conjunto de herramientas MCP all
| Campo de entrada | Tipo | Valor por defecto | Significado |
|---|---|---|---|
org |
str |
obligatorio | El inquilino (primer elemento de la tupla de identidad). |
namespace |
str |
obligatorio | El espacio de nombres que la operación lee o escribe. |
agent |
str |
'' |
Solo las ejecuciones de este agente; "", "*" o "-" = todos los agentes. |
session_id |
str |
'' |
Solo las ejecuciones de esta sesión; "", "*" o "-" = todas las sesiones. |
status |
Literal['', 'active', 'completed', 'failed', 'cancelled'] |
'' |
Solo las ejecuciones en este estado; "" lista todos los estados. |
limit |
int |
50 |
Como máximo este número de ejecuciones, en el orden de order_by; el servidor lo limita a 200. |
offset |
int |
0 |
Ejecuciones que se omiten antes de la página (0-100,000); por defecto 0, la primera página. |
order_by |
Literal['started_desc', 'started_asc', 'duration_desc', 'duration_asc', 'relied_on_desc', 'relied_on_asc'] |
'started_desc' |
Ordena por hora de inicio, duración (0 mientras está activa) o memorias utilizadas; por defecto, las más recientes primero. |
q |
str |
'' |
Solo las ejecuciones cuyo objetivo, id de ejecución o agente contiene este texto, sin distinguir mayúsculas; "" significa sin filtro. |
memory_activity |
Literal['', 'with', 'without'] |
'' |
La página Runs oculta las ejecuciones que no utilizaron ni escribieron ninguna memoria. |
grade |
Literal['', 'ungraded', 'graded', 'pass', 'fail'] |
'' |
ungraded / graded / un veredicto (pass, fail); "" = todas las ejecuciones. |
fields |
list[str] \| None |
None |
Los campos de salida que lee el llamador (una lista blanca resuelta contra el modelo de fila; un nombre desconocido produce un 422); si no se define, todos los campos. |
| Campo de salida | Tipo | Significado |
|---|---|---|
runs |
list[RunRow] |
Ejecuciones coincidentes en el orden de order_by (por defecto, primero el started_at más reciente), proyectadas a fields cuando se indica. |
total |
int \| None |
Cuántas ejecuciones coinciden con los filtros; null en una página completa posterior a la primera. |