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

<!-- i18n: source=docs/reference/operations/run.md blob=4f9606262a494386856be2505b8e7fd3dbb703f0 model=claude-sonnet-5-5 -->
> 이 페이지는 [영어 원문](https://clickhouse.github.io/loom/reference/operations/run/)을 기계 번역한 것이며, 영어 원문이 기준입니다.
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/run/), which is authoritative.

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

# `run` 작업

각 `run.*` 작업이 받고 반환하는 정확한 필드입니다.

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

모든 op는 HTTP에서는 `POST /v1/<op>`이고, MCP에서는 `loom_<op>` 도구입니다. 전송 방식이 지원하면 ID 필드(`org`, `namespace`, `agent`, `user_id`, `session_id`)는 토큰과 MCP 세션에서 채워집니다. 단일 사용자 서버에서 토큰 없이 HTTP로 호출하면, `code.*`와 `tracker.*`를 제외한 모든 op에서 설치의 org가 사용됩니다(이 둘은 각자 플레인의 값을 유지합니다). [일부 op](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)에서는 네임스페이스와 에이전트도 채워집니다. 자세한 내용은 [ID와 네임스페이스](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)를 참고하세요. [작업 색인](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)에서 role, kind, MCP `all` 목록을 설명합니다. 알 수 없는 입력 필드도 처리되며 `ignored_args`에 이름이 표시됩니다.

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

<a id="runbegin"></a>

## `run.begin`

작업을 시작하기 전에 RUN(작업 한 번의 실행)을 엽니다.

`POST /v1/run.begin` · MCP `loom_run_begin` · role `writer` · 멱등 · 감사 기록 대상

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소). |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. |
| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트. `'-'` 또는 `'*'`는 op가 허용하는 경우 모든 에이전트를 의미합니다. |
| `user_id` | `str` | `'-'` | 행이 속한 최종 사용자. 없으면 `'-'`. |
| `session_id` | `str` | `'-'` | 이 run이 속한 대화. |
| `run_id` | `str` | `''` | run의 id. 비어 있거나 "-"이면 서버가 새로 생성합니다. |
| `goal` | `str` | 필수 | run이 달성하려는 목표를 에이전트의 표현으로 작성한 것. run 행에 저장됩니다. |
| `user_request` | `str` | `''` | run을 시작시킨 원래 요청을 그대로 옮긴 것. 지정하지 않으면 비어 있습니다. |
| `expected_outcome` | `str` | `''` | 성공한 run이 만들어내야 하는 결과. 나중에 검토할 수 있도록 저장되며, 지정하지 않으면 비어 있습니다. |
| `environment` | `str` | `''` | run이 실행되는 위치를 나타내는 자유 형식 라벨(예: `ci`, `local`). 입력한 그대로 저장됩니다. |
| `model` | `str` | `''` | 에이전트가 사용하는 모델. 입력한 그대로 저장되며, 지정하지 않으면 비어 있습니다. |
| `consumer` | `str` | `''` | 호출하는 통합(integration)의 태그. 원장 행에 기록됩니다. |
| `role` | `str` | `''` | 다중 에이전트 run에서 에이전트의 역할 — planner, executor, critic 또는 팀에서 쓰는 용어. |
| `metadata` | `dict[str, Any]` | *(계산됨)* | run에 저장되는 자유 형식 키/값. `role`이 설정되면 여기에 추가됩니다. |
| `budget_usd` | `float` | `0.0` | run이 사용할 수 있는 모델 비용(USD). session_id가 필요합니다(0 = 없음, 같은 run_id로 begin을 다시 보내도 유지됨). |
| `budget_seconds` | `int` | `0` | run에 허용되는 시간(초)(0 = 없음, 같은 run_id로 begin을 다시 보내도 유지됨). |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `run_id` | `str` | 호출이 속한 에이전트 run(작업 범위). 없으면 `'-'`. |
| `status` | `Literal['active', 'completed', 'failed', 'cancelled']` | 방금 연 run에서는 항상 `active`입니다. |
| `started_at` | `str` | run이 시작된 시각. `Z`가 붙은 ISO UTC 형식이며, `run_id`를 다시 보내도 처음 시작 시각이 유지됩니다. |
| `next` | `str` | 프로토콜 안내: run_id로 무엇을 해야 하는지. |

