> Source: https://clickhouse.github.io/loom/es/reference/operations/run/ (Markdown: https://clickhouse.github.io/loom/es/reference/operations/run.md)

<!-- i18n: source=docs/reference/operations/run.md blob=4f9606262a494386856be2505b8e7fd3dbb703f0 model=claude-sonnet-5-5 -->
> Esta página es una traducción automática de la [página en inglés](https://clickhouse.github.io/loom/reference/operations/run/), que prevalece.
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/run/), which is authoritative.

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

# Operaciones de `run`

Los campos exactos que recibe y devuelve cada operación `run.*`.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

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](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request) también su espacio de nombres y su agente; consulta [identidades y espacios de nombres](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md). El [índice de operaciones](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica el rol, el tipo y el listado `all` de MCP. Los campos de entrada desconocidos se atienden y se nombran en `ignored_args`.

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

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

## `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. |

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

## `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. |

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

## `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). |

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

## `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). |

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

## `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. |

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