未翻訳のページは英語で開き、英語と表示されます。
このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 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/<domain>/api/models_<group>.py"] --> D["Operation(...) in OPERATIONS<br/>server/<domain>/api/ops_<group>.py"]
H["handler<br/>server/<domain>/app/<group>.py"] --> D
D --> R["ALL_OPERATIONS"]
R --> HTTP["HTTP /v1/<op>"]
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 リファレンス内のそのアンカーにリンクしている。