<a id="runcomplete"></a>

## `run.complete`

run.begin으로 시작한 run을 닫습니다. 작업이 끝날 때 정확히 한 번만 호출하세요.

`POST /v1/run.complete` · MCP `loom_run_complete` · 역할 `writer` · 쓰기 · 감사 대상

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소)입니다. |
| `namespace` | `str` | 필수 | 이 op가 읽거나 쓰는 네임스페이스입니다. |
| `user_id` | `str` | `'-'` | run.begin이 받은 그대로의 run 사용자와 대화입니다. 하나의 세션으로 범위가 좁혀진 토큰은 이 값으로 범위를 결정하며, 자신의 run만 완료할 수 있습니다. |
| `session_id` | `str` | `'-'` | 행이 속한 세션 또는 대화입니다. 없으면 `'-'`입니다. |
| `run_id` | `str` | 필수 | 호출이 속한 에이전트 run(작업 범위)입니다. 없으면 `'-'`입니다. |
| `status` | `Literal['completed', 'failed', 'cancelled']` | 필수 | run이 끝난 방식으로, `completed`, `failed`, `cancelled` 중 하나입니다. 기본 `outcome`도 이 값으로 정해집니다. |
| `final_response` | `str` | `''` | 에이전트의 최종 답변입니다. run 행에 저장됩니다. |
| `confidence` | `float` | `0.0` | 결과에 대한 에이전트의 신뢰도(0–1)이며 run에 저장됩니다. 0이면 세션 결과 레이블을 최대 신뢰도로 기록합니다. |
| `memories_used` | `list[str]` | *(계산됨)* | 에이전트가 실제로 의존한 memory_keys입니다(recall한 것의 부분집합). |
| `recalled_keys` | `list[str]` | *(계산됨)* | 세션의 Loom 도구가 제공(SERVED)한 메모리 키입니다(플러그인의 PostToolUse 훅이 loom_search / memory.get 결과에서 이를 보관해 두었다가 SessionEnd에 넘깁니다). |
| `outcome` | `Literal['', 'positive', 'negative', 'none']` | `''` | memories_used에 적용되는 결과입니다. ""이면 status에서 유도합니다. completed → positive, failed → negative, cancelled → none. |
| `weight` | `int` | `1` | `memories_used`에 대한 각 사용, 근거 또는 피해 이벤트가 갖는 이벤트 횟수입니다(1–100). |
| `duration_ms` | `int` | `0` | 실제 경과 시간 재정의 값입니다. 0이면 started_at으로 계산합니다. |
| `metadata` | `dict[str, Any]` | *(계산됨)* | run에 저장된 메타데이터에 병합되는 키/값입니다. 여기에 지정한 키가 우선합니다. |
| `reflection` | `RunReflection \| None` | `None` | 선택적인 프로세스 학습으로, `reflection` 메모리로 기록됩니다(RunReflection 참고). |
| `retain` | `Literal['', 'keep', 'demote', 'expire']` | `''` | 이 run이 기록한 행을 어떻게 처리할지 정합니다. ''이면 서버 기본값(settings.memory_run_complete_retain, `keep`)을 따릅니다. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `run_id` | `str` | 호출이 속한 에이전트 run(작업 범위)입니다. 없으면 `'-'`입니다. |
| `status` | `Literal['active', 'completed', 'failed', 'cancelled']` | run이 닫힐 때의 상태입니다. |
| `duration_ms` | `int` | run 길이(밀리초)입니다. 호출의 `duration_ms`가 있으면 그 값, 없으면 현재 시각에서 `started_at`을 뺀 값입니다. |
| `used_applied` | `int` | 살아 있는 메모리 행으로 확인된 memories_used 키의 수입니다(각각 `used`를 받음). |
| `evidence_applied` | `int` | 긍정 결과 근거 이벤트도 함께 받은 행의 수입니다. |
| `harm_applied` | `int` | 부정 결과 피해 이벤트를 받은 행의 수입니다. |
| `memories_written` | `list[str]` | 이 run_id로 기록된 memory_keys입니다(loom.memory에서 유도). |
| `recalled` | `int` | 이 run_id로 memory.search가 반환한 서로 다른 memory_keys의 수입니다. LOOM_SEARCH_TRACE_LOG_ENABLED가 필요하며, 추적 로그가 꺼져 있으면 -1입니다. |
| `observations` | `int` | 이 run_id가 태그된 에피소드 관찰(observe.record)의 수입니다. |
| `procedure_runs_recorded` | `int` | memories_used 중 procedure.record_run 행을 받은 절차 메모리의 수입니다(path는 비어 있고, ok = run의 결과). procedure.evolve가 읽는 장부입니다. `none` 결과이면 0입니다. |
| `reflection_key` | `str` | `reflection`으로 기록된 reflection의 memory_key입니다. 없으면 ""입니다. |
| `retain` | `str` | 이 run이 기록한 행에 대한 보존 집계입니다. |
| `retained` | `int` | 이 run이 기록한 행 중 `demote`/`expire` 모드가 건드리지 않은 행의 수입니다(고정됨, 검증됨 등). `keep`에서는 0입니다. |
| `demoted` | `int` | `retain=demote`로 신뢰도가 낮아진 행의 수입니다. |
| `expiring` | `int` | `retain=expire`로 만료 시각이 지정된 행의 수입니다. |

