번역되지 않은 페이지는 영어로 열리며 영어로 표시됩니다.
이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. 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 op 테이블, 오퍼레이션 레퍼런스는 모두 이 선언에서 파생됩니다. 개발자는 모델, 핸들러, 선언, 테스트를 작성하고 나머지는 다시 생성합니다.
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"]
예제는 가장 작은 op 중 하나인 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)
모델 규칙:
- 식별 정보. 네임스페이스를 대상으로 하는 op는
org와namespace를 받습니다. 행을 쓰는 op는 식별 튜플의 나머지인agent,user_id,session_id,run_id를 받습니다(마지막 세 개의 기본값은'-'). MCP에서는 서버가 생략된 식별 필드를 연결의 기본값으로 채운 다음, 본문에 지정된(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. 핸들러 작성
그룹마다 server/<domain>/app/ 아래에 핸들러 모듈 하나를 둡니다. 핸들러는 async이며 입력 모델을 받아 출력 모델을 반환합니다. 모듈 최상단에서 wire 모델을 import하며, 모델은 핸들러를 import하지 않으므로 import에 순환이 생기지 않습니다.
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)를 raise합니다. 전송 계층은 이를 에러 envelope으로 변환하고, 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에 항목 하나로 들어갑니다. 예: "calibration.get": 60, (ms 단위의 op 설계 목표 p99이며, 이를 넘긴 성공 호출은 budget.violated 이벤트를 발생시킵니다). 핸들러가 실행 중에 기록하는 요청 형태(server.observability.budget_shape)는 OP_SHAPE_BUDGETS_P99_MS에 별도의 예산을 가지며, 카탈로그에 목록이 있습니다. tests/unit/test_op_budgets.py는 항목이 없는 op를 실패 처리합니다. 배포 환경에서는 LOOM_LATENCY_BUDGET_OVERRIDES로 op 하나를, LOOM_LATENCY_BUDGET_MULTIPLIER로 전체 op를 조정할 수 있습니다.
선언은 해당 그룹의 ops 모듈인 server/<domain>/api/ops_<group>.py에 두며, 이 모듈은 모델과 핸들러를 import합니다. 모듈의 OPERATIONS 리스트에 추가하세요. 새 그룹 모듈은 server/operations/registry.py에서 import하여 _OPERATION_MODULES에 추가합니다.
| 필드 | 필수 | 의미 |
|---|---|---|
name |
예 | 점으로 구분한 <group>.<verb> 형식입니다. HTTP 경로는 /v1/<name>, MCP 도구는 loom_<name with . → _>입니다. |
input_model, output_model |
예 | Pydantic 모델입니다. |
handler |
예 | 비동기 callable로, 입력 모델을 받아 출력 모델을 반환합니다. |
idempotent |
예 | 일시적인 실패 시 재시도해도 안전합니다. SDK와 클라이언트가 이 값에 의존합니다. |
required_role |
예 | Role.VIEWER, WRITER, ADMIN, ORG_ADMIN, PLATFORM_ADMIN 중 하나입니다. |
audit |
아니요 | True이면 성공 시 loom.audit_log에 행 하나를 기록합니다. 메모리, 권한 부여, 정책, 설정을 변경하는 op에는 반드시 지정하세요. |
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은stableop를 나열하며,experimentalop는 core 또는 atomic 목록에 포함된 경우에만 나열합니다(server/operations/toolsets.py의listed_under_all). _MCP_HIDDEN_OPS: MCP로 접근할 수 없습니다.tests/unit/test_hidden_op_says_why.py는 대신 호출해야 할 op를 알려 주는 거부 메시지를 요구합니다.
나열되는 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의 도달 범위(reach)는 파생 값입니다(Operation.reach, server/operations/reach.py). MCP 로스터 포함 여부와, SDK, examples/, dev/, scripts/, 플러그인 훅, 대시보드의 "/v1/<op>" 호출 지점을 커밋된 상태로 스캔한 결과를 합쳐 계산합니다. {"http_only"}는 원시 /v1/* POST만 해당 op에 도달한다는 뜻입니다.
모든 op는 모든 표면에 노출되거나, 노출되지 않는 이유를 코드에 밝힙니다. HTTP는 레지스트리의 모든 op를 제공하며, 두 SDK 모두 레지스트리에서 생성됩니다. MCP는 _MCP_HIDDEN_OPS가 사람과 운영자용으로 남겨 두지 않는 한 해당 op에 도달합니다. 대시보드는 사람이 필요로 할 때 op를 호출합니다. 관리, 검토, 조회, 구성, 확인 후 삭제가 그런 경우이며, 이런 종류의 새 op는 해당 컨트롤과 함께 출시됩니다. 에이전트나 클라이언트 프로그램만 호출하는 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"로 선언합니다. stableop는 MCPall툴셋에 나열되어 있거나, MCP에서 숨겨져 있다면 다른 도달 경로가 있어야 하며, 프로덕션 호출자가 있어야 합니다. 호출자가 있는지는python scripts/codegen/op_reach_census.py --call-counts --days 30으로 확인할 수 있습니다. 새 op는 stable 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, 그리고 다른 org)로 호출하고 canary nonce를 사용합니다. 어떤 응답에도 nonce가 포함되어서는 안 되며, 모든 호출은 200(빈 응답), 403 또는 404로 끝나야 하고 500이 나와서는 안 됩니다. 페이로드는 입력 모델로부터 합성되므로, 새 읽기 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가 일치하고 manifest가 최신 상태입니다. |
tests/unit/test_mcp_listing_budget.py |
목록에 올린 op가 목록을 예산 이내로 유지하며, 그 설명이 클라이언트가 호출할 수 없는 도구를 가리키지 않습니다. |
leakage 스위트가 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>는 두 리비전 사이에 클라이언트에 영향을 주는 변경 사항을 출력합니다. 릴리스 노트는 이 출력을 바탕으로 작성됩니다.
PR을 열기 전에
- 모델, 핸들러, 선언,
OPERATIONS항목(새 그룹이라면_OPERATION_MODULES도 포함). -
required_role,idempotent,audit,writes,maturity를 신중하게 선택했습니다. -
row_scopedop는 다른 소유자의 행을 존재하지 않는 행으로 응답합니다. - 툴셋 배치와, 목록에 포함되는 경우 설명.
- 위에 명시한 테스트가 통과하고, 생성되는 파일을 다시 생성했습니다.
- 해당 op를 담당하는 기능 페이지가 operations 레퍼런스의 앵커를 링크합니다.