대형 언어 모델(Large language models)은 이해, 추론, 콘텐츠 생성에 탁월합니다. 하지만 오늘의 뉴스, 소셜 대화, 제품 가격, 기업 정보, 온체인 활동 등 실시간 정보가 필요한 작업에서는 기존 학습 지식만으로는 부족합니다.

때문에 에이전트 허스트(Agent harness)가 핵심 역할을 합니다. 모델은 사고를 담당하고, 허스트는 실제 환경에서 작업을 계속 수행하도록 유지하며, 외부 도구는 실시간 정보를 컨텍스트로 가져옵니다.

DeepSeek Harness (DSH) 및 AgentKey두 가지 보완적인 구성 요소를 담습니다. DSH는 오픈형이며 확장 가능하고 추적 가능한 에이전트 런타임을 제공하며, AgentKey는 통합된 실시간 데이터 접근 계층을 제공합니다. 두 시스템을 함께 사용하면 로컬에서 실행되는 DSH 에이전트가 웹 검색, 소셜 플랫폼 점검, 시장 및 온체인 데이터 쿼리를 수행할 수 있고, 세션 트래젝토리 내부에 전체 도구 호출 기록을 안전하게 보존할 수 있습니다.

DeepSeek Harness란 무엇인가?

DeepSeek Harness는 dsh 명령으로 호출되는 디프시크(DeepSeek)의 오픈소스 에이전트 허스트입니다. 디프시크는 모델을 에이전트의 영혼으로 규정하며, 허스트는 에이전트가 환경을 이해하고 도구를 사용하며 현실 세계에서 작업을 지속할 수 있도록 돕습니다.

DSH는 Cordis를 기반으로 하며 하나의 핵심 원칙을 따릅니다: 모든 것은 플러그인(Everything is a Plugin). 모델 어댑터, 도구, 기술, 세션, 샌드박스, 저장소, 에이전트 루프, 스케줄링, 심지어 UI까지 마운트하거나 교체하거나 재구성할 수 있습니다. 개발자는 DeepSeek Harness 소스 코드를 수정하지 않고도 구성 파일을 통해 기능 스택을 변경할 수 있습니다.

주요 장점은 다음과 같습니다:

• 설계 단계부터 컴포저블(Composable by design):플러그인과 구성 레이어를 통해 기능이 모듈식으로 조립되므로, 다양한 사용 사례에 맞는 모델, 도구, 권한 정책, 저장소 시스템, 실행 모드 등을 선택할 수 있습니다.
• 추적 가능한 실행(Traceable execution):시스템 프롬프트, 추론, 도구 호출 및 결과, 서브에이전트 스케줄링, 컨텍스트 주입 등이 읽기 전용 세션 로그에 기록되어 검사, 재개, 분기(fork), 검색, 재생을 지원합니다.
• 다중 런타임 모드(Multiple runtime modes):표준 모드는 전체 에이전트 워크플로우를 제공하고, 코드 모드는 생성된 코드가 여러 도구 호출을 오케스트레이션하도록 하며, 미니멀 모드는 집중된 모델 벤치마킹을 지원하고, 크리에이터 모드는 개발자가 런타임을 검사하고 플러그인 또는 프리셋을 구축하는 데 도움을 줍니다.
• 오픈소스 및 로컬 실행 가능(Open source and locally runnable):DSH는 MIT 라이선스로 출시되었으며, Web UI를 통해 사용하거나 소스에서 빌드하고 확장할 수 있습니다.

DSH는 현재 개발자 미리보기 버전이므로, 플러그인 API와 구성 계약에는 아직 파싱 변경 사항(breaking changes)이 발생할 수 있습니다. 프로덕션 사용자는 DSH 버전을 고정하고 업그레이드 전에 프로필, 패치, 플러그인을 검증해야 합니다.

에이전트키란 무엇인가?

에이전트키는 모델이거나 다른 채팅 보조 도구가 아닙니다. 그것은 에이전트용 외부 데이터 접근 계층입니다. 단일 MCP 연결을 통해 에이전트에 웹 검색, 콘텐츠 추출, 소셜 미디어, 금융, 전자상거래, 비즈니스 인텔리전스, 암호화폐/온체인 데이터 등의 기능을 제공합니다.

