コンテンツにスキップ

未翻訳のページは英語で開き、英語と表示されます。

このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.

オペレーションの追加

オペレーションはレジストリ内で一度だけ宣言します。HTTP ルート(POST /v1/<op>)、OpenAPI スキーマ、MCP ツール(loom_<op with dots as underscores>)、カタログ(/v1/operations、ops.capabilities)、SDK のオペレーションテーブル、およびオペレーションリファレンスは、すべてこの宣言から生成されます。モデル、ハンドラー、宣言、テストを自分で書き、残りは再生成します。

flowchart LR
    M["Input / Output models<br/>server/&lt;domain&gt;/api/models_&lt;group&gt;.py"] --> D["Operation(...) in OPERATIONS<br/>server/&lt;domain&gt;/api/ops_&lt;group&gt;.py"]
    H["handler<br/>server/&lt;domain&gt;/app/&lt;group&gt;.py"] --> D
    D --> R["ALL_OPERATIONS"]
    R --> HTTP["HTTP /v1/&lt;op&gt;"]
    R --> MCP["MCP tool + toolsets"]
    R --> G["generated: sdk ops.py, ops.ts,<br/>reach manifest, reference/operations.md"]

例として、最小規模のオペレーションの一つである calibration.get を取り上げます。関連ファイルは server/memory/api/models_calibration.py、server/memory/api/ops_calibration.py、server/memory/app/calibration.py です。

1. 入力モデルと出力モデルを定義する

モデルは、グループの models モジュール server/<domain>/api/models_<group>.py に置きます。models モジュールにはワイヤー形式の Pydantic モデルだけを置き、ハンドラーは import しません。

from pydantic import BaseModel, Field


class CalibrationGetInput(BaseModel):
    org: str
    namespace: str


class CalibrationGetOutput(BaseModel):
    source: str  # "namespace" / "cluster" / "scalar"
    embedder_model: str = ""
    noise_floor: float
    ...
    similar_pairs_n: int = Field(default=0)

モデルのルール:

  • ID。 名前空間を指定する op は org と namespace を受け取ります。行を書き込む op は、ID タプルの残りである agent、user_id、session_id、run_id も受け取ります(後ろの 3 つのデフォルトは '-' です)。MCP では、省略された ID フィールドをサーバーが接続のデフォルト値で補い、そのうえでボディが指定する (org, namespace) を認可します。
  • サーバーが設定するカラムをボディから受け取らない。 書き込みパスが actor(server.memory.app.provenance.writer_actor)と source_class(server.memory.domain.provenance.source_class_for)を設定します。リクエストで宣言できるのは、derived、external、imported へのダウングレードだけです。
  • エージェントに無関係なフィールドを MCP から隠す。 ランキングのつまみやパイプラインのスイッチには json_schema_extra=MCP_HIDDEN(server/operations/base.py)を指定します。MCP スキーマからは除外されますが、op は引き続きそのフィールドを受け付けます。
  • 読み取り入力にモデルレベルの「A または B のどちらか」バリデーターを置かない。 トランスポートは認可の前にボディを検証するため、例外を送出する @model_validator は、名前空間ゲートが拒否するはずのプリンシパルに op の内容を明かしてしまいます。ルールはハンドラーに書き、server.core.errors.ValidationError を送出してください。tests/unit/test_op_inputs_after_gate.py が、登録済みのすべての op を検査します。
  • フィールドを廃止するには、削除します。そのフィールドをまだ送ってくるクライアントも処理され、そのフィールド名は ignored_args に入ります(未知のフィールドと削除されたフィールド)。

2. ハンドラを書く

ハンドラモジュールはグループごとに 1 つ、server/<domain>/app/ に置きます。ハンドラは async で、入力モデルを受け取り、出力モデルを返します。ワイヤモデルはモジュールの先頭でインポートします。モデルがハンドラをインポートすることはないため、インポートは循環しません。

from server.memory.api.models_calibration import CalibrationGetInput, CalibrationGetOutput


