DeepSeek Harness - 모든 구성 요소를 플러그인으로 만든 오픈소스 코딩 에이전트 — 아키텍처와 실전 활용 가이드
핵심은 “Everything is a Plugin” 구조로, Model Adapter와 Tool뿐 아니라 Session Log, Agent Loop 자체까지 플러그인으로 구성 고정된 Core를 직접 수정하는 대신 필요한 플러그인을 추가하거나 기존 구현을 교체해 에이전트의 동작과 실행…
왜 DeepSeek Harness인가
기존의 코딩 에이전트는 LLM 호출, 도구 실행, 컨텍스트 관리, 정책 enforcement이 한 덩어리의 코드에 결합되어 있습니다. 이 때문에 모델을 바꾸거나, 도구를 추가하거나, 정책 룰을 교체하려면 프레임워크 본체를 수정해야 했습니다. DeepSeek Harness는 모든 구성 요소를 플러그인 인터페이스로 추상화해, 한 줄의 설정 변경만으로 LLM·도구·정책을 교체할 수 있게 만들었습니다.
핵심 설계 원칙은 세 가지입니다: (1) 단일 책임 인터페이스 — 각 플러그인은 한 가지 역할만 갖습니다 (2) 런타임 결합 — 플러그인은 사전 등록이 아니라 기동 시점에 로드됩니다 (3) 관측 가능성 우선 — 모든 단계가 trace 이벤트를 발행해 post-mortem 분석이 가능합니다.
핵심 아키텍처
Harness는 다음 다섯 계층으로 구성됩니다:
- Agent Loop: 사용자 입력 → 컨텍스트 빌드 → LLM 호출 → 도구 실행 → 응답 생성의 사이클을 담당합니다.
- Plugin Registry: LLM, Tool, Policy, Storage, Hook 네 종류의 플러그인을 등록·조회합니다.
- Context Builder: 시스템 프롬프트, 도구 스키마, 메모리, 정책 가드를 종합해 LLM 입력 컨텍스트를 만듭니다.
- Tool Sandbox: 도구 실행을 격리된 환경에서 수행하고 stdout/stderr/artifact를 수집합니다.
- Policy Engine: 호출 직전·직후에 정책 룰을 검증합니다 (예: 코드 실행 전 정적 분석, 외부 API 호출 전 사용자 승인).
플러그인 인터페이스 contract
모든 플러그인은 Python 프로토콜로 다음 메서드를 구현합니다:
from harness.plugins import ToolPlugin, ToolContext
class ReadFilePlugin(ToolPlugin):
name = "read_file"
description = "지정 경로의 파일을 읽어 반환합니다."
def run(self, ctx, path):
if not ctx.policy.allows("read", path):
raise PermissionError("read blocked: " + path)
try:
content = ctx.sandbox.read(path)
ctx.hook.emit("file.read", {"path": path, "bytes": len(content)})
return content
except FileNotFoundError:
ctx.hook.emit("file.read.miss", {"path": path})
raise이 한 클래스만 등록하면 read_file 도구가 LLM에 즉시 노출됩니다. LLM은 함수 호출 형식으로 read_file(path="/repo/src/main.py")를 요청하고, Harness는 tool schema를 자동 생성해 컨텍스트에 포함합니다.
런타임 설정 — 무엇이 플러그인이고 무엇이 코어인가
사용자는 harness.yaml 파일로 어떤 플러그인을 어떤 순서로 결합할지 선언합니다. 다음은 Claude Code 스타일 에이전트를 DeepSeek 모델로 교체하는 예시입니다:
agent:
name: coding-agent
plugins:
llm:
- deepseek-coder-v3
- openai-gpt-4o-fallback
tools:
- read_file
- write_file
- shell_exec
- grep_search
policy:
- no-destructive-shell
- require-approval-http
storage:
- sqlite-memory
hook:
- trace-jsonl이 선언만으로 DeepSeek Coder가 메인 LLM, GPT-4o가 폴백, shell_exec가 destructive 명령 차단 룰과 함께 기동됩니다. 본체 코드는 단 한 줄도 수정하지 않습니다.
기존 프레임워크 대비 마이그레이션 이점
대표적인 코딩 에이전트들과 비교했을 때 DeepSeek Harness의 차별점은 명확합니다:
- 모듈 교체 비용: 다른 프레임워크는 LLM·도구 변경 시 본체 fork가 필요한 경우가 많지만, Harness는 플러그인 교체 한 줄로 끝납니다.
- 디버깅 가능성: Hook 플러그인이 모든 trace를 발행하므로
trace-jsonl플러그인만 켜도 전체 호출 흐름을 재생할 수 있습니다. - 정책 일관성: Policy Engine이 도구 호출 직전에 검증하므로, 새 도구를 추가해도 정책 룰을 재작성할 필요가 없습니다.
- 자가 진단:
harness doctor명령으로 등록된 모든 플러그인의 health를 점검하고, 잘못된 설정은 기동 단계에서 차단됩니다.
실전 활용 팁 — 첫 플러그인 만들기까지
- 도메인 한정: 처음부터 모든 기능을 플러그인화하려 하지 말고, 가장 자주 교체하고 싶은 한 가지(예: 모델)부터 시작합니다.
- 정책 먼저: 도구 플러그인을 만들기 전에 Policy 플러그인 스키마를 확정하면, 이후 모든 도구가 자동으로 검증됩니다.
- Hook로 가시화: 개발 초기에는
trace-jsonlHook을 반드시 켜고, 호출 그래프를 눈으로 확인하며 진행합니다. - 샌드박스 우선:
Tool Sandbox에 시간·메모리·네트워크 제한을 명시해 LLM이 무한 루프에 빠지거나 외부로 데이터를 유출하지 않게 막습니다. - 버전 동결: 플러그인 시그니처는 시맨틱 버저닝하고, 메이저 변경 시
migrate.py로 사용자 설정을 자동 변환합니다.
전망 — 에이전트 생태계의 인프라로
플러그인 인터페이스가 표준화되면, 커뮤니티는 모델별 어댑터, 도구별 구현, 정책 룰 세트를 npm/pip처럼 손쉽게 배포할 수 있게 됩니다. 이미 DeepSeek 측은 핵심 인터페이스를 안정화한 상태이며, 오픈소스 기여를 통해 생태계가 빠르게 확장될 가능성이 높습니다. 기업 입장에서는 vendor lock-in 없이 자체 모델·도구·정책을 조합할 수 있다는 점에서 비용·거버넌스 양면의 이점을 얻습니다.
핵심 정리
- DeepSeek Harness는 LLM·도구·정책·스토리지·Hook을 플러그인으로 추상화한 코딩 에이전트 프레임워크다.
harness.yaml만 수정하면 모델·도구·정책을 교체할 수 있고 본체 코드는 손대지 않는다.- Policy Engine이 도구 호출 직전에 검증해, 새 도구 추가 시에도 정책 일관성이 유지된다.
- Hook 플러그인이 trace 이벤트를 발행해 post-mortem 디버깅이 가능하다.
- 실전 적용 시 한 가지(모델/도구/정책)부터 시작해 점진적으로 플러그인화하는 전략이 가장 안전하다.