DeepSeek Harness Agent Framework 분석

플러그인을 추가했는데 모델 연결부와 실행 루프까지 함께 고쳐야 하고, 오류가 나도 어느 단계에서 멈췄는지 보이지 않습니까?

가장 빠른 판단법은 DeepSeek Harness를 모델 호출기가 아니라 모델 어댑터, 도구, 세션, 에이전트 루프, 화면을 조합하는 실행 구조로 보는 것입니다. 복잡한 도구 체인과 교체 가능한 구성에는 유리하지만, 단순 질의응답에는 과한 설계가 될 수 있습니다. (공식 저장소)

이 글은 DeepSeek Harness 내부의 책임 경계를 확인하려는 에이전트 엔지니어를 위한 글입니다.
제3자 플러그인을 검토하는 프레임워크 유지 관리자와, 직접 실행 루프를 만들지 기존 Harness를 채택할지 결정하는 기술 책임자도 대상입니다.

마지막 업데이트: 2026년 8월 17일. 공식 저장소의 현재 구조 문서, 사용자 가이드, 개발자 문서를 기준으로 확인했습니다. 현재 저장소는 개발자 미리 보기 상태이며 호환성을 깨는 변경 가능성을 명시하고 있습니다. (공식 변경 기록)

먼저 확인할 기준: 플러그인 수보다 교체 경계를 봅니다

DeepSeek Harness의 핵심 가치는 “모든 것이 플러그인”이라는 문구 자체에 있지 않습니다. 실제로 어떤 기능이 독립적으로 교체되고, 어떤 기능이 이벤트와 세션 로그라는 공통 계약에 묶이는지를 확인해야 합니다.

공식 구조 문서에서 확인되는 주요 책임은 다음과 같습니다.

• 모델 어댑터는 ctx.llm에서 모델 메시지와 스트림 형식을 다룹니다.
• 도구 등록부는 ctx.tools에서 도구 스키마와 실행 파이프라인을 관리합니다.
• 세션은 추가 전용 이벤트 로그와 메모리 저장소를 담당합니다.
• 에이전트 인터페이스와 기본 실행 드라이버는 별도 구성 요소로 나뉩니다.
• 화면은 세션 이벤트와 에이전트 상태를 읽어 사용자에게 보여주는 계층입니다. (구조 문서)

이 구분은 세 가지 비용을 줄이는 데 중요합니다.

첫째, 모델 제공자를 바꿔도 도구와 세션 처리까지 다시 작성하지 않을 가능성이 커집니다.
둘째, 특정 작업에만 다른 도구 묶음이나 권한 정책을 적용할 수 있습니다.
셋째, 오류가 발생했을 때 모델 문제인지, 도구 문제인지, 세션 기록 문제인지 분리해서 조사할 수 있습니다.

반대로 간단한 챗봇이라면 이런 계층이 오히려 부담입니다. 한 번의 모델 요청과 한 번의 함수 호출만 필요하다면 플러그인 트리, 이벤트 흐름, 재개 가능한 세션을 운영하는 비용이 얻는 이익보다 클 수 있습니다.

첫 번째 단계: 프로필과 번들로 실제 구성을 재현합니다

DeepSeek Harness는 실행 시 빈 등록 목록에 여러 계층을 순서대로 쌓는 방식으로 프로필을 구성합니다. 공식 문서가 설명하는 순서는 프로필의 번들, 프로필 설정 패치, 사용자 홈의 패치, 실행 시 오버레이입니다. 패치는 기존 항목을 부분 수정하는 방식이 아니라 해당 항목의 전체 설정을 교체할 수 있으므로 주의해야 합니다.

플러그인 시스템을 검토할 때는 다음 순서로 확인하는 것이 좋습니다.

1. 기본 프로필이 어떤 번들을 불러오는지 확인합니다.
2. 각 번들이 어떤 dsh 설정 항목을 제공하는지 살핍니다.
3. 동일한 식별자를 가진 설정이 어느 계층에서 마지막으로 교체되는지 기록합니다.
4. dsh --profile web --dump-config로 실제 실행 트리를 출력합니다.
5. 플러그인을 하나만 추가한 상태에서 모델, 도구, 세션, 화면이 모두 정상적으로 등록되는지 확인합니다.
6. 플러그인을 제거한 뒤 등록 효과와 이벤트 리스너가 함께 사라지는지 검사합니다.

이 과정에서 중요한 것은 설치 성공 여부가 아닙니다. 같은 플러그인이 다른 프로필에서도 동일한 방식으로 작동하는지, 설정 패치가 기존 인증 정보나 권한 값을 조용히 덮어쓰지 않는지를 확인해야 합니다.

