본문으로 건너뛰기
ClickHouse Loom
Esc
↑↓이동↵열기⌘J미리보기
이 페이지에서

실행

실행

이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.

실행(run)은 “이슈 1234 분류”와 같은 작업 하나를 한 번 수행하는 단위입니다. run.begin이 실행을 열고 run_id를 반환합니다. 에이전트는 쓰기 작업(memory.set, memory.update, observe.record)에 이 id를 함께 전달합니다. run.complete는 상태, 에이전트가 참고한 메모리, 그리고 선택 사항으로 회고(reflection)를 받아 실행을 닫습니다. 읽기 작업(memory.search, memory.ask)에서 본문의 run_id는 해당 실행 자체의 행만 걸러냅니다. 따라서 읽기에는 대신 다른 방식으로 레이블을 붙입니다. HTTP에서는 X-Loom-Run-Id 헤더(Python SDK에서는 run_scope)를, MCP에서는 세션 자체의 실행을 사용합니다. 성공한 실행이 참고한 메모리는 다음번에 더 높은 순위로 노출되고, 실패한 실행이 참고한 메모리는 그동안 얻은 가중치를 잃습니다.

실행이 기록하는 내용

실행 행은 loom.agent_runs에 있습니다. run.get이 보여 주는 대부분의 값은 읽는 시점에 다른 plane에서 파생됩니다.

필드 저장 또는 파생 출처
goal, user_request, model, … 저장 run.begin
status, final_response 저장 run.complete (그 전까지는 active)
memories_used 저장 run.complete: 에이전트가 의존했다고 직접 밝힌 내용
grade, grade_source, … 저장 실행이 종료된 후의 run.grade
memories_written 파생 실행의 run_id를 가진 loom.memory의 행
recalled, recalled_keys 파생 run_id에 대한 검색 트레이스 로그와 run.complete(recalled_keys)의 합집합
observations 파생 run_id가 태그된 observe.record의 에피소드 행
turns, cost_usd 파생 실행이 열려 있는 동안 발생한 세션의 턴(loom.agent_turn_usage에 기록됨, Claude Code 플러그인 또는 cost.record_turns를 사용하는 에이전트가 기록)
budget_usd, budget_seconds 저장 run.begin (0 = 예산 없음)
elapsed_seconds, over_budget 파생 서버 시계 기준으로 실행 시작부터 종료(또는 현재)까지의 시간과 cost_usd를 예산과 비교하여 계산

LOOM_SEARCH_TRACE_LOG_ENABLED가 꺼져 있고 recalled_keys도 전송되지 않았다면 recalled는 -1입니다.

예산

run.begin은 선택 항목인 budget_usd(모델 지출)와 budget_seconds(실행에 걸릴 수 있는 시간)를 받습니다. run.get은 이 값을 cost_usd, elapsed_seconds와 비교하여 실행이 초과한 항목을 over_budget에 나열합니다(cost, time, 또는 둘 다). Loom은 에이전트를 실행하지 않으므로, 예산은 에이전트를 실행하는 쪽에 보내는 신호일 뿐 실행을 중단시키지 않습니다.

실행의 지출은 실행이 열려 있는 동안 해당 세션에서 발생한 턴의 비용이며, 각 턴의 고유 시각(대화 기록의 turn_at)을 기준으로 합산합니다. 따라서 budget_usd에는 session_id가 필요합니다(없으면 422). 비용과 마찬가지로 소수점 6자리까지 유지하므로 가장 작은 값은 $0.000001입니다. 시간은 클라이언트가 보고한 duration_ms와 관계없이 서버 시계를 기준으로 실행 시작부터 종료까지 계산합니다. 예산은 실행의 첫 run.begin에서 설정하세요.