전통적인 방식은 검색, 소셜 데이터, 시장 피드, 기타 서비스마다 별도 계정과 API 키를 요구합니다. 또한 별도의 SDK, 할당량, 청구서, 장애 처리 방안도 필요합니다. 에이전트키는 이러한 통합을 하나의 계정, 하나의 공유 잔고, 하나의 에이전트용 워크플로우 아래로 통합하면서도 클라우드 상의 공급자와 도구 카탈로그를 지속적으로 업데이트합니다.

모델에게 고정된 API 동작명을 외우게 하는 대신, 에이전트키는 동적 탐색을 위해 세 가지 도구를 노출합니다:

1. find_tools사용자의 전체 의도를 사용하여 현재 카탈로그를 검색하여 적합한 도구와 호출별 비용(cost)을 반환합니다.
2. describe_tool선택된 도구의 파라미터 스키마, 필수 필드, 확정된 비용을 반환합니다.
3. execute_tool방금 확인한 스키마를 사용하여 도구를 실행합니다.

이를 통해 일관된 에이전트 워크플로우가 만들어집니다:

User request
   ↓
DSH Agent + AgentKey Skill
   ↓
find_tools → describe_tool → execute_tool
   ↓
AgentKey routes the request to an appropriate data service
   ↓
The result returns to DSH and is recorded in the session trajectory

해당 아키텍처는 다음과 같은 실용적인 장점을 제공합니다:

• 데이터 소스별 별도 통합 불필요:하나의 연결만으로 여러 카테고리의 실시간 데이터 도구를 해금할 수 있습니다.
• 지속적으로 진화하는 카탈로그:정적(hard-coded) 동작명 의존하는 대신 런타임에 기능을 탐색합니다.
• 실행 전 비용 확인 가능:에이전트가 작업을 시작하기 전 호출별 크레딧 정보를 확인할 수 있어 배치 작업 제어가 용이합니다.
• 라우팅 및 폴백(Fallback) 확보:하나의 데이터 경로가 이용 불가하면, 에이전트는 형제 인터페이스, 다른 버전, 대안 공급자를 선택할 수 있습니다.
• 단일 모델 또는 허스트에 대한 종속성 없음:에이전트키는 MCP와 기술을 지원하는 DeepSeek Harness 및 기타 에이전트를 제공할 수 있는 데이터 계층으로 작동합니다.

에이전트키와 DeepSeek Harness는 왜 잘 맞을까요?

DSH는 “에이전트는 어떻게 실행되어야 하는가?”라는 질문에 답합니다. 에이전트키는 “에이전트는 어떻게 외부 실시간 데이터를 얻어야 하는가?”라는 질문에 답합니다.

둘을 함께 사용하면 DSH는 로컬에서 질문에 답하는 것 이상을 수행합니다. 작업 이해, 외부 기능 선택, 실시간 정보 검색, 결과 교차 검증을 거친 후 답변을 생성하며, 전체 과정은 여전히 DSH의 도구 정책과 세션 추적이 관리합니다.

5분 만에 에이전트키 연동하기

단계 1: DSH 시작하기

Node.js 설치 후 DSH Web UI를 시작하세요:

npx @deepseek-ai/dsh web

기본적으로 Web UI는 http://127.0.0.1:3080 에서 시작하여 브라우저에서 열립니다.

단계 2: 에이전트키 설치하기

macOS 또는 Linux에서는 공식 설치 프로그램을 실행하고 DSH만 대상으로 지정하세요:

curl -fsSL https://agentkey.app/install.sh | bash -s -- --only dsh

Windows PowerShell에서는 다음을 실행하세요:

& ([scriptblock]::Create((irm https://agentkey.app/install.ps1))) -Only "dsh"

설치 프로그램은 두 가지 명확히 구분되고 동일한 중요한 작업을 수행합니다:

• 에이전트가 find_tools → describe_tool → execute_tool워크플로우를 따르도록 학습하려면 에이전트키 스킬을 전역으로 설치합니다.
• 에이전트키 장치코드 로그인(DS 홈 레벨 패치에 인증된 원격 MCP 구성을 기록합니다.

브라우저가 열리면 인증 절차를 완료하세요. 서버 연결, 스킬, 인증은 서로 독립적인 요소입니다. 스킬만 설치하면 MCP 도구가 생성되지 않으며, MCP 구성만 작성해도 모델이 올바른 동적 탐색 워크플로우를 따르는 것이 보장되지 않습니다.

각 작업을 명시적으로 확인하고 싶다면 다음 두 개의 수동 명령을 대신 실행하세요:

npx -y skills add chainbase-labs/agentkey -g -a universal -s agentkey -y
npx -y @agentkey/cli --auth-login --only dsh

두 번째 명령은 일반 MCP OAuth가 아닌 장치코드 흐름(device-code flow)을 사용합니다. 현재 DSH MCP Client는 Streamable HTTP 전송에 정적 헤더를 전달하지만 authProvider를 제공하지 않습니다. 따라서 에이전트키는 DeepSeek Harness가 접속하기 전에 자체 CLI를 사용하여 Bearer 토큰을 기록합니다.

단계 3: 구성 파일 위치 파악하기

에이전트키 CLI는 다음 위치에 표시된 Loader 블록을 하나 유지합니다:

${DSH_HOME:-~/.dsh}/cordis.patch.yml

이는 DSH 홈 레벨 패치이므로, 매 프로필마다 동일한 키를 중복하지 않고 현재 및 향후 프로필에 적용됩니다. 실행 중인 프로필은 HMR을 통해 변경 사항을 관찰할 수 있으며, 중지된 프로필과 향후 프로필은 다음 시작 시 로드합니다.

이것은 CLI 관리형 DeepSeek Harness MCP 연동이며, dsh plugin add를 통해 설치되는 네이티브 DeepSeek Harness 번들이 아닙니다. 실제 API 키는 로컬 홈 패치에만 존재해야 합니다. 해당 키나 구성 파일을 Git에 커밋하지 마세요.

연동이 실제로 작동하는지 확인하기

플러그인 페이지에서 Mounted 상태를 설정 완료를 증명하지 마세요. Mounted는 코르디스가 구성 행을 로드했다는 의미일 뿐, MCP가 인증되었고 도구가 동기화되었다는 것을 증명하지 않습니다.

다음 세 단계를 거쳐 연동을 검증하세요:

1. DSH → Settings → Plugins → Plugin list로 이동하여 구성된 id DSH → Settings → Plugins → Plugin list 그리고 구성된 id agentkey 을 검색하세요. 행을 확장하면 mcp-client 이 표시되며, @deepseek-ai/dsh-mcp-client 의해 백업되었는지 확인할 수 있습니다.
2. 에이전트키를 사용할 프리셋 또는 세션에서 다음 세 가지 핵심 도구가 보이는지 확인하세요:
   • mcp__agentkey__find_tools
   • mcp__agentkey__describe_tool
   • mcp__agentkey__execute_tool
3. 실시간 데이터가 필요한 작업을 제출하고, 탐색(description, 실행이 실제로 발생했는지 트래젝토리를 검사하세요.

예를 들어, DSH에 다음을 질문하세요:

에이전트키를 사용하여 오늘 최신 AI 뉴스를 찾아보세요. find_tools로 시작하고, describe_tool로 선택된 도구를 검사한 뒤 실행하여 출처와 함께 주요 현황을 요약하세요.

다음과 같이 더 실용적인 워크플로우도 시도해 보세요:

• “지난 달 동안 Reddit과 X에서 이 제품에 대한 논의를 검색한 후, 반복되는 페인 포인트와 기능 요청 사항을 요약하세요.”
• “여러 전자상거래 플랫폼에서 이 제품의 현재 가격, 리뷰, 판매 신호를 비교하세요.”
• “이 지갑의 최근 온체인 활동을 검사하고 프로토콜 및 자산 종류별로 요약하세요.”
• “기업 정보, 최근 뉴스, 시장 데이터를 결합하여 현재 기업 브리핑을 작성하세요.”

프롬프트에 공급업체 동작명을 하드코딩하지 마세요. 에이전트키 카탈로그는 지속적으로 진화하므로, find_tools 가 전체 사용자 요청에서 기능을 선택하도록 허용하는 것이 특정 인터페이스에 워크플로우를 고정하는 것보다 일반적으로 더 안정적입니다.

문제 해결(Troubleshooting)

플러그인은 Mounted 상태이지만 에이전트키 도구가 누락됨

활성 프리셋, 세션 또는 서브에이전트의 도구 허용/거부 정책을 확인하세요. 홈 패치는 MCP 클라이언트를 프로필 구성에 사용할 수 있게 하지만, 모든 컨텍스트에서 모든 도구를 노출하도록 강제하지는 않습니다. 그런 다음 MCP 연결 로그를 검사하여 인증 및 도구 동기화가 성공적으로 완료되었는지 확인하세요.

DSH에서 401 오류 반환

로컬 Bearer 토큰이 누락되었거나 유효하지 않을 수 있습니다. 인증 명령을 다시 실행하여 토큰을 회전시키고 관리 구성 블록을 교체하세요:

npx -y @agentkey/cli --auth-login --only dsh

DSH가 serverName 이미 사용 중

이전 버전의 프리셋 또는 세션이 serverName: agentkey 를 사용하는 다른 MCP 클라이언트를 포함할 수 있습니다. 레거시 구성을 처리하려면 현재 CLI를 다시 실행하세요. 기존 세션이 구버전 프리셋을 이미 로드했다면 해당 세션을 닫거나 DeepSeek Harness를 한 번 재시작하세요.

구성 파일이 예상한 위치가 아님

DS_HOMEDSH_HOME 이 설정되어 있는지 확인하세요. 설정되지 않은 경우 DSH는 ~/.dsh 에 기본값으로 설정됩니다. CLI는 성공 요약문에서 실제 대상 경로를 출력하므로 해당 경로를 기준으로 삼으세요.

원격 또는 헤드리스 환경에서 브라우저를 열 수 없음

no-browser 모드를 사용하여 CLI가 인증 URL과 QR 코드를 출력하도록 하세요:

npx -y @agentkey/cli --auth-login --only dsh --no-browser

결론

유용한 에이전트는 단순히 답변을 생성할 수 있는 모델을 넘어서야 합니다. 안정적인 런타임, 명확한 도구 경계, 추적 가능한 실행 과정, 학습 데이터 밖의 실시간 정보에 도달할 수 있는 방법이 필수적입니다.

DeepSeek Harness는 모델, 도구, 기술, 세션, 샌드박스, UI 컴포넌트를 컴포저블 허스트로 변환합니다. 에이전트키断편화된 외부 데이터 API를 에이전트가 동적으로 탐색하고 호출할 수 있는 기능으로 전환합니다. 둘을 함께 사용하면 검색, 소셜, 시장, 상거래, 비즈니스, 온체인 데이터 추가에 필요한 노력을 줄이면서 DeepSeek Harness의 개방성, 가시성, 구성 가능성을 유지합니다.

이미 DeepSeek Harness를 실험 중이라면 가장 쉬운 시작점은 에이전트키를 설치하고 현재 정보로만 답할 수 있는 질문을 DSH에 던져보는 것입니다:

curl -fsSL https://agentkey.app/install.sh | bash -s -- --only dsh

이것이 ‘많은 것을 아는’ 에이전트에서 ‘세계와 연결하여 업무를 수행하는’ 에이전트로 나아가는 첫걸음입니다.

참고 자료

• DeepSeek Harness 공식 소개
• DeepSeek Harness GitHub 저장소
• DeepSeek Harness 아키텍처 문서
• DeepSeek Harness MCP Client 전송 구현부
• 에이전트키 웹사이트
• 에이전트키 GitHub 저장소 및 DeepSeek Harness 설정 가이드