특히 제3자 플러그인은 이름만 보고 신뢰하면 안 됩니다. 플러그인이 파일 시스템, 셸 실행, 네트워크, 자격 증명에 접근하는지와 어떤 이벤트를 가로채는지를 별도로 검토해야 합니다. 실제 등록 방식과 개발자용 확장 지점은 공식 개발자 문서에서 함께 대조하는 편이 안전합니다.

두 번째 단계: 도구 호출 체인을 다섯 구간으로 나눕니다

AI Agent 워크플로에서 가장 많은 장애가 발생하는 부분은 모델 자체보다 도구 호출 사이의 경계입니다. DeepSeek Harness의 공식 흐름은 모델 요청, 스트리밍 응답, 도구 호출, 실행 전 처리, 실행, 실행 후 처리, 결과 기록, 다음 단계 요청으로 이어집니다.

검토 기준은 다음과 같습니다.

• 도구 선택: 모델에 노출되는 도구 이름과 설명이 실제 권한 범위와 일치해야 합니다.
• 매개 변수 생성: 스키마 검증을 통과하지 못한 입력을 실행 계층으로 넘기지 않아야 합니다.
• 실행 전 검사: 경로, 명령, 네트워크 대상, 사용자 승인 여부를 확인해야 합니다.
• 실행 결과 처리: 성공과 실패를 같은 문자열로 반환하지 말고 상태, 오류 유형, 재시도 가능 여부를 구조화해야 합니다.
• 다음 추론 전달: 결과가 세션 로그에 남고 다음 모델 요청의 이력에 포함되어야 합니다.

공식 문서는 도구 파이프라인을 여러 이벤트 구간으로 나누고, 각 구간이 다음 처리기로 넘겨지는 폭포식 흐름을 사용한다고 설명합니다. 따라서 리스너가 다음 처리기를 호출하지 않으면 도구 실행이 중단될 수 있습니다.

생산 배포에서는 다음 조건을 추가해야 합니다.

• 동일 요청이 다시 들어와도 결과가 중복 생성되지 않는 멱등성
• 오래 걸리는 작업을 중단할 수 있는 시간 제한
• 실패 원인을 구분하는 구조화된 오류
• 재시도 횟수와 재시도 대상의 명시
• 도구별 최소 권한
• 모델이 만든 경로와 명령을 실행 전 검토하는 승인 단계

도구가 파일을 수정하거나 외부 시스템에 데이터를 보내는 경우에는 “모델이 호출했다”는 사실만 기록해서는 부족합니다. 입력 매개 변수, 승인 주체, 플러그인 버전, 실행 결과, 생성된 산출물의 위치까지 남겨야 합니다.

세 번째 단계: 열린 루프와 결정형 흐름을 분리합니다

DeepSeek Harness의 한 단계는 모델 요청과 그 요청에서 발생한 도구 실행을 묶은 단위입니다. 한 번의 작업은 여러 단계를 포함할 수 있으며, 더 처리할 입력이나 도구 결과가 남아 있으면 다음 단계로 이어집니다.

이 구조는 열린 에이전트 루프에 적합합니다. 모델이 현재 결과를 보고 다음 도구를 선택하고, 필요하면 계획을 바꾸는 방식입니다. 하지만 결제 승인, 배포 승인, 개인정보 처리처럼 순서와 조건이 고정된 업무에는 그대로 맡기기 어렵습니다.

두 방식을 다음처럼 나누어 판단하면 됩니다.

실무에서는 탐색 단계만 열린 루프로 두고, 외부 변경이 발생하는 순간 결정형 상태로 전환하는 방식이 안전합니다. 예를 들어 코드 분석은 에이전트가 수행하되, 파일 삭제나 배포 명령은 승인 이벤트가 있어야만 진행하게 구성할 수 있습니다.

네 번째 단계: 세션 로그를 복구 기준으로 삼습니다

공식 구조 문서는 세션 로그를 모델이 보는 문맥의 원천으로 설명합니다. 모델 요청에 들어간 정보는 로그에서 다시 구성할 수 있어야 하며, 원시 스트리밍 이벤트도 재생과 화면 표시를 위해 보존됩니다.

이 설계는 장기 작업에서 큰 장점이 있습니다. 작업을 중단한 뒤 다시 시작할 때 마지막 대화만 저장하는 것이 아니라, 어떤 도구가 실행됐고 어떤 결과가 돌아왔는지 재구성할 수 있기 때문입니다.

다만 다음 문제는 별도로 관리해야 합니다.