세션에서 활성 실행이 예산을 초과한 것을 처음 발견한 run.get에는 멘토 힌트 run_over_budget도 함께 담기며, 플러그인이 이를 조언으로 모델에 전달합니다. 종료된 실행도 over_budget은 보고하지만 힌트는 받지 않습니다. 다른 멘토 힌트와 마찬가지로 세션당 한 번만 전달되며, 세션을 보내지 않는 호출자(SDK, 일반 HTTP)는 네임스페이스와 웹 프로세스마다 하나를 공유하므로, 힌트가 아니라 over_budget을 기준으로 판단하세요.

제한 사항:

  • 프롬프트 사이에서만 확인됩니다. Claude Code 플러그인은 프롬프트가 끝날 때 해당 프롬프트의 턴을 전송하므로(에이전트가 cost.record_turns로 직접 전송할 수도 있습니다), 비용 예산은 프롬프트 사이에서 확인되고, 단일 헤드리스 프롬프트(claude -p)의 지출은 끝난 뒤에야 나타납니다. 에이전트 자신의 run.complete 이후에 도착한 턴도 계속 합산됩니다. 호출의 비용은 호출이 반환된 뒤에야 알 수 있으므로, 실행은 어떤 곳에서 감지하기 전에 마지막 턴의 비용만큼 budget_usd를 넘어설 수 있습니다.
  • 클라이언트의 시계. 이 구간은 클라이언트의 턴 시각을 서버의 실행 시각과 비교하므로, 시계가 몇 분 어긋나면 실행 경계의 턴이 잘못 분류됩니다. 턴은 전송될 때의 시각을 유지하므로, 다시 전송한 턴은 처음 속했던 실행에 그대로 남습니다. 시각 없이(또는 해석할 수 없는 시각으로) 전송한 턴은 message_id가 기록된 시각을 사용하며, 새 턴이면 현재 시각을 사용합니다. 처음 전송 후 1초도 안 되어 다시 전송하면 현재 시각으로 기록될 수 있습니다. cost.record_turns는 서버 시계보다 5초를 넘게 앞선 시각의 턴을 turns_dated_ahead로 응답하므로, 턴을 직접 전송하는 호출자는 시계가 빠른지 확인할 수 있습니다. Claude Code 플러그인은 응답을 읽지 않고 전송합니다.
  • 하나의 세션, 여러 실행. 한 세션에서 동시에 열린 실행은 같은 턴을 봅니다. 중첩된 실행은 양쪽 모두에 합산되며, 비용 예산이 각각 필요한 동시 워커는 각자의 세션이 있어야 합니다.
  • 가격 정보가 없는 모델. 가격표에 없는 모델의 턴은 비용이 0이며, run.get은 이런 턴을 unpriced_turns로 집계하고 budget_usd에는 합산하지 않습니다.
  • MCP. MCP 도구는 budget_seconds만 제공합니다. 모델은 턴이 기록되는 세션 id를 알지 못하기 때문입니다.
  • 재시도. 다시 전송한 run.begin은 다른 재시도와 마찬가지로 실행의 행을 교체합니다. 다시 지정하지 않은 세션과 예산은 유지하고, 0이 아닌 새 예산은 기존 예산을 대체하며, 0은 기존 값을 유지합니다. 새 budget_usd는 session_id와 함께 보내야 하며(없으면 422), 새 budget_seconds는 다른 값이 필요 없습니다. 실행을 다른 세션으로 옮기는 재전송 begin은 이전 세션의 턴을 기준으로 설정된 비용 예산을 제거하고 시간 예산은 유지하며, 이를 next에 알려 줍니다. 예산을 제거하는 방법은 이것뿐입니다. run.begin이 보낸 것과 다른 run_id로 응답했다면 그 run_id를 다시 보내거나 같은 session_id를 보내세요. 그렇지 않으면 재시도가 새 실행을 엽니다.

불러왔다고 해서 의존한 것은 아니다