async def handle_calibration_get(input: CalibrationGetInput) -> CalibrationGetOutput:
    from server.memory.app.embedder_calibration import get_calibration, get_namespace_calibration

    ns_cal = await get_namespace_calibration(input.org, input.namespace)
    ...
  • 純粋なロジックはドメインの domain/ に、SQL は store/ に置きます。ハンドラはそれらを組み合わせます。
  • 拒否は server.core.errors.LoomServerError のサブクラス(または {"code", "message"} を detail に持つ HTTPException)を送出します。トランスポートがこれをエラーエンベロープに変換し、MCP では isError の結果にします。新しいエラーコードは、生成されるエラーリファレンスに掲載されます。
  • 広範な except は理由を書きます: except Exception as e: # noqa: BLE001 — <what must not fail>。
  • ClickHouse クエリへの log_comment の付与はトランスポートが行います。ハンドラは何もしません。
  • 設定は settings.<field> として読み取り、getattr(settings, ...) は使いません。
  • op が loom.memory または loom.shared に書き込む場合は、server/memory/store/rows.py のビルダーで行を組み立てます(テーブルの追加)。

組織全体の id で指定される op

memory.get_by_id や memory.update_by_id のように (org, memory_id) だけを受け取る op には、トランスポートから名前空間が渡されません。この op には row_scoped=True を宣言し、読み取りの前に呼び出し元が到達できる名前空間を解決し、他者の行は隠します。

import server.memory.store as memory_repo
from server.memory.app.id_namespace import namespace_for_id

namespace = await namespace_for_id(input.org, input.memory_id, strong=False)
if namespace is None:
    return MemoryGetByIdOutput(found=False)
row = await memory_repo.get_by_id(input.memory_id, org=input.org, namespace=namespace, ...)
if row is None:
    return MemoryGetByIdOutput(found=False)

403 ではなく、行が存在しない場合と同じ応答を返します。403 を返すと、その id が別のテナントに存在することを確認させてしまうためです。書き込みでは、保持者を最新の状態で読むために、namespace_for_id に Role.WRITER と strong=True を渡します。memory.redact のように先に行を読み取る必要がある op は、取得後に authz.row_in_scope で検査します(行スコープの操作)。

3. オペレーションを宣言する

from server.operations.base import Operation, Role

calibration_get = Operation(
    name="calibration.get",
    maturity="experimental",
    input_model=CalibrationGetInput,
    output_model=CalibrationGetOutput,
    handler=handle_calibration_get,
    idempotent=True,
    required_role=Role.VIEWER,
    audit=False,
)

OPERATIONS: list[Operation] = [calibration_get]

レイテンシ予算は、すべての op の予算を定める server/settings/catalog.py の OP_BUDGETS_P99_MS に 1 エントリとして置きます。"calibration.get": 60, がその例です(op の設計目標 p99 をミリ秒で表したもので、これを超えた成功呼び出しは budget.violated イベントを発行します)。ハンドラが実行時に記録するリクエスト形状(server.observability.budget_shape)には、OP_SHAPE_BUDGETS_P99_MS に個別の予算を設定します。カタログにその一覧があります。エントリのない op は tests/unit/test_op_budgets.py で失敗します。デプロイ側では、1 つの op は LOOM_LATENCY_BUDGET_OVERRIDES で、すべての op は LOOM_LATENCY_BUDGET_MULTIPLIER で調整できます。

宣言は、グループの ops モジュール server/<domain>/api/ops_<group>.py に置きます。このモジュールがモデルとハンドラをインポートします。宣言はモジュールの OPERATIONS リストに追加してください。新しいグループモジュールは、server/operations/registry.py でインポートし、_OPERATION_MODULES に追加します。

