AI 튜토리얼

Dot Reflex 14B로 더 안전한 에이전트 복구 루프 구축

Dot Reflex 14B 설치 방법, CLI 또는 HTTP 서비스로 에이전트 궤적을 제출하는 방법, 10가지 제어 작업의 의미를 해석하는 방법, 배포 및 평가의 제한 사항을 준수하면서 권장 사항을 실행 하니스에 연결하는 방법을 알아보세요.

2026년 8월 29일약 15분 소요

Dot Reflex 14B의 기능

Dot Reflex 14B는 코딩 및 도구 사용 에이전트를 위한 실행 복구 컨트롤러입니다. 작업 에이전트를 대체하지 않습니다. 대신 에이전트의 실행 과정에 대한 간결한 JSON 요약을 검토하고, 주변 하네스가 다음 실행 단계를 어떻게 제어해야 하는지 권장합니다.

이 컨트롤러는 내부 아키텍처가 아닌 정규화된 실행 이벤트를 기반으로 작동하므로 GPT, Claude, Gemini, Qwen, Llama 또는 다른 모델로 구동되는 에이전트를 감독할 수 있습니다. 이번 릴리스는 Qwen3-14B-Base용 rank-64 QLoRA 어댑터입니다.

Dot Reflex는 다음 10가지 작업 중 하나를 반환합니다.

continue: 타당한 계획을 계속 진행합니다.
verify: 주장이나 위험한 가정에 대한 증거를 요청합니다.
retry_differently: 다른 명령, 매개변수 또는 방법으로 현재 시도를 반복합니다.
replan: 핵심 가정이 실패한 접근 방식을 교체합니다.
rollback: 유해한 변경 후 정상 상태로 복원합니다.
branch: 여러 가지 가능한 접근 방식을 별도의 환경에서 격리합니다.
switch_model: 지속적인 기능 또는 공급자 장애가 발생하면 다음 시도를 다른 모델로 전달합니다.
ask_human: 권한, 비밀 정보, 명확한 설명 또는 외부 결정이 필요할 때 일시 중지합니다.
stop_successfully: 충분한 증거로 완료가 뒷받침될 때 종료합니다.
stop_failure: 안전하고 승인된 복구 방법이 남아 있지 않을 때 중지합니다.

출력은 권장이며 승인이 아닙니다. 권한, 정책 집행, 도구 실행, 롤백 메커니즘 및 최종 중지 결정은 여전히 사용자의 하네스가 담당합니다.

주요 기능

프레임워크 중립적 입력: 컨트롤러는 에이전트 프레임워크가 이미 기록한 실행 이벤트로 구성된 일반 JSON을 받습니다.
기계 판독 가능한 출력: 유효한 모든 응답에는 작업, 근거, 신뢰도 값, 복구 지침 및 파싱 상태가 포함됩니다.
결정론적 생성: 참조 런타임은 탐욕적 생성을 사용합니다.
안전 우선 동작: 입력 스키마 또는 생성된 작업이 유효하지 않으면 CLI가 0이 아닌 상태 코드로 종료됩니다.
다양한 인터페이스: 명령줄에서 단일 결정을 실행하거나, 표준 입력을 통해 JSON을 전달하거나, 로컬 HTTP 엔드포인트를 호스팅할 수 있습니다.
모델 간 감독: 작업 에이전트는 Qwen을 사용할 필요가 없으며 컨트롤러와 동일한 아키텍처를 공유할 필요도 없습니다.

요구 사항 및 설치

참조 4비트 런타임에는 Linux와 NVIDIA GPU가 필요합니다. 한 번에 하나의 요청을 처리하려면 24 GB GPU가 실질적인 최소 사양이며, 40–48 GB에서는 추가 여유 공간을 확보할 수 있습니다. 이번 릴리스에는 GGUF, Ollama, MLX, CPU 또는 병합 가중치 빌드가 포함되지 않습니다.

저장소를 복제하고 Python 가상 환경을 만든 다음 런타임 종속성을 설치합니다.

git clone https://github.com/usedotai/dot-reflex.git
cd dot-reflex
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

GitHub 저장소에는 런타임, 테스트, 예제, 문서 및 평가 검증 자료가 포함되어 있습니다. 약 1.03 GB 크기의 어댑터는 Hugging Face에서 호스팅되며 처음 사용할 때 자동으로 다운로드됩니다. 고정된 Qwen3 기본 가중치도 Hugging Face에서 다운로드되어 캐시됩니다.

릴리스 검증

저장소 루트에서 Linux의 소스 페이로드를 검증합니다.

sha256sum --check SHA256SUMS

macOS에서는 다음에 해당하는 명령을 사용합니다. macOS는 참조 GPU 런타임의 지원 플랫폼으로 명시되어 있지 않다는 점에 유의하세요.

shasum -a 256 -c SHA256SUMS

