DeepSeek Harness는 무엇을 바꿨나? AI Agent Framework에서 차세대 Coding Agent 인프라로

한눈에

계층	한 줄	당신이 유지하는 것
Agent Framework	앱 코드에서 prompt·도구·단계를 오케스트레이션	Python/TS 호출 그래프
Agent Harness	도구·FS·샌드박스·루프를 플러그인으로 올리는 런타임	Profile / Bundle / SessionEvent
DeepSeek Harness	Cordis 위의 MIT 오픈소스 dsh: 모든 것이 플러그인	ctx.* 서비스 + JSON 도구 Schema

분리를 기억하라: Framework는 chain을 주고, Harness는 교체 가능한 호스트를 준다. 모델은 바뀐다; seam과 JSON 계약은 남아야 한다.

DeepSeek Harness란 무엇인가?

DeepSeek Harness(dsh)는 LLM을 파일시스템·터미널·브라우저·기타 코딩 도구에 연결하는 오픈소스 Agent 런타임이다. 모델 가중치가 아니라, Coding Agent가 환경 안에서 계속 돌게 하는 호스트다.

먼저 세 가지:

• Everything is a Plugin: 도구, FS, 샌드박스, 모델 어댑터는 Cordis에 마운트/언마운트한다.
• 새 DeepSeek 모델이 아니다: 모델은 영혼, harness는 환경·도구·루프를 맡는 몸.
• Coding Agent 지향: Agent Loop, Session Log, Capability Seam이 일급 개념이 된다.

여전히 Agent를 「더 긴 prompt」로 본다면, 먼저 AI Agent란 무엇인가로 호스트와 계약 경계를 잡은 뒤 돌아오라. dsh가 바꾸는 것은 그 호스트 쪽이다.

Agent Framework에서 Agent Harness로

전통적인 Agent Framework는 종종 한 클래스에 Agent Loop를 묻는다. 도구 등록, 채팅 기록, 샌드박스, 재시도가 같은 호출 그래프에 굳어 교체 비용이 크다.

Harness는 루프·도구·세션을 교체 가능한 런타임 부품으로 만든다. 네 가지 차이:

• 특권 커널 vs 플러그인: 코어에 전부 넣지 않고 능력을 마운트한다.
• 채팅 기록 vs Session Log: 모델이 본 입력을 이벤트 열로 재구성한다.
• 하드코드 샌드박스 vs Capability Seam: bash·에디터를 서비스 경계에서 교체한다.
• prompt가 제품 vs 설정 합성: Profile / Bundle / 설정 트리가 제품 형태가 된다.

프레임워크는 「어떻게 체인을 쓸지」를 가르치고, harness는 「어떤 호스트에 올릴지」를 가르친다. Coding Agent의 수명은 후자에 기운다.

Everything is a Plugin: Cordis 위의 dsh

dsh는 Cordis 플러그인 호스트 위에 올라간다. 마운트와 언마운트는 가역이다. 모델 어댑터, 도구, FS, 샌드박스를 같은 방식으로 더하고 뺀다.

보통 cordis.yml(또는 patch)로 플러그인을 선언한다. 제품 코드를 다시 쓰지 않고 모델 어댑터를 바꾸는 예:

# cordis.patch.yml — swap model + add a tool
plugins:
  - name: llm/deepseek
    config:
      model: deepseek-v4-pro
  - name: tools/my-repo-search
    config:
      root: ./src

Framework와의 실무 차이다. 새 도구는 전체 포크가 아니라 플러그인으로 올린다. 제품 경계는 「어떤 플러그인 집합을 Bundle할지」로 移간다.

Capability Seam: Definition·Provider·Consumer

Capability Seam은 능력의 계약면이다. 세 역할로 나뉜다:

1. Service Definition: 이름과 입출력 형태(대개 JSON Schema / inputSchema).
2. Provider: bash, 에디터, 검색 등을 실제로 구현하는 플러그인.
3. Consumer: Agent Loop나 다른 플러그인이 ctx.*로 호출하는 쪽.

예: bash는 「셸 실행」seam의 Provider다. 루프는 Provider 내부가 아니라 정의된 인터페이스만 본다.

도구는 모델 쪽에서는 Function Calling의 tool_calls로 보이고, 호스트 쪽에서는 검증 가능한 JSON 계약이 된다. 전형적인 도구 Schema:

{
  "name": "str_replace_editor",
  "description": "Edit a file by exact string replacement",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "old_str": { "type": "string" },
      "new_str": { "type": "string" }
    },
    "required": ["path", "old_str", "new_str"],
    "additionalProperties": false
  }
}

이 경계는 MCP 도구 공급과 API측 Function Calling이 푸는 문제와 같다. 계층 구분은 MCP Tool Schema vs Function Calling, Schema를 런타임 게이트로 두는 이유는 AI는 왜 JSON Schema가 필요한가.

Session Log: 모델이 본 것을 재구성한다

채팅 UI 말풍선만으로는 부족하다. Session Log는 모델에 보인 입력, tool_calls, 도구 결과, 에이전트 이벤트를 시간순으로 남긴다.

디버그 기준은 「모델이 무엇을 봤는가」를 로그에서 재구성할 수 있는가다. 도구 결과 이벤트는 대략 이렇게 생긴다:

{
  "type": "tool/result",
  "tool_call_id": "call_7f2a",
  "name": "bash",
  "ok": true,
  "content": {
    "stdout": "passed 12",
    "exit_code": 0
  },
  "ts": "2026-09-11T06:12:04.221Z"
}

로그 JSON이 깨지면 로컬에서 포맷·구문 검사하고, 이전 성공 세션과 JSON Diff하라. 비밀·사용자 데이터를 공개 사이트에 붙이지 마라.

Profile, Bundle, 턴과 스텝

런타임 조립은 대략 네 층이다:

• Profile: web / headless 등 기동 형태와 기본 능력 세트.
• Bundle: 플러그인 집합을 쌓아 올린다. 같은 코어에 다른 Bundle로 제품 차이를 낸다.
• Turn vs Step: 사용자/에이전트 턴과 그 안의 도구 스텝을 구분한다.
• agent/* 이벤트: 루프 상태를 Session Log에 남기는 관측면.

제품 차이는 「또 다른 거대 클래스」가 아니라 Profile + Bundle 조합으로 표현한다. 루프 본체는 교체 가능하게 둔다.

네 가지 Mode: Standard / Code / Minimal / Creation

dsh는 용도별로 Mode를 바꾼다. 이름은 영어로 기억한다:

Mode는 「모델 성격」이 아니라 올리는 플러그인과 권한 묶음이다. 프로덕션은 Minimal / Standard부터, Creation은 신뢰 환경에만.

차세대 Coding Agent 인프라란

여기서 「인프라」가 가리키는 네 가지:

• Capability Seam: 능력을 계약으로 교체한다.
• Fail-closed 보안: 검증되지 않은 도구 인자는 통과시키지 않는다.
• JSON 계약: 도구 정의·호출·결과가 Schema로 맞춰진다.
• 재생 가능한 세션: Session Log로 실패를 재현한다.

긴 prompt를 자산으로 삼던 시대에서 Schema·seam·설정 트리를 자산으로 삼는 시대로 옮긴다. 구조화 워크플로 연결은 JSON Schema와 Agent 워크플로.

Framework와 Harness를 나란히 보기

같은 「Agent 실행」이라도 유지 단위가 다르다:

Framework를 버리라는 뜻이 아니다. 체인 위에 교체 가능한 호스트 층이 필요하다는 이야기다.

흔한 실수

• dsh를 새 모델로 본다. 벤치의 주인공은 모델, 운영의 주인공은 harness.
• 도구 하나 넣자고 전체 리포를 포크한다. 먼저 플러그인과 seam을 써라.
• Schema 검증을 건너뛴다. inputSchema 없는 tool_calls는 사고의 입구다.
• Session Log를 무시한다. 「모델이 이상하다」의 상당수는 본 컨텍스트 재구성 실패다.
• 신뢰할 수 없는 환경에서 Creation Mode를 연다. 자기참조 Cordis는 권한이 넓다.

FAQ

Claude Code 같은 제품과 뭐가 다른가?

Claude Code는 완성된 Coding Agent 제품에 가깝다. dsh는 교체 가능한 harness/인프라 층으로, 같은 생각을 자체 호스트에 옮기기 위한 오픈소스 기반이다.

DeepSeek 모델만 쓸 수 있나?

아니다. 모델은 어댑터로 올린다. DeepSeek 공식 데모는 자사 모델 중심이지만, 설계상 harness는 모델 교체를 전제한다.

Cordis가 필수인가?

업스트림 dsh 구현은 Cordis 플러그인 호스트 위에 있다. 사상(seam·플러그인·세션)은 이식 가능하지만, 공식 트리를 따르려면 Cordis 설정 모델을 배워야 한다.

JSON의 역할은?

도구 inputSchema, 호출 인자, 도구 결과, SessionEvent 페이로드를 실어 나른다. harness에서는 prose보다 JSON 계약이 제품 경계다.

프로덕션에 써도 되나?

지금은 developer preview에 가깝다. 파괴적 변경이 있을 수 있다. 내부 실험·스테이징부터 시작하고, seam과 Schema를 먼저 고정한 뒤 넓혀라.

정리

DeepSeek Harness가 바꾼 것은 모델 카드가 아니라 Coding Agent 인프라를 자르는 방식이다. 루프·도구·세션을 플러그인과 JSON 계약으로 만들고, 호스트를 교체 가능하게 했다.

오늘부터 Schema와 Capability Seam을 먼저 써라. prompt를 늘리지 마라. 모델은 바뀌고, harness 계약은 남는다.

더 읽기

• AI Agent란? Tool Calling과 JSON 호스트와 계약 경계부터
• AI는 왜 JSON Schema가 필요한가 Structured Output과 Function Calling 계약
• MCP Tool Schema vs Function Calling 도구 JSON의 프로토콜 경계
• AI Agent가 JSON Schema를 필요로 하기 시작한 이유 Tool Calling에서 구조화 워크플로까지
• JSONSort 로컬 도구함 포맷, 검증, Diff
• 모든 글 JSON과 AI 개발 노트

변경 기록: 2026-09-11 최초 게시