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

<!-- i18n: source=docs/reference/operations/observe.md blob=66dcf380ad6c65acb51be4b77f0437c076b43b0c 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/observe/), que prevalece.
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/observe/), which is authoritative.

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

# Operaciones `observe`

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

<!-- 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 salvo `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 aceptan y se nombran en `ignored_args`.

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

<a id="observecrystallize"></a>

## `observe.crystallize`

Marca las observaciones pendientes de una sesión como listas para su extracción a memorias (solo encola).

`POST /v1/observe.crystallize` · MCP `loom_observe_crystallize` · rol `writer` · idempotente

| 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 ninguno. |
| `session_id` | `str` | `'-'` | La sesión o conversación a la que pertenece la fila; `'-'` si ninguna. |
| `max_observations` | `int` | `500` | Se marcan como listas, como máximo, tantas observaciones pendientes de la sesión, empezando por las más antiguas. |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `enqueued` | `int` | Cuántas observaciones se marcaron como `crystallize:ready` para el worker de extracción; 0 cuando la sesión no tenía ninguna pendiente. |
| `session_id` | `str` | La sesión o conversación a la que pertenece la fila; `'-'` si ninguna. |

<a id="observerecord"></a>

## `observe.record`

Registra una observación de herramienta (entrada, salida, archivos, error) en el plano episódico; sin llamada a un LLM.

`POST /v1/observe.record` · MCP `loom_observe_record` · rol `writer` · idempotente

| 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 ninguno. |
| `session_id` | `str` | `'-'` | La sesión o conversación a la que pertenece la fila; `'-'` si ninguna. |
| `run_id` | `str` | `'-'` | La ejecución del agente (ámbito de la tarea) a la que pertenece la llamada; `'-'` si ninguna. |
| `tool_name` | `str` | obligatorio | Nombre de la herramienta que se ejecutó; determina el `kind` de la observación por coincidencia de subcadena. |
| `tool_input` | `dict[str, Any] \| list[Any] \| str \| int \| float \| bool \| None` | `None` | JSON arbitrario reenviado por el hook; se convierte en cadena y se trunca, nunca se ejecuta. |
| `tool_output` | `dict[str, Any] \| list[Any] \| str \| int \| float \| bool \| None` | `None` | Lo que devolvió la herramienta; se convierte en cadena y se corta a 800 caracteres en la narrativa. |
| `file_paths` | `list[str]` | *(calculado)* | Se combina con las rutas detectadas en la entrada o la narrativa. |
| `error` | `str \| None` | `None` | Presente solo si la llamada falló; reclasifica el kind de la observación como `error`. |
| `tags` | `list[str]` | *(calculado)* | Etiquetas adicionales que se añaden tras las propias del servidor (`observation`, el kind, los nombres base de los archivos); en total se conservan como máximo 32. |
| `observation_date` | `str` | `''` | Fecha ISO YYYY-MM-DD registrada como valid_at; vacío = se deja NULL. |
| `action_type` | `str` | `''` | La clase de acción propia del cliente (file_read, command_run, …), añadida como etiqueta `action:<type>`. |
| `metadata` | `dict[str, Any]` | *(calculado)* | Contexto del cliente (project, repo, event); se acepta, no se almacena. |
| `observed_at` | `str` | `''` | El momento en que se ejecutó la herramienta, de modo que una captura enviada más tarde quede fechada cuando ocurrió. |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `memory_key` | `str` | Clave de la fila episódica, `obs:<session_id>:<hash prefix>`; un hook que se dispara de nuevo para la misma llamada obtiene la misma clave. |
| `memory_id` | `str` | Siempre vacío: el id de la fila lo asigna la tabla y no se vuelve a leer. |
| `kind` | `str` | Uno de estos valores: file_edit / command_run / error / web_fetch / file_read / tool_use. |
| `tags` | `list[str]` | Las etiquetas almacenadas en la fila (como máximo 32). |
| `file_paths` | `list[str]` | Rutas de archivo almacenadas en la fila: las enviadas más las encontradas en la entrada y la narrativa; vacío para una llamada autorreferencial. |
| `content_sha256` | `str` | Hash del valor de la observación almacenada (kind, herramienta, narrativa, rutas, error). |
| `tool_name` | `str` | Lo que contiene la fila, en el registro como out_tool_name / out_has_error / out_narrative_chars — una observación con una narrativa de 40 caracteres es un nombre de herramienta, no una observación. |
| `has_error` | `bool` | True cuando `error` no estaba vacío (siempre False para una llamada autorreferencial). |
| `narrative_chars` | `int` | Longitud de la narrativa almacenada en caracteres (como máximo 2000). |
| `skipped_reason` | `str` | Por qué la fila se almacenó sin contenido: "self_referential" (la herramienta era el propio loom o una herramienta meta del harness), "blacklisted" (el contenido coincidió con un patrón de la lista negra); "" en otro caso. |

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