run.complete에는 두 개의 목록이 함께 전달됩니다.

  • memories_used — 에이전트가 실제로 의존한 키입니다. 각 키에는 used 사용 이벤트가 기록되며, 결과가 긍정적이면 evidence 이벤트가, 부정적이면 harm 이벤트가 추가로 기록됩니다. outcome의 기본값은 status에서 정해집니다. completed는 긍정, failed는 부정, cancelled는 없음입니다.
  • recalled_keys — 실행 중에 Loom의 도구가 제공한 키입니다(Claude Code와 Codex 플러그인은 loom_search와 memory.get 결과에서 이 키를 따로 보관해 두었다가 세션이 끝날 때 전송합니다). 이 키는 run.get을 위해 기록될 뿐, 보상에는 반영되지 않습니다.

반환되었지만 사용되지 않은 행은 아무런 보상도 받지 못합니다. 검색에 적중한 모든 행에 보상을 주면 가장 먼저 노출된 항목에 보상을 주는 셈이 되기 때문입니다. usage_fold 워커는 이 이벤트들을 강화 항으로 합산하며, 메모리 검색은 이 값을 기준으로 순위를 매깁니다. harm 이벤트는 얻은 가산점을 회수하되 해당 행의 작성 시점 기본값을 하한으로 하므로, 한 번의 나쁜 실행으로 행이 관련도 아래로 밀려나거나 삭제되는 일은 없습니다.

memories_used에 지정된 프로시저 키는 프로시저 원장에도 행이 추가됩니다(경로는 비어 있고 ok는 결과에서 가져옵니다). procedure.record_run을 직접 호출하는 에이전트는 실행이 두 번 집계되지 않도록 해당 키를 memories_used에서 빼야 합니다. 프로시저와 학습 내용을 참고하세요.

회고

run.complete(reflection=...)는 what_worked, what_failed, assumptions, lessons, improvements(각각 최대 20개 항목), confidence, 그리고 교훈의 근거가 되는 evidence 키를 기록합니다. 이 내용은 reflection:<run_id> 아래에 reflection 유형의 메모리 하나로 저장됩니다.

  • 임베딩되므로 이후 실행에서 memory.search(memory_type="reflection")으로 찾을 수 있지만, 필터 없는 검색과 memory.ask에서는 제외됩니다.
  • what_failed와 lessons에는 evidence 키가 하나 이상 필요합니다(없으면 422가 반환됩니다).
  • expires_in_days가 지나면 만료됩니다(기본값 90, 0은 만료 없음). 단, memory.verify나 긍정적인 결과가 있으면 만료가 갱신됩니다.
  • role(planner, executor, critic 또는 직접 정한 이름)을 지정해 시작한 실행은 회고에 role:<role> 태그를 붙이므로, 같은 역할의 에이전트가 memory.search(role=...)를 호출하면 이 회고가 우선적으로 검색됩니다.

실행이 기록한 행은 어떻게 되는가

run.complete의 retain은 해당 실행(run) 아래에서 기록된 메모리의 처리 방식을 결정합니다.

retain 효과
keep (기본값) 아무것도 변경되지 않습니다.
demote 해당 메모리의 신뢰도가 즉시 낮아집니다.
expire LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS(기본값 7)일 뒤의 만료 시점이 on_expire=demote와 함께 설정되며, memory_expiry_sweep 워커가 이를 적용합니다.

고정(pinned), 검증(verified), 승격(promoted), 잠금(locked), 에피소딕(episodic), 리플렉션(reflection) 행은 모드와 관계없이 유지되며, 어떤 모드도 행을 삭제 표시(tombstone)하지 않습니다. 기본값은 LOOM_MEMORY_RUN_COMPLETE_RETAIN에서 가져옵니다. MCP 세션의 암묵적 실행은 이를 종료하는 전송 계층이 작업의 성과를 판단할 수 없으므로 항상 유지(keep)됩니다.

평가된 실행

status는 실행이 끝났음을 알려 주고, 평가(grade)는 그 결과가 유지되었는지를 알려 줍니다. 평가는 CI가 통과하거나 리뷰어가 풀 리퀘스트를 거절하는 시점, 즉 며칠 뒤에 도착하는 경우가 많습니다. run.grade는 grade(pass 또는 fail), source(maintainer, ci, reviewer 등 자유 텍스트), reason, ref(URL, finding key, check run id)를 받으며, 하나의 run_id 또는 하나의 session_id(예: pr_1234)에 속한 종료된 모든 실행을 대상으로 지정합니다. 다시 평가하면 이전 판정을 대체하고, 같은 source가 같은 판정을 내리면 아무것도 바뀌지 않습니다. 진행 중인 실행은 건너뜁니다.