フィールド 必須 意味
name はい <group>.<verb> の形のドット区切りの名前。HTTP パスは /v1/<name>、MCP ツールは loom_<name with . → _>。
input_model, output_model はい Pydantic モデル。
handler はい 非同期の呼び出し可能オブジェクト。入力モデルを受け取り、出力モデルを返す。
idempotent はい 一時的な失敗のときに安全に再試行できる。SDK とクライアントはこれに依存する。
required_role はい Role.VIEWER、WRITER、ADMIN、ORG_ADMIN、PLATFORM_ADMIN のいずれか。
audit いいえ True の場合、成功すると loom.audit_log に 1 行を書き込む。メモリ、権限付与、ポリシー、設定を変更するものには必ず設定する。
writes いいえ viewer が呼び出せて再試行も安全だが、保存された状態を変更する op(フィードバック行、既読マーカーなど)。writer ロールや audit=True は、すでに「書き込む」ことを示している。
maturity いいえ stable(デフォルト)または experimental。ステップ 5 を参照。
skip_namespace_authz いいえ 名前空間に対して作用する op(join、leave、register)や、対象をハンドラだけが解決できる op(id 指定の memory.verify、スコープ指定の erasure.request、呼び出し元ロールによる erasure.list)で、トランスポートの名前空間チェックを省略する。ハンドラが独自のルールを適用する。ロールチェックは引き続き実行される。
deployment_scoped いいえ op が名前空間のデータではなく、デプロイに関する事実(ビルド、レジストリ)を読む。スコープ付きトークンは、名前空間ごとのロールのうち最も高いものでパスする。
row_scoped いいえ 組織全体の id で指定される。ハンドラが行のスコープを認可し(読み取り前は namespace_for_id、読み取り後は row_in_scope)、他スコープの行は存在しないものとして隠す。

op が読み取り専用(MCP の readOnlyHint、readonly ツールセット)になるのは、idempotent であり、required_role == Role.VIEWER で、audit も writes も設定されていない場合に限ります(Operation.read_only)。読み取り専用ツールを自動承認するクライアントは、これらのフラグを信頼します。

4. MCP での公開範囲を決める

server/operations/toolsets.py が、op をどこに一覧表示するかを決めます。

  • 厳選されたロスター(_MCP_CORE_OPS、_MCP_CODING_OPS、_MCP_ATOMIC_OPS、_MCP_TASK_OPS、_MCP_TRACKER_OPS、_MCP_CODE_CORE_OPS)に載せると、その ?toolset= に op が一覧表示されます。一覧に載せたプロパティはすべて毎ターントークンを消費するため、そのアーキタイプが呼び出すものだけを追加してください。tests/unit/test_mcp_listing_budget.py が、一覧をトークン上限以下に保ちます。
  • 一覧に載せない(ほとんどの op):どの一覧からでも loom_op を通して名前で呼び出せます(readonly では読み取りのみ。MCP ツールセット)。?toolset=all は stable の op を一覧表示し、experimental の op は core または atomic のロスターに載っている場合にのみ一覧表示します(server/operations/toolsets.py の listed_under_all)。
  • _MCP_HIDDEN_OPS:MCP からは到達できません。tests/unit/test_hidden_op_says_why.py は、代わりに呼び出すべきものを示す拒否応答を要求します。

一覧に載せる op には、server/transport/mcp_descriptions.py(TOOL_DESCRIPTIONS)に説明が必要です。説明はモデル向けに書きます。ツールをいつ呼び出すか、何を返すか、何に使うべきでないかを書いてください。変更された事実に関する説明は、独自の記述を持たず、同じモジュールの revision_policy() を埋め込みます。別の op には、ドット区切りの op 名で言及します。各一覧は、一覧に載っている op をそのツール名に置き換え、載っていない op には印を付けます(MCP リファレンス)。op を呼び出し形式(op(args))で書いたり、より長いコードスパンの中に入れたり、手書きの「(via loom_op)」を付けたりしないでください。フィールドの例の値として op 名を示す場合は、一重引用符で囲みます('memory.ask')。一覧はこれをそのまま残します。

5. リーチと成熟度を確認する