모델을 로드하지 않고도 소스 매니페스트, 고정된 기본 모델 식별 정보, JSON 예제, 스키마 및 차트 검증 자료를 확인할 수 있습니다.

python3 scripts/validate_release.py

에이전트 실행 과정 준비

Dot Reflex는 원시 트랜스크립트가 아니라 간결한 스냅샷을 요구합니다. 정확한 입력 계약은 trajectory.schema.json에 정의되어 있습니다. 대부분의 에이전트 시스템에는 프레임워크별 이벤트를 이 구조로 매핑하는 소형 어댑터가 필요합니다.

예를 들어 에이전트가 비밀번호 재설정 코드를 수정하고 테스트를 실행하지 않은 채 완료를 주장했다고 가정해 보겠습니다. 실행 과정은 다음과 같을 수 있습니다.

{
  "task_summary": "Add password-reset token validation",
  "execution_history": [
    {
      "step": 1,
      "actor": "agent",
      "action": "Modified auth/reset.py and declared completion.",
      "result": "Patch applied; no verification was run."
    }
  ],
  "tool_results": [
    {
      "tool": "pytest",
      "status": "not_run",
      "summary": "Tests were never executed."
    }
  ],
  "current_state": "Code changed, but there is no evidence it works.",
  "detected_failure_signals": ["false_completion_risk"]
}

그러면 컨트롤러는 누락된 증거를 식별하고 다음과 같은 구조화된 결정을 반환할 수 있습니다.

{
  "action": "verify",
  "rationale": "The agent claimed completion without test evidence.",
  "confidence": 0.98,
  "recovery_instructions": "Run the targeted reset-token tests, then the relevant auth suite.",
  "parse_valid": true
}

하네스가 정확하게 지원할 수 있는 증거만 포함하세요. 누락되었거나 오래되었거나 오해의 소지가 있는 이벤트는 잘못된 권고를 초래할 수 있습니다.

기본 결정 실행

저장소에는 false-completion 시나리오의 예제 trajectory가 포함되어 있습니다. 이를 one-shot CLI에 제출하세요:

python3 inference.py examples/trajectory_false_completion.json \
  --adapter usedot/Dot-Reflex-14B

입력 경로로 -를 사용하면 표준 입력을 통해 trajectory를 전달할 수도 있습니다:

python3 inference.py - --adapter usedot/Dot-Reflex-14B \
  < examples/trajectory_false_completion.json

오케스트레이터에서는 프로세스 종료 상태와 반환된 parse_valid 필드를 모두 확인하세요. 0이 아닌 종료 상태는 입력 스키마 또는 생성된 action이 유효하지 않음을 의미하므로 자동 진행을 중단해야 합니다.

Dot Reflex를 로컬 HTTP 서비스로 실행하기

학습 동역학

추가 서버 종속성을 설치하고 Uvicorn으로 FastAPI 애플리케이션을 실행하세요:

python3 -m pip install -r requirements-server.txt
uvicorn serve:app --host 127.0.0.1 --port 8080

동일한 trajectory를 decision 엔드포인트에 제출하세요:

curl --fail-with-body \
  -H 'content-type: application/json' \
  --data @examples/trajectory_false_completion.json \
  http://127.0.0.1:8080/v1/decision

이 예제는 localhost에 바인딩됩니다. 서비스를 네트워크에 노출하기 전에 인증, TLS, 속도 제한, 요청 크기 제한, 감사 로깅을 추가하세요.

에이전트 루프에 컨트롤러 통합하기

생성된 모든 토큰 이후가 아니라 의미 있는 증거 게이트에서 Dot Reflex를 호출하세요. 유용한 체크포인트로는 실패한 도구 호출, 반복 action, 코드 편집, 테스트 또는 빌드 결과, 환경 변경, 완료 주장 등이 있습니다.

trajectory = harness.snapshot_for_supervisor()
decision = reflex.predict(trajectory)

if decision["action"] == "continue":
    harness.resume()
elif decision["action"] == "verify":
    harness.require_verification(
        decision["recovery_instructions"]
    )
elif decision["action"] == "ask_human":
    harness.pause_for_user(decision["rationale"])
elif decision["action"].startswith("stop_"):
    harness.stop(decision)
else:
    harness.apply_recovery_control(decision)

이 패턴은 책임을 분리합니다. Dot Reflex는 복구 필요성을 분류하고, harness는 실제 작업을 수행합니다. 예를 들어 rollback 권고는 harness에 이미 정의되고 승인된 rollback 프리미티브만 호출해야 합니다.

이 컨트롤러는 이벤트를 정규화하여 LangGraph, OpenAI Agents SDK, OpenHands, AutoGen, CrewAI, Google ADK 또는 사용자 지정 도구 루프에 연결할 수 있습니다. 이벤트 스트림을 캡처하는 래퍼나 훅이 없다면 Cursor, Claude Code, Codex CLI 또는 Aider용 즉시 사용 가능한 미들웨어가 아닙니다. 매핑 예제와 호환성 참고 사항은 INTEGRATION.md를 참조하세요.