평가된 실행의 memories_used에 있는 모든 메모리는 그 평가에 반영되어 집계됩니다. 이 집계값은 memory.proposals가 시험 중인 각 사실(memory.set(proposed=true) 행) 옆에 보여 주는 값입니다. Loom이 이 값으로 제안을 결정하는 경우는 네임스페이스 소유자가 proposal_policy.mode를 auto로 설정했을 때뿐이며, 어느 모드에서든 작성자는 memory.proposal_decide로 직접 결정할 수 있습니다. 메모리 쓰기를 참고하세요.

run.list(grade="ungraded")는 아직 판정을 받지 못한 종료된 실행을 나열합니다.

MCP 세션은 요청하지 않아도 암묵적 실행(implicit run)을 갖습니다. 실행 범위를 가지는 첫 도구 호출이 실행을 시작하고, DELETE /mcp 또는 mcp_session_run_sweep 워커가 이를 종료합니다(MCP 참고). 스윕은 environment='mcp'이고 metadata.implicit가 true이며 id가 mcp- 뒤에 16진수 40자가 붙은 형태(전송 계층만 만들 수 있는 형태)인 활성 실행을 종료합니다. 종료 조건은 해당 실행의 토큰으로 이루어진 호출이(토큰을 기록하지 않는 실행이라면 누구의 호출이든) LOOM_MCP_SESSION_RUN_IDLE_SECONDS 안에 도달하지 않았을 때입니다. 이 실행은 호출자의 기본 네임스페이스에 속하므로, 그 실행을 읽는 쪽에서 보이는 내용도 그 네임스페이스 안에 머뭅니다. 실행의 goal은 mcp session (<agent>)라는 레이블이며 호출의 텍스트는 절대 들어가지 않습니다(읽기 호출의 쿼리는 호출자가 읽을 수 있는 어느 네임스페이스든 대상으로 삼을 수 있기 때문입니다). 또한 memories_written에는 그 네임스페이스의 쓰기만 나열됩니다(다른 네임스페이스의 쓰기에도 해당 run_id는 여전히 붙습니다). 종료는 아무것도 판정하지 않습니다. outcome은 none이고, 서버의 기본 retain 모드가 무엇이든 그 메모리는 유지됩니다. 따라서 두 종료가 경합하더라도(두 호스트의 스윕, 또는 DELETE) 최악의 경우 같은 완료 기록이 두 번 쓰일 뿐입니다.

실행이 여러 웹 프로세스에 걸치는 방식은 다음과 같습니다. 실행 id는 호출자의 org, 토큰의 subject, Mcp-Session-Id의 해시이므로, 서버의 모든 프로세스가 같은 세션에 대해 같은 실행을 가리키고, 다른 토큰은 같은 세션 id를 보내더라도 그 실행을 지정할 수 없습니다. 프로세스는 세션의 첫 번째로 허용된 실행 범위 호출에서 실행을 등록하고, begin 행을 백그라운드에서 씁니다(대기하는 insert는 ClickHouse Cloud에서 그 호출을 수 초간 붙잡아 둘 수 있습니다). 게이트가 거부한 호출은 실행 행을 쓰지 않습니다. 행을 찾지 못한 두 프로세스가 각각 첫 begin을 쓰면, 더 이른 시작과 그 소유자가 우선합니다(첫 begin의 행 버전은 시작 시점부터 거꾸로 세며, 이후의 모든 쓰기가 이를 대체합니다). 각 프로세스는 캐시된 실행을 원장(ledger)과 대조해 최대 1분에 한 번 확인하고, 그동안 DELETE나 스윕이 실행을 종료했다면 다시 엽니다. DELETE는 어느 프로세스에 도달하든 id로 실행을 종료하며, 종료 시에는 누가 닫든 그 id로 쓰인 모든 쓰기를 집계합니다. begin 행이 아직 기록되기 전에 다른 프로세스에 도달한 DELETE는 종료할 대상을 찾지 못하고, 이후 begin이 열린 실행으로 기록되면 스윕이 그 실행이 유휴 상태가 된 뒤 종료합니다. 짧은 재시도로는 수 초가 걸리는 begin을 감당할 수 없고, 실행을 만든 적 없는 모든 세션의 DELETE를 지연시키기 때문입니다. 다시 열린 실행은 원래의 started_at을 유지하므로, 스윕이 종료한 뒤 나중에 다시 열린 실행의 duration_ms는 중간의 공백을 포함해 세션의 첫 호출부터 계산됩니다. 삭제(erasure)로 행이 지워져 확인 시 행이 전혀 없으면 그 시점에 시작하는 새 실행을 시작하므로, 삭제 이전 날짜의 실행이 되살아나지 않습니다.

