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

<!-- i18n: source=docs/reference/operations/observe.md blob=66dcf380ad6c65acb51be4b77f0437c076b43b0c model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://clickhouse.github.io/loom/reference/operations/observe/)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/observe/), which is authoritative.

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

# `observe` オペレーション

各 `observe.*` オペレーションが受け取るフィールドと返すフィールドの詳細です。

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

すべてのオペレーションは、HTTP では `POST /v1/<op>`、MCP ツールでは `loom_<op>` として呼び出せます。アイデンティティのフィールド（`org`、`namespace`、`agent`、`user_id`、`session_id`）は、トランスポートが対応している場合にトークンと MCP セッションから補完されます。単一ユーザーのサーバーでトークンなしに HTTP 呼び出しを行う場合は、`code.*` と `tracker.*`（それぞれのプレーンの値を保持）を除くすべてのオペレーションでインストールの org が使われ、[一部のオペレーション](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)では名前空間とエージェントも補完されます。詳しくは [アイデンティティと名前空間](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md) を参照してください。ロール、種別、MCP の `all` 一覧については [オペレーション一覧](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) で説明しています。未知の入力フィールドは処理されたうえで、`ignored_args` に名前が示されます。

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

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

## `observe.crystallize`

セッションの保留中のオブザベーションを、メモリへの抽出が可能な状態にします（キューへの登録のみ）。

`POST /v1/observe.crystallize` · MCP `loom_observe_crystallize` · role `writer` · idempotent

| 入力フィールド | 型 | デフォルト | 意味 |
| --- | --- | --- | --- |
| `org` | `str` | 必須 | テナント（アイデンティティタプルの最初の要素）。 |
| `namespace` | `str` | 必須 | オペレーションが読み書きする名前空間。 |
| `agent` | `str` | 必須 | 書き込みまたは読み取りを行うエージェント。オペレーションが許可する場合、`'-'` または `'*'` は任意のエージェントを意味します。 |
| `user_id` | `str` | `'-'` | 行が属するエンドユーザー。なしの場合は `'-'`。 |
| `session_id` | `str` | `'-'` | 行が属するセッションまたは会話。なしの場合は `'-'`。 |
| `max_observations` | `int` | `500` | セッションの保留中のオブザベーションのうち、古いものから最大でこの件数を ready にします。 |

| 出力フィールド | 型 | 意味 |
| --- | --- | --- |
| `enqueued` | `int` | 抽出ワーカー向けに `crystallize:ready` とマークされたオブザベーションの数。保留中のものがなかった場合は 0。 |
| `session_id` | `str` | 行が属するセッションまたは会話。なしの場合は `'-'`。 |

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

## `observe.record`

ツールのオブザベーション（入力、出力、ファイル、エラー）を 1 件、エピソードプレーンに記録します。LLM 呼び出しはありません。

`POST /v1/observe.record` · MCP `loom_observe_record` · role `writer` · idempotent

| 入力フィールド | 型 | デフォルト | 意味 |
| --- | --- | --- | --- |
| `org` | `str` | 必須 | テナント（アイデンティティタプルの最初の要素）。 |
| `namespace` | `str` | 必須 | オペレーションが読み書きする名前空間。 |
| `agent` | `str` | 必須 | 書き込みまたは読み取りを行うエージェント。オペレーションが許可する場合、`'-'` または `'*'` は任意のエージェントを意味します。 |
| `user_id` | `str` | `'-'` | 行が属するエンドユーザー。なしの場合は `'-'`。 |
| `session_id` | `str` | `'-'` | 行が属するセッションまたは会話。なしの場合は `'-'`。 |
| `run_id` | `str` | `'-'` | 呼び出しが属するエージェントの実行（タスクのスコープ）。なしの場合は `'-'`。 |
| `tool_name` | `str` | 必須 | 実行されたツールの名前。部分文字列の一致によってオブザベーションの `kind` が決まります。 |
| `tool_input` | `dict[str, Any] \| list[Any] \| str \| int \| float \| bool \| None` | `None` | フックから転送される任意の JSON。文字列化して切り詰められ、実行されることはありません。 |
| `tool_output` | `dict[str, Any] \| list[Any] \| str \| int \| float \| bool \| None` | `None` | ツールが返した内容。文字列化され、ナラティブでは 800 文字に切り詰められます。 |
| `file_paths` | `list[str]` | *(算出)* | 入力やナラティブから検出されたパスとマージされます。 |
| `error` | `str \| None` | `None` | 呼び出しが失敗した場合にのみ指定されます。オブザベーションの種別を `error` に再分類します。 |
| `tags` | `list[str]` | *(算出)* | サーバー自身のタグ（`observation`、種別、ファイルのベース名）の後に追加される任意のタグ。保持されるタグは合計で最大 32 個です。 |
| `observation_date` | `str` | `''` | valid_at として記録される ISO 形式 YYYY-MM-DD。空の場合は NULL のままにします。 |
| `action_type` | `str` | `''` | クライアント独自のアクション分類（file_read、command_run など）。`action:<type>` タグとして追加されます。 |
| `metadata` | `dict[str, Any]` | *(算出)* | クライアントのコンテキスト（project、repo、event）。受け付けられますが、保存されません。 |
| `observed_at` | `str` | `''` | ツールが実行された時刻。後から送信されたキャプチャも、実際に起きた時刻の日付になります。 |

| 出力フィールド | 型 | 意味 |
| --- | --- | --- |
| `memory_key` | `str` | エピソード行のキー（`obs:<session_id>:<hash prefix>`）。同じ呼び出しに対してフックが再度発火した場合も同じキーになります。 |
| `memory_id` | `str` | 常に空です。行の id はテーブルによって割り当てられ、読み戻されません。 |
| `kind` | `str` | file_edit / command_run / error / web_fetch / file_read / tool_use。 |
| `tags` | `list[str]` | 行に保存されたタグ（最大 32 個）。 |
| `file_paths` | `list[str]` | 行に保存されたファイルパス。送信されたものに加え、入力とナラティブから検出されたものを含みます。自己参照の呼び出しでは空です。 |
| `content_sha256` | `str` | 保存されたオブザベーションの値（kind、tool、ナラティブ、パス、エラー）のハッシュ。 |
| `tool_name` | `str` | 行が保持する内容。台帳では out_tool_name / out_has_error / out_narrative_chars として記録されます。ナラティブが 40 文字のものは、オブザベーションではなくツール名です。 |
| `has_error` | `bool` | `error` が空でなかった場合は True（自己参照の呼び出しでは常に False）。 |
| `narrative_chars` | `int` | 保存されたナラティブの文字数（最大 2000）。 |
| `skipped_reason` | `str` | 行が内容なしで保存された理由。"self_referential"（ツールが loom 自身、またはハーネスのメタツールだった）、"blacklisted"（内容がブラックリストのパターンに一致した）。それ以外は ""。 |

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