Saltar a contenido

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.