작업

작업 역할 기능
run.begin writer 실행을 시작합니다: goal(필수), user_request, expected_outcome, run_id(비어 있거나 -이면 새로 생성), session_id, role, model, metadata. 같은 run_id를 다시 보내면 해당 행을 교체하며, MCP 전송 방식의 형태(mcp- 뒤에 16진수 40자리)인 id에는 별도의 id가 부여됩니다.
run.complete writer 실행을 한 번 종료합니다: status, memories_used, recalled_keys, outcome, reflection, retain. 멱등이 아니므로 두 번 완료하면 사용 이벤트가 두 번 추가됩니다.
run.get viewer 실시간 파생 정보와 함께 실행 하나를 가져옵니다.
run.list viewer 실행 목록의 한 페이지를 가져옵니다. agent, session_id, status, grade, q, memory_activity로 필터링합니다(with는 메모리를 활용했거나 기록한 실행만, without은 메모리 활동이 없는 실행만 남기며, 필터는 limit보다 먼저 적용됩니다).
run.grade writer 종료된 실행 또는 세션의 실행들에 pass / fail 등급을 매깁니다.

run.list는 order_by(시작 시각, 소요 시간, 활용한 메모리 수를 각각 오름차순 또는 내림차순으로 지정하며, 기본값은 최신순인 started_desc)와 offset(최대 100,000)으로 페이지를 나눕니다. q는 목표, 실행 id 또는 에이전트에 해당 텍스트가 포함된 실행을 대소문자 구분 없이 남깁니다. total은 필터에 일치하는 모든 실행의 수이며, 첫 페이지 이후의 가득 찬 페이지에서는 해당 페이지만으로 알 수 없으므로 null입니다.

전체 필드 목록은 작업 레퍼런스에 있습니다. memory.outcome_run은 키를 지정하는 대신 일괄로 등급을 매기는 호출자를 위해, 실행 중 호출된 모든 메모리에 대해 helped / hurt 결과를 하나씩 기록합니다.

예시

Python SDK의 run.scope는 진입 시 실행(run)을 열고 종료 시 닫습니다. 블록 안에서 memory.ask 답변이 인용한 키와 used()에 전달된 키는 memories_used가 됩니다. 예외가 발생하면 실행은 failed(결과는 부정)로 닫힌 뒤 예외가 그대로 전파됩니다. 블록 안의 쓰기에는 해당 실행의 id가 함께 기록됩니다.

from loom import Agent

async with Agent(org="acme", namespace="support", agent="triage-bot") as agent:
    async with agent.run.scope(goal="Answer ticket 4411: refund policy for annual plans") as run:
        answer = await agent.memory.ask("what is the refund policy for annual plans?")
        run.used("policy/refunds/annual")  # relied on beyond what the answer cited
        run.final_response = answer["answer"]

    replay = await agent.run.get(run.run_id)
    print(replay["run"]["status"], replay["memories_written"], replay["recalled"])

    # Later, once the customer confirmed the answer was right:
    await agent.run.grade("pass", run_id=run.run_id, source="support-lead")