<a id="runget"></a>

## `run.get`

하나의 실행(run)을 재현합니다: 목표, 상태, 최종 응답, 실행이 참고한 메모리, 실행이 기록한 memory_keys, 실행이 회상하고 관찰한 메모리 수, 그리고 모델 턴에 든 비용을 확인할 수 있습니다.

`POST /v1/run.get` · MCP `loom_run_get` · 역할 `viewer` · 읽기

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소)입니다. |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스입니다. |
| `run_id` | `str` | 필수 | 호출이 속한 에이전트 실행(작업 범위)입니다. 없으면 `'-'`를 사용합니다. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `found` | `bool` | 네임스페이스에 해당 id의 실행이 없으면 False이며, 이 경우 다른 모든 필드는 비어 있습니다. |
| `run` | `RunRow \| None` | 실행 행입니다. 찾지 못하면 `None`입니다. |
| `recalled` | `int` | 행에 저장되지 않고 실시간으로 계산되는 값입니다: 실행이 회상한 것, 기록한 것, 관찰한 것, 그리고 비용입니다. |
| `recalled_keys` | `list[str]` | 실행 아래에서 memory.search가 반환한 키와 훅이 제공된 것으로 보고한 키입니다. 둘 다 알 수 없으면 비어 있습니다. |
| `memories_written` | `list[str]` | 이 실행의 id로 기록된 키이며, `loom.memory`에서 실시간으로 읽습니다. |
| `observations` | `int` | 이 실행의 id가 태그된 에피소드 관찰(`observe.record`)의 수입니다. |
| `turns` | `int` | 실행이 열려 있는 동안 발생한, loom.agent_turn_usage에 있는 세션의 턴 수입니다(플러그인의 Stop 훅이 기록합니다). 실행에 세션이 없거나 훅이 설치되지 않았다면 0입니다. |
| `unpriced_turns` | `int` | 모델이 가격표에 없는 턴의 수입니다. 이런 턴은 각각 비용이 0이므로 `cost_usd`와 비용 예산에서 제외됩니다. |
| `cost_usd` | `float` | 해당 턴들의 모델 비용 합계(USD)입니다. `turns`와 마찬가지로 해당 사항이 없으면 0입니다. |
| `elapsed_seconds` | `int` | started_at부터 completed_at까지(활성 상태에서는 현재까지)의 시간(초)이며, 서버 시계를 기준으로 합니다. duration_ms와는 다릅니다. |
| `over_budget` | `list[Literal['cost', 'time']]` | 실행이 초과한 예산입니다: `cost`(cost_usd > budget_usd)와 `time`(elapsed_seconds > budget_seconds)입니다. |

<a id="rungrade"></a>

## `run.grade`

종료된(CLOSED) 실행에 대한 판정으로, 보통 며칠이 지난 뒤에 내려집니다. 예를 들어 메인테이너가 발견 사항을 확인했거나, CI가 통과했거나, 리뷰어가 반려한 경우입니다.