고급 통합 팁

결정적인 검증은 가장 작은 범위로 수행하기

action이 verify인 경우 주장을 확인하거나 반박할 수 있는 가장 좁은 범위의 검사를 우선하세요. 코딩 워크플로에서는 더 큰 테스트 모음을 실행하기 전에 대상 테스트를 실행하는 방식일 수 있습니다. 결과를 기록하고 다음 증거 게이트에서 새로운 trajectory를 제출하세요.

모든 action을 명시적으로 매핑하기

알 수 없거나 지원되지 않는 action을 continue로 처리하지 마세요. 10개 action 모두에 대한 harness 동작을 정의하고, 생성된 action을 검증하며, 파싱 또는 정책 검사가 실패하면 안전하게 중단하세요.

실제 복구 프리미티브 제공하기

harness가 권고를 강제할 수 있을 때만 권고가 유용합니다. branch를 지원하는 시스템은 격리된 worktree 또는 sandbox를 생성해야 합니다. rollback을 지원하는 시스템은 정상 상태로 확인된 복구 가능한 상태를 유지해야 합니다. 멀티 모델 라우터는 switch_model을 구현할 실제 라우팅 메커니즘이 필요합니다.

민감한 결정은 사람이 통제하기

에이전트에게 권한, 비밀 정보, 명확한 설명 또는 외부 결정이 부족한 경우 ask_human을 사용하세요. 모델 출력만으로 파괴적, 금융, 의료, 법률, 보안 민감 또는 그 밖의 영향이 큰 작업을 승인하도록 허용하지 마세요.

신뢰도는 로컬 환경에 맞게 보정하기

반환된 confidence 값은 생성된 텍스트일 뿐 안전을 보장하지 않습니다. 임계값이나 자동화 정책을 적용하기 전에 자신의 환경을 대표하는 trajectory를 사용해 이를 측정하고 재보정하세요.

증거와 감사 추적 보존하기

입력 trajectory, 컨트롤러 응답, 실행된 복구 action 및 이후 결과를 저장하세요. 이러한 기록은 장애 조사를 쉽게 하고 컨트롤러가 실제 워크로드에서도 적용되는지 평가하는 데 도움이 됩니다.

평가 범위 이해하기

Dot Reflex는 합성 trajectory 6,000개로 학습되었고 합성 trajectory 600개로 검증되었습니다. 공개된 Agent Recovery Bench v0 평가에는 균형 있게 구성된 별도 보류 합성 trajectory 1,000개와 상태를 유지하는 별도 합성 복구 에피소드 200개가 포함됩니다.

이 합성 벤치마크에서 adapter는 복구 정확도 1.000, macro F1 1.000, 시뮬레이션 복구 1.000을 달성했습니다. 보고된 평균 latency는 NVIDIA H200에서 6.13초였지만, 이는 범용적인 서비스 성능 주장이 아니라 특정 실행에서 측정된 값입니다.

합성 환경에서 100%를 기록했다고 해서 보편적인 신뢰성이 입증되는 것은 아닙니다. 이 벤치마크는 SWE-bench도, 엔드투엔드 저장소 이슈 해결 테스트도, 프로덕션 시험도 아닙니다.

게시된 데이터는 벤치마크 분포에 대한 적합성을 보여 주지만, 독립적으로 작성된 장애 사례나 실제 운영 장애로의 신뢰할 수 있는 전이를 입증하지는 않습니다. 결과를 인용하거나 배포 정책을 설계하기 전에 EVALUATION.md를 검토하세요.

모델 및 런타임 세부 정보

기반 모델: Qwen/Qwen3-14B-Base.
방법: BF16 연산을 사용하는 4비트 NF4 QLoRA.
LoRA 구성: rank 64, alpha 128, dropout 0.05.
대상 모듈: 어텐션 및 MLP 프로젝션 계층.
학습 컨텍스트: 2,048 토큰.
학습 가능 파라미터: 256,901,120개, 기반 모델의 1.710%.
라이선스: 저장소 및 어댑터 파일에 Apache-2.0 적용.

Qwen 기반 모델은 별도의 업스트림 종속성입니다. 결합된 시스템을 배포하거나 운영에 사용하기 전에 해당 모델 카드와 라이선스를 검토하세요.

결론

Dot Reflex 14B는 에이전트 실행 루프에 구조화된 복구 계층을 추가합니다. GPU 런타임을 설치하고, 기존 이벤트를 궤적 스키마로 변환한 다음, CLI를 통해 하나의 결정을 테스트하는 것부터 시작하세요. 이후 HTTP 서비스를 추가하거나 사용자 지정 하네스의 증거 게이트에서 컨트롤러를 호출할 수 있습니다. 실행 권한은 하네스에 유지하고, 모든 응답을 검증하며, 감사 증거를 보존하고, 자동화를 활성화하기 전에 자체 워크로드에서 성능을 평가하세요.