번역되지 않은 페이지는 영어로 열리며 영어로 표시됩니다.
이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.
run 작업
각 run.* 작업이 받고 반환하는 정확한 필드입니다.
모든 op는 HTTP에서는 POST /v1/<op>이고, MCP에서는 loom_<op> 도구입니다. 전송 방식이 지원하면 ID 필드(org, namespace, agent, user_id, session_id)는 토큰과 MCP 세션에서 채워집니다. 단일 사용자 서버에서 토큰 없이 HTTP로 호출하면, code.*와 tracker.*를 제외한 모든 op에서 설치의 org가 사용됩니다(이 둘은 각자 플레인의 값을 유지합니다). 일부 op에서는 네임스페이스와 에이전트도 채워집니다. 자세한 내용은 ID와 네임스페이스를 참고하세요. 작업 색인에서 role, kind, MCP all 목록을 설명합니다. 알 수 없는 입력 필드도 처리되며 ignored_args에 이름이 표시됩니다.
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로 무엇을 해야 하는지. |
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로 만료 시각이 지정된 행의 수입니다. |
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)입니다. |
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 모드에서만). |
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. |