HTTP를 사용할 때 수명 주기는 두 번의 호출로 이루어집니다.

curl -sX POST "$LOOM_BASE_URL/v1/run.begin" -H "Authorization: Bearer $LOOM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"org":"acme","namespace":"support","agent":"triage-bot","goal":"Answer ticket 4411"}'
# → {"run_id":"…","status":"active","started_at":"…","next":"…"}

curl -sX POST "$LOOM_BASE_URL/v1/run.complete" -H "Authorization: Bearer $LOOM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"org":"acme","namespace":"support","run_id":"…","status":"completed",
       "memories_used":["policy/refunds/annual"]}'

Agent(auto_run=True)(또는 클라이언트 환경의 LOOM_AUTO_RUN=on)를 사용하면 첫 번째 메모리 플레인 호출 시점에 실행을 지연 생성하고, 이후의 모든 호출을 그 실행에 연결하며, Agent가 닫힐 때 결과 none으로 실행을 완료하므로 어떤 것에도 점수를 더하거나 차감하지 않습니다. 이 옵션은 기본적으로 꺼져 있습니다. 실행 중의 쓰기는 해당 실행으로 범위가 한정되어, 다른 실행의 행을 다시 서술한 내용은 병합되지 않고 duplicate로 저장되기 때문입니다.

설정

설정 효과
LOOM_MEMORY_RUN_COMPLETE_RETAIN 호출에서 retain 모드를 지정하지 않았을 때 사용하는 모드(keep)입니다.
LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS retain=expire가 만료 시점을 얼마나 먼 미래로 설정하는지를 정합니다(7일).
LOOM_SEARCH_TRACE_LOG_ENABLED 모든 검색을 해당 run_id로 기록하며, recalled는 이 기록에서 도출됩니다. 쿼리 텍스트를 로그에 남기므로 기본값은 꺼짐입니다.
LOOM_USAGE_FOLD_ENABLED 사용됨 / 근거 / 피해 이벤트를 랭킹으로 변환하는 usage_fold 워커입니다.
LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT, …_HALF_LIFE_DAYS 의존 이력이 검색에서 행의 순위를 얼마나, 얼마 동안 끌어올리는지를 정합니다.

설정: 중복 제거와 만료, 워커, 메모리 검색를 참고하세요.

제한

  • memories_used와 recalled_keys는 각각 최대 500개의 키를 받으며, goal은 최대 2,000자까지 허용됩니다.
  • memories_used의 키 중 활성 상태의 행으로 확인되지 않는 키는 아무런 효과가 없습니다. 응답의 used_applied는 확인된 키의 개수입니다.
  • run.complete는 멱등이 아닙니다. 완료를 재시도하면 사용 이벤트가 중복 집계되므로 한 번만 완료하세요.
  • SDK의 run.scope는 원장을 최선의 노력(best-effort)으로 기록합니다. run.complete가 실패해도 블록 자체의 예외가 가려지지 않으며, 완료에 실패한 실행은 active 상태로 남습니다.
  • 실행에 session_id가 없거나 클라이언트가 턴 사용량을 보고하지 않으면 turns와 cost_usd는 0입니다. 이 값은 실행이 열려 있는 동안 이루어진 턴만 집계합니다.

관련 문서

  • 장시간 실행 추적 및 재개 — run_id를 키로 하는 작업 메모리의 체크포인트와, 실행이 수행한 작업을 추적하는 방법.
  • 검색 및 질문 — 강화(reinforcement)가 순위 결정에 반영되는 방식.
  • 작업과 결정 — decision.outcome은 결정을 내린 실행이 근거로 삼은 메모리에 기여도를 부여합니다.
  • 메모리 아키텍처 — 사용 이벤트 폴드(usage-event fold)와 그 기반이 되는 테이블.

이 페이지가 도움이 되었나요?