콘텐츠로 이동

번역되지 않은 페이지는 영어로 열리며 영어로 표시됩니다.

이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. 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.