Rust로 로컬‑퍼스트 에이전트 런타임을 만들었습니다 (기존 CLI를 래핑한 것이 왜 작동하지 않았는지)

발행: 2시간 전 (2026년 2월 22일 오전 07:59 GMT+9)

6 분 소요

원문: Dev.to

Source: Dev.to

내가 이것을 만든 이유

나는 로컬 20–30B 모델에서 동일한 실패 패턴을 계속 목격했다:

깨지기 쉬운 도구 동작
가끔 발생하는 무응답
일관성 없는 단계 실행
재생 가능한 상태 없이 디버깅하기 어려운 실패

답은 단순히 “더 좋은 모델을 선택한다”는 것이 아니었다.
답은 런타임 프로세스를 강화하는 것이었다:

명시적인 안전 게이트
결정론적 아티팩트
정책 + 승인
평가 + 베이스라인 비교
재생 + 검증

LocalAgent란

LocalAgent는 제어와 신뢰성을 중시하는 로컬‑퍼스트 에이전트 런타임 CLI입니다. 다음을 지원합니다:

로컬 제공자: LM Studio, Ollama, llama.cpp 서버
하드 게이트가 적용된 툴 호출
신뢰 워크플로우(정책, 승인, 감사)
재생 가능한 실행 아티팩트
MCP stdio 툴 소스(Playwright MCP 포함)
결정론적 평가 하니스
TUI 채팅 모드

GitHub:

Safety defaults (important)

Defaults are intentionally restrictive:

trust is off
shell is disabled
write tools are not exposed
file‑write execution is disabled

You have to explicitly enable risky capabilities.

아키텍처 (고수준)

런타임 컨텍스트 구축 (provider/model/workdir/state/settings)
프롬프트 메시지 준비 (세션/작업 메모리/지시사항, 활성화된 경우)
컴팩션 적용 (구성된 경우)
모델 호출 (스트리밍 또는 비스트리밍)

툴 호출이 반환된 경우:

TrustGate 결정 먼저 실행
허용된 경우에만 실행
툴 결과 엔벨로프 정규화
툴 결과를 모델에 다시 전달
최종 출력 또는 종료 조건이 나올 때까지 반복
재생/디버깅을 위해 아티팩트/이벤트를 최선의 노력으로 기록

이 설계는 부작용을 명시적인 게이트 뒤에 두어 실패를 검사 가능하게 합니다.

Why this is better than wrapper‑only trust

External wrappers are useful, but they’re limited when tool execution happens inside another runtime you don’t control.

With LocalAgent:

tool identity/args are first‑class internal data
policy and approvals are evaluated before side effects
event/audit/run artifacts are generated in one execution graph
replay and verification use the same runtime semantics

In short: security and reliability controls are part of the execution model, not bolted on.

빠른 시작

cargo install --path . --force
localagent init
localagent doctor --provider lmstudio
localagent --provider lmstudio --model  chat --tui

원샷 실행

localagent --provider ollama --model qwen3:8b --prompt "Summarize README.md" run

느린 하드웨어 참고사항

느린 CPU / 첫 토큰에 많이 의존하는 설정에서는 재시도가 나쁜 사용자 경험을 초래할 수 있습니다(완료되기 전에 프롬프트가 다시 전송됨). 디버깅 중에는 더 큰 타임아웃을 사용하고 재시도를 비활성화하세요:

localagent --provider llamacpp \
  --base-url http://localhost:5001/v1 \
  --model default \
  --http-timeout-ms 300000 \
  --http-stream-idle-timeout-ms 120000 \
  --http-max-retries 0 \
  --prompt "..." run

지금까지 배운 점

가장 큰 신뢰성 향상은 모델 과대광고가 아니라 프로세스 제약에서 비롯되었습니다:

제한된 작업
엄격한 출력 기대치
실행 전 인자 검증
결정론적 평가 + 베이스라인
근본 원인 디버깅을 위한 재생 가능한 아티팩트

고모호성 추론의 경우, 여전히 더 강력한 호스팅 모델로 라우팅합니다. 많은 생산성 보조 작업에 대해서는, 런타임이 체계적일 때 로컬 모델도 활용 가능합니다.

현재 문서

README: 프로젝트 개요 + 워크플로우
CLI reference: 전체 명령/플래그 맵
Provider setup guide: LM Studio / Ollama / llama.cpp
템플릿, 정책 문서, 및 평가 문서

Repo:

피드백을 받고 싶어요

도구 호출에 가장 안정적인 로컬 모델 + 런타임 조합은 무엇인가요?
어떤 프롬프트/출력 제약이 신뢰성을 가장 크게 향상시켰나요?
로컬‑우선 코딩 워크플로우가 “프로덕션‑준비 완료”처럼 느껴지게 하려면 무엇이 필요할까요?

이게 도움이 된다면, 구체적인 평가/베이스라인 워크플로우와 모델 라우팅 전략을 담은 후속 글을 작성할 수 있습니다.