• 로그가 계속 커지면 문맥 조립 비용이 증가합니다.
• 오래된 도구 결과를 모두 모델에 다시 보내면 중요한 지시가 묻힐 수 있습니다.
• 요약이나 문맥 압축이 원본 로그와 분리되면 재현성이 떨어집니다.
• 진행 중인 작업과 완료된 작업을 같은 상태로 표시하면 재개 시 중복 실행이 생길 수 있습니다.

따라서 운영 설계에서는 원본 이벤트와 모델에 전달할 요약을 분리하십시오. 원본은 감사와 복구용으로 보존하고, 모델 입력은 현재 목표에 필요한 상태만 투영해야 합니다. 새로 모델에 보여주는 정보가 있다면 세션 이벤트로 기록할 수 있는지도 확인해야 합니다.

다섯 번째 단계: 권한과 관측성을 플러그인 단위로 묶습니다

플러그인 구조의 장점은 교체성입니다. 동시에 가장 큰 위험도 교체성입니다. 플러그인이 공통 문맥에 등록되고 도구나 이벤트를 통해 실행 흐름에 접근한다면, 악성 코드뿐 아니라 잘못 구성된 코드도 넓은 영향을 줄 수 있습니다.

검토할 권한은 최소한 다음 네 가지입니다.

• 파일 읽기와 쓰기 범위
• 셸과 자식 프로세스 실행 여부
• 외부 네트워크 접근 대상
• API 키와 환경 변수 접근 여부

공식 문서에는 샌드박스 제공자, 파일 시스템 제공자, 셸 백엔드, 도구 이벤트, 텔레메트리 계층을 별도 확장 지점으로 둔 구조가 설명되어 있습니다. 플러그인 권한을 설계할 때는 최소 권한 원칙에 대한 오왑 안내도 함께 대조하십시오. 이 원칙은 플러그인에 필요한 파일과 네트워크 권한만 부여하고, 실행 범위를 넓히는 권한은 별도 승인 뒤에 두는 기준으로 사용할 수 있습니다.

관측성은 다음 순서로 기록해야 합니다.

1. 작업 식별자와 세션 식별자를 생성합니다.
2. 모델 요청에 사용한 프로필과 플러그인 버전을 기록합니다.
3. 모델이 선택한 도구와 실제 매개 변수를 저장합니다.
4. 승인 여부와 승인 주체를 남깁니다.
5. 실행 시간, 종료 상태, 표준 출력과 오류를 구분합니다.
6. 다음 추론에 어떤 결과가 전달됐는지 기록합니다.
7. 최종 산출물과 복구 지점을 연결합니다.

이 정보가 없으면 “모델이 잘못 판단했다”는 결론만 남습니다. 실제로는 오래된 플러그인 설정, 누락된 도구 결과, 권한 거부, 세션 복원 실패가 원인일 수 있습니다.

적용 전 마일스톤: 생산 환경 도입 여부를 판정합니다

DeepSeek Harness는 공식 문서 기준으로 모델, 도구, 세션, 에이전트 루프, 화면을 모두 조합 가능한 계층으로 다룹니다. 하지만 저장소가 개발자 미리 보기 상태이고 호환성 변경 가능성을 명시하고 있으므로, 생산 환경 적합성을 기능 목록만으로 판단하면 안 됩니다.

다음 조건을 만족하면 도입 검토 가치가 있습니다.

• 여러 모델 제공자나 실행 백엔드를 교체해야 합니다.
• 긴 작업을 중단하고 다시 시작해야 합니다.
• 도구 호출과 승인 흐름을 세밀하게 통제해야 합니다.
• 플러그인별 권한과 버전을 관리해야 합니다.
• 실행 기록을 감사하거나 재생해야 합니다.

반대로 아래에 해당하면 더 가벼운 구현이 낫습니다.

• 사용자 질문에 모델 답변만 반환합니다.
• 함수 호출이 한 번 또는 두 번으로 끝납니다.
• 세션 복구가 필요하지 않습니다.
• 파일과 셸에 접근하지 않습니다.
• 특정 프레임워크의 내부 확장점을 운영할 인력이 없습니다.

도입 전 확인 목록

• 프로필별 실제 플러그인 트리를 출력했습니까?
• 패치가 전체 설정을 교체한다는 점을 반영했습니까?
• 도구 매개 변수와 오류 형식을 고정했습니까?
• 열린 루프의 종료 조건을 정했습니까?
• 재시도와 중복 실행 방지 규칙을 만들었습니까?
• 세션 로그에서 모델 입력을 재구성할 수 있습니까?
• 플러그인의 파일, 네트워크, 키 접근을 제한했습니까?
• 개발자 미리 보기 변경을 추적할 담당자를 지정했습니까?