`POST /v1/run.grade` · MCP `loom_run_grade` · 역할 `writer` · 멱등 · 감사 대상 · MCP `all` 툴셋에는 나열되지 않음

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소)입니다. |
| `namespace` | `str` | 필수 | 이 op가 읽거나 쓰는 네임스페이스입니다. |
| `run_id` | `str` | `''` | 판정할 실행입니다. ""또는 "-"는 지정하지 않음을 뜻합니다. |
| `session_id` | `str` | `''` | 이 세션의 종료된 모든 실행입니다. ""또는 "-"는 지정하지 않음을 뜻합니다. |
| `grade` | `Literal['pass', 'fail']` | 필수 | 판정 결과입니다. `pass`(결과가 유효함) 또는 `fail`입니다. |
| `source` | `str` | `'caller'` | 판정한 주체입니다. `maintainer`, `ci`, `reviewer`, `judge` 등(짧은 자유 텍스트)입니다. |
| `reason` | `str` | `''` | 판정 이유입니다. 실행에 `grade_reason`으로 저장됩니다. |
| `ref` | `str` | `''` | 판정의 근거입니다. URL, 발견 사항 키, 체크 실행 id 등입니다. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `graded` | `int` | 판정이 기록된 실행의 수입니다(판정이 바뀐 종료된 실행). |
| `run_ids` | `list[str]` | 판정이 기록된 실행의 id입니다. |
| `skipped_active` | `int` | 아직 활성 상태(종료되지 않음)여서 건드리지 않은 대상 실행의 수입니다. |
| `unchanged` | `int` | 이미 같은 판정, 출처, 이유, 참조를 가지고 있던 종료된 실행의 수입니다. |
| `memories_counted` | `int` | 판정된 실행이 활용한 서로 다른 메모리의 수입니다(memories_used). |
| `proposals_decided` | `list[RunGradeProposal]` | 소유자가 설정한 정책이 이 판정에 따라 결정한 제안입니다(auto 모드에서만). |

<a id="runlist"></a>

## `run.list`

네임스페이스의 에이전트 실행(run)을 필터링하고 정렬한 한 페이지와 일치하는 개수(`total`)를 반환합니다.

`POST /v1/run.list` · MCP `loom_run_list` · role `viewer` · read · MCP `all` 툴셋에는 나열되지 않음

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소). |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. |
| `agent` | `str` | `''` | 이 에이전트의 run만 반환. "", "*", "-"는 모든 에이전트. |
| `session_id` | `str` | `''` | 이 세션의 run만 반환. "", "*", "-"는 모든 세션. |
| `status` | `Literal['', 'active', 'completed', 'failed', 'cancelled']` | `''` | 이 상태의 run만 반환. ""는 모든 상태를 나열. |
| `limit` | `int` | `50` | `order_by` 순서로 최대 이 개수만큼의 run을 반환. 서버는 200으로 제한. |
| `offset` | `int` | `0` | 페이지 앞에서 건너뛸 run 수(0-100,000). 기본값 0은 첫 페이지. |
| `order_by` | `Literal['started_desc', 'started_asc', 'duration_desc', 'duration_asc', 'relied_on_desc', 'relied_on_asc']` | `'started_desc'` | 시작 시각, 소요 시간(진행 중이면 0) 또는 의존한 메모리 수로 정렬. 기본값은 최신순. |
| `q` | `str` | `''` | 목표, run id 또는 에이전트에 이 텍스트가 포함된 run만 반환(대소문자 무시). ""는 필터 없음. |
| `memory_activity` | `Literal['', 'with', 'without']` | `''` | Runs 페이지는 메모리에 의존하지도, 메모리를 쓰지도 않은 run을 접어서 표시합니다. |
| `grade` | `Literal['', 'ungraded', 'graded', 'pass', 'fail']` | `''` | `ungraded` / `graded` / 판정(`pass`, `fail`). ""는 모든 run. |
| `fields` | `list[str] \| None` | `None` | 호출자가 읽을 출력 필드(행 모델에 대해 확인되는 허용 목록이며, 알 수 없는 이름은 422). 설정하지 않으면 모든 필드. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `runs` | `list[RunRow]` | `order_by` 순서(기본값은 `started_at`이 최신인 순)로 일치하는 run. 지정한 경우 `fields`로 투영됩니다. |
| `total` | `int \| None` | 필터와 일치하는 run 수. 첫 페이지 이후의 가득 찬 페이지에서는 null. |

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