op のリーチは導出される値です(Operation.reach、server/operations/reach.py)。MCP ロスターへの所属に加えて、SDK、examples/、dev/、scripts/ のコミット済みスキャン、プラグインのフック、ダッシュボードの "/v1/<op>" 呼び出し箇所から決まります。{"http_only"} は、生の /v1/* POST だけがその op に到達できることを意味します。

すべての op は、すべてのサーフェスに存在するか、存在しない理由をコード内で示します。HTTP はレジストリ内のすべての op を提供し、両方の SDK はレジストリから生成されます。_MCP_HIDDEN_OPS が人間やオペレーター向けに留めている場合を除き、MCP からも op に到達できます。ダッシュボードは、人が必要とするとき(管理、レビュー、確認、設定、確認付きの削除)にその op を呼び出します。この種の新しい op は、対応する操作 UI とともに提供されます。エージェントまたはクライアントプログラムだけが呼び出す op や、ダッシュボードが別の op を通じて提供する op は、理由とともに NOT_IN_DASHBOARD(server/operations/dashboard.py)に記載します。census の --check(tests/unit/test_op_reach_census.py)は、ダッシュボードの呼び出し箇所も server/operations/dashboard.py のエントリもない op があると失敗します。

  • MCP から隠されていて、ほかにリーチ経路がない op(種類は server/operations/reach.py に一覧があります)は、maturity="experimental" を宣言します。
  • stable の op は、MCP の all ツールセットに掲載されているか、MCP から隠されている場合はほかのリーチ経路を持ち、本番の呼び出し元があることが前提です。呼び出し元があるかどうかは python scripts/codegen/op_reach_census.py --call-counts --days 30 で確認できます。stable の op を置き換える場合を除き、新しい op は experimental と宣言してください。
  • マニフェストを更新します:python scripts/codegen/op_reach_census.py --write-manifest(server/operations/reach_manifest.py に書き込みます)。

6. テストを書く

テスト op に求められること
tests/unit/ 配下のユニットテスト ハンドラーの拒否ケースと正常系を網羅します。
tests/integration/test_cross_principal_leakage.py 読み取り系の op をすべて、別のテナント(別の名前空間の writer と viewer、および別の組織)として実行し、canary nonce を埋め込みます。レスポンスにそれらが含まれてはならず、すべての呼び出しは 200(空)、403、404 のいずれかで終わり、500 になってはなりません。ペイロードは op の入力モデルから合成されるため、新しい読み取り op は登録したその日からプローブされます。
tests/integration/test_restricted_namespace_leakage.py 制限付き名前空間に対する同様のテストです。
tests/unit/test_op_inputs_after_gate.py 入力モデルが、モデルレベルの検証エラーなしで構築できること。
tests/unit/test_op_reach_census.py reach と maturity が一致し、マニフェストが最新であること。
tests/unit/test_mcp_listing_budget.py 一覧に載る op が一覧を予算内に収め、その説明がクライアントの呼び出せないツールを指していないこと。

リークテストのスイートが op のボディを合成できない場合は、その旨が報告されます。スキップせず、ヒントを追加してください。呼び出し元自身の名前空間を変更する op は、スイートの _SKIP_OPS に入れ、writer ゲートは別のテストでカバーします。統合テストには稼働中のサーバー(LOOM_BASE_URL)が必要で、サーバーがない場合はスキップされます。トークンは、CI で有効になっていないセルフサインアップではなく、スイートのヘルパーで発行してください。

7. 再生成とゲートの実行

python scripts/codegen/sdk_py_gen.py                       # sdk/python/loom/ops.py
python scripts/codegen/sdk_py_client_gen.py                # sdk/python/loom/client.py
python scripts/codegen/sdk_ts_gen.py                       # sdk/typescript/src/generated/ops.ts
python scripts/codegen/op_reach_census.py --write-manifest # server/operations/reach_manifest.py
python scripts/codegen/docs_reference.py                   # generated regions of docs/reference/*.md
make format
make lint          # ruff, gates, every generator with --check, the reach census --check, Biome's dashboard accessibility rules
make typecheck
make test-unit     # reach census, MCP listing budget

生成ファイルが古い場合、CI は失敗します。生成された SDK ファイルにより、すべてのクライアントが op を一度に利用できます。Python と TypeScript の agent.call("calibration.get", {...}) は、新しい TypedDict とインターフェースに対して型付けされます。SDK クライアント上の手書きメソッド(sdk/python/loom/<group>.py)は任意です。よく使う動詞には追加してください。これは到達パスとして数えられます。

python scripts/codegen/wire_changelog.py <rev_a> <rev_b> は、2 つのリビジョン間でクライアントに影響する変更を出力します。リリースノートはこの出力から作成されます。

PR を開く前に

  • モデル、ハンドラ、宣言、OPERATIONS エントリ(新しいグループの場合は _OPERATION_MODULES も)。
  • required_role、idempotent、audit、writes、maturity を意図して選んでいる。
  • row_scoped の op は、他者の行を存在しない行として応答する。
  • ツールセットへの配置、および一覧に載せる場合は説明。
  • 上記のテストが通り、生成ファイルを再生成済みである。
  • その op を扱う機能ページが、operations リファレンス内のそのアンカーにリンクしている。

関連ドキュメント