단순한 대화형 서비스라면 이 확인 목록을 모두 운영할 이유가 적습니다. 반면 복잡한 도구 체인이나 장기 작업을 맡길 계획이라면, 이 절차를 생략하는 것이 나중에 더 큰 유지 비용으로 돌아옵니다.

현재 환경과 맥 실행 환경을 비교해 검증 비용을 줄입니다

이미 윈도우나 리눅스 서버에서 실험 중이라면 초기 검증은 계속할 수 있습니다. 다만 현재 환경에는 원격 셸 설정, 화면 없는 실행, 파일 권한 차이, 네트워크 정책 차이가 생길 수 있습니다. 특히 플러그인이 로컬 파일과 터미널을 함께 다룬다면 개발 환경과 배포 환경의 차이가 오류 원인이 됩니다.

맥에서 플러그인 검증을 진행하면 로컬 개발 도구와 터미널 기반 작업을 한 환경에서 확인하기 쉽고, 팀원이 동일한 작업 공간을 재현하기도 편합니다. 반면 장기간 고정 부하를 처리하거나 특정 물리 장치와 직접 연결해야 한다면 임대보다 자체 장비가 맞습니다.

아직 맥 환경을 구매하기 전이라면 맥 미니 렌탈 환경에서 플러그인 설치, 로그 보존, 원격 디버깅 조건을 먼저 확인하는 방법이 현실적입니다. 운영 중 발생하는 권한 문제와 세션 복구 문제는 맥 지원 안내도 함께 확인해 두는 편이 좋습니다.

자주 묻는 내용

DeepSeek Harness 플러그인 시스템은 어떤 방식으로 작동하나요?

공식 구조에서는 모델 연결부, 도구 등록부, 세션 저장소, 에이전트 루프, 화면 구성이 모두 플러그인으로 취급됩니다. 프로필이 여러 번들을 순서대로 쌓고 설정 패치가 각 등록 항목을 교체합니다. 따라서 새 기능을 핵심 코드에 직접 붙이기보다 서비스와 이벤트가 만나는 지점에 추가하는 방식입니다.

DeepSeek Harness의 Agent Loop는 다른 실행 방식으로 바꿀 수 있나요?

공식 문서는 기본 에이전트 루프가 교체 가능한 플러그인이라고 설명합니다. 다만 루프를 바꾸면 단계 시작, 도구 실행, 종료, 취소, 복구 이벤트의 계약까지 함께 검증해야 합니다. 설정만 바꾸는 수준인지, 실제 드라이버를 교체하는 수준인지 먼저 구분해야 하며 후자는 호환성 비용이 큽니다.

도구 호출 결과는 다음 추론 단계로 어떻게 전달되나요?

모델 요청 뒤 도구 호출이 발생하면 실행 전 검사, 실제 실행, 실행 후 처리, 결과 기록 순서를 거칩니다. 결과는 세션 이벤트 로그에 남고 다음 단계의 모델 이력으로 다시 투영됩니다. 이 구조 때문에 도구 결과를 임시 메모리에만 보관하면 재개와 재현이 깨질 수 있습니다.

DeepSeek Harness는 생산 환경에 바로 적합한가요?

현재 공식 저장소는 개발자 미리 보기이며 호환성을 깨는 변경이 있을 수 있다고 명시합니다. 따라서 통제된 내부 도구, 플러그인 검증, 장기 작업 실험에는 적합하지만 핵심 업무를 바로 맡기기에는 별도 검증이 필요합니다. 권한 격리, 로그 보존, 버전 고정, 복구 시험을 통과한 뒤 제한된 범위로 배포하는 편이 안전합니다.

현재 윈도우나 리눅스 환경만으로 플러그인을 검증하면 원격 접속, 파일 권한, 화면 없는 실행, 셸 차이 때문에 실제 배포 시 다시 확인해야 할 항목이 늘어납니다. 특히 로그 지속화와 권한 격리를 반복 검증해야 한다면 물리 맥을 바로 구매하는 것보다 초기 비용과 회수 부담이 크고, 일반 클라우드 환경은 맥 전용 개발 도구와 로컬 실행 조건을 맞추기 어렵습니다. 단기간 플러그인 검증이나 팀별 비교 테스트라면 Kvmkit의 맥 환경을 임대해 필요한 기간만 실행 조건을 확인하는 편이 더 합리적입니다. 장기 고정 부하나 물리 장치 연결이 목적일 때만 자체 장비를 우선 검토하십시오.

자주 묻는 질문