AI 에이전트 ·

DeepSeek Harness AI Agent 개발 안내

게시 2026.08.17 약 8분

처음 DeepSeek Harness를 사용하는 개발자와 팀을 위해 가장 작은 AI Agent 실행 고리부터 시작하는 순서를 정리했습니다. 모델 연결, 도구 등록, 상태 저장, 오류 복구, 배포 전 검증까지 실제 작업 순서에 맞춰 설명합니다.

적합합니다. DeepSeek Harness AI Agent는 먼저 단일 도구와 짧은 작업으로 실행 고리를 검증할 때 선택할 만합니다. 처음부터 여러 Agent, 장기 기억, 병렬 실행을 붙이면 원인 추적이 어려워집니다. 지속 실행과 환경 격리가 필요해지는 시점에는 반복 배포가 가능한 원격 개발 환경으로 옮기는 편이 안전합니다.

이 글은 처음 DeepSeek Harness를 접하고 첫 AI Agent를 실행하려는 개발자를 위한 안내입니다. 로컬 원형을 팀용 실행 환경으로 옮기려는 개발팀과 도구 호출 성공률을 검증해야 하는 기술 책임자에게도 맞습니다.

핵심 판단: 첫 목표는 “똑똑한 Agent”가 아니라 입력을 받고, 도구를 한 번 호출하고, 결과를 돌려준 뒤 멈추는 Agent입니다.

먼저 확인할 범위와 공식 자료

DeepSeek Harness라는 이름의 구현은 하나로 고정되어 있지 않습니다. 공식 DeepSeek 자료는 API 형식, 도구 호출, 사고 모드의 동작을 설명합니다. 반면 여러 저장소에서 같은 이름을 사용하는 커뮤니티 구현도 보입니다. 따라서 저장소의 플러그인이나 명령어를 공식 기능처럼 간주하면 안 됩니다.

우리는 다음 기준으로 확인하는 것을 권합니다.

모델 이름과 기본 주소는 공식 첫 API 호출 안내에서 확인합니다.
함수형 도구 호출의 입력 형식은 공식 도구 호출 안내에 맞춥니다.
도구의 이름, 설명, 매개변수 형식은 공식 채팅 생성 문서를 기준으로 검증합니다.
사고 모드에서 도구를 사용한다면 reasoning_content를 다음 요청에도 보존해야 합니다. 이를 누락하면 공식 문서가 설명하는 400 오류가 발생할 수 있습니다. 자세한 흐름은 공식 사고 모드 안내에서 확인할 수 있습니다.
커뮤니티 저장소는 공개 구현 README처럼 별도 출처로 표시해 비교합니다.

공식 조직의 공개 저장소 목록에 특정 Harness 구현이 표시되는지와, 설치하려는 저장소의 소유자·릴리스 기록·예제 코드가 일치하는지도 함께 확인해야 합니다. 이 글은 확인되지 않은 플러그인 기능을 공식 능력으로 단정하지 않습니다. 2026년 9월 공식 저장소 deepseek-ai/deepseek-harness와 CLI dsh가 공개되었습니다. 공식 런타임을 설치하고 Web / headless를 돌리려면 DeepSeek Harness dsh 설치 튜토리얼: Web 실행, Headless, AI Coding 실측을 보세요. 이 글은 직접 짠 루프와 도구 검수만 다루며, 공식 CLI 문서를 대신하지 않습니다.

첫 시간에는 무엇부터 실행해야 할까요?

첫 실행은 파일을 수정하거나 셸 명령을 실행하지 않는 작업으로 제한합니다. 예를 들면 입력 문자열을 받아 정해진 형식의 목록으로 돌려주는 작업입니다. 이 단계에서 확인할 것은 모델의 추론 품질이 아닙니다. 요청부터 종료까지 연결되는지가 핵심입니다.

첫 단계: 작업 경계를 문장으로 고정합니다

다음 네 줄을 먼저 작성합니다.

입력: 사용자가 제공하는 값은 무엇인지 정합니다.
도구: 호출 가능한 함수는 하나만 둡니다.
출력: 성공했을 때 반환할 형식을 정합니다.
종료: 도구 결과를 받은 뒤 언제 멈출지 정합니다.

이 네 항목이 없으면 Agent Loop가 계속 다음 행동을 찾습니다. “필요하면 더 조사한다” 같은 표현은 첫 실험에서 제외합니다.

둘째 단계: 실행 구조를 네 부분으로 나눕니다

모델 연결부: API 주소, 인증 키, 모델 이름을 관리합니다.
Agent Loop: 모델 응답을 읽고 도구 호출 여부를 판단합니다.
메시지 기록: 사용자 요청, 모델 응답, 도구 결과를 순서대로 보존합니다.
작업 입구: 명령줄이나 작은 함수로 하나의 작업을 받습니다.

첫 원형에서는 이 네 부분을 한 파일에 둘 수 있습니다. 다만 각 역할을 함수로 분리해야 나중에 로그와 재시도 정책을 붙이기 쉽습니다.

간단한 흐름은 다음과 같습니다.

python

messages = [{"role": "user", "content": task}]

while True:
    reply = model_call(messages, tools=[one_tool])

    if not reply.tool_calls:
        return reply.content

    for call in reply.tool_calls:
        args = validate(call.function.arguments)
        result = run_tool(args)
        messages.append(reply.message)
        messages.append(tool_result(call.id, result))

실제 구현에서는 JSON 형식 검증, 시간 제한, 예외 기록을 반드시 추가해야 합니다. 위 코드는 구조를 확인하기 위한 축약본입니다.

DeepSeek Harness에서 사용자 도구를 어떻게 연결할까요?

도구 호출은 함수 하나를 등록하는 일로 끝나지 않습니다. 모델이 도구를 선택하는 근거는 이름, 설명, 매개변수 형식입니다. 실행 권한은 애플리케이션이 따로 통제해야 합니다.

공식 API 문서 기준으로 함수 도구는 최대 128개까지 요청에 포함할 수 있고, 함수 이름은 최대 64자까지 허용됩니다. 그러나 첫 원형에서 이 한도를 채울 이유는 없습니다. 도구가 늘수록 이름과 설명이 겹치고 잘못된 선택이 증가할 수 있기 때문입니다. 공식 도구 매개변수 설명을 기준으로 스키마를 작성합니다.

도구 등록 시 다음을 분리합니다.

설명: 언제 사용해야 하는지 씁니다.
입력 형식: 필수 값과 허용 범위를 명시합니다.
권한: 읽기 전용인지, 파일 변경이 가능한지 구분합니다.
결과 형식: 성공·실패를 같은 구조로 반환합니다.
감사 기록: 호출 시각, 입력, 출력, 소요 시간, 실패 원인을 저장합니다.

모델이 생성한 인수가 항상 유효한 것은 아닙니다. 공식 문서도 도구 인수가 잘못된 JSON이거나 정의하지 않은 매개변수를 포함할 수 있으므로 실행 전에 검증하라고 안내합니다. 따라서 run_tool() 앞에 스키마 검증 단계를 둬야 합니다.

도구 호출 결과는 단순 문자열보다 다음과 같은 구조가 좋습니다.

json

{
  "ok": false,
  "error_type": "permission_denied",
  "message": "읽기 전용 경로입니다",
  "retryable": false
}

retryable이 없으면 Agent가 권한 오류를 같은 방식으로 반복할 수 있습니다.

경험: 도구 실패 로그를 남기지 않은 Agent는 고장 난 것이 아니라, 고장 원인을 숨기는 상태입니다. 입력과 결과를 함께 저장해야 재현이 가능합니다.

긴 작업의 상태는 어떻게 나눠야 할까요?

Agent 실행 상태를 모두 대화 기록에 넣으면 처음에는 편하지만, 작업이 길어질수록 비용과 오류 가능성이 커집니다. 우리는 상태를 세 층으로 나누는 방식을 권합니다.

단기 대화 상태: 현재 요청과 직전 도구 결과를 보관합니다.
작업 상태: 단계, 재시도 횟수, 승인 여부, 마지막 성공 지점을 저장합니다.
작업 산출물: 파일, 보고서, 검사 결과처럼 다시 읽을 수 있는 결과를 별도 경로에 둡니다.

예를 들어 코딩 Agent라면 요구 분석 → 파일 탐색 → 수정 → 테스트 → 승인으로 나눕니다. 각 단계가 끝날 때 상태 파일에 단계 이름과 결과를 기록합니다. 프로세스가 중단되어도 마지막 성공 단계부터 다시 시작할 수 있습니다.

상태 정책은 미리 정합니다.

실패가 일시적이면 제한된 횟수만 재시도합니다.
파일 삭제나 배포처럼 되돌리기 어려운 작업은 사람의 확인을 요구합니다.
입력이 바뀌면 기존 상태를 이어 가지 않고 새 작업으로 만듭니다.
같은 작업을 다시 실행해도 결과가 달라지는지 확인합니다.

사고 모드에서 도구를 호출하는 경우에는 응답의 reasoning_content를 다음 요청에 그대로 전달해야 합니다. 이 필드를 대화 기록에서 임의로 제거하면 다음 호출이 실패할 수 있습니다. 공식 사고 모드 예제를 기준으로 메시지 보존 방식을 점검합니다.

언제 로컬을 떠나 원격 환경으로 옮겨야 할까요?

개인 실험은 로컬 컴퓨터로 충분할 수 있습니다. 다음 조건이 하나라도 생기면 독립된 원격 환경을 검토합니다.

작업이 수십 분 이상 이어지고 중단 뒤 복구해야 합니다.
팀원이 같은 실행 환경과 의존성을 공유해야 합니다.
API 키와 작업 파일을 개인 컴퓨터와 분리해야 합니다.
여러 작업을 동시에 실행하되 서로의 파일을 볼 수 없어야 합니다.
실행 후 작업 공간을 초기 상태로 되돌려야 합니다.

의존성 파일과 잠금 파일을 함께 관리하고, 비밀 키는 환경 변수나 비밀 저장소로 주입합니다. 작업 디렉터리는 사용자별로 분리합니다. 로그는 프로세스가 끝난 뒤에도 남겨야 합니다. 동시에 실행할 작업 수에는 상한을 둡니다.

클라우드 맥 환경을 검토하는 팀이라면 한국 클라우드 맥 대여 안내에서 접속 방식과 운영 조건을 먼저 비교할 수 있습니다. 미국 동부 사용자를 대상으로 한다면 미국 동부 클라우드 맥 대여 안내도 함께 확인하는 편이 좋습니다. 개인정보와 키 관리가 핵심인 작업은 개인정보 보호 안내의 운영 원칙과 맞춰야 합니다.

로컬과 원격 환경을 나누는 결정 조건 목록

다음 조건 분기로 로컬과 원격 환경을 나눌 수 있습니다.

단일 개발자이고 작업이 짧으며 파일 변경이 없다면 로컬에서 시작합니다.
도구가 파일을 수정하거나 셸을 실행한다면 격리된 작업 디렉터리와 복구 지점을 먼저 준비합니다.
작업 중단 뒤 이어서 실행해야 한다면 상태 저장과 로그 지속성이 있는 원격 환경을 선택합니다.
팀원이 같은 환경을 사용한다면 의존성 잠금과 접근 권한을 포함한 반복 배포 방식을 선택합니다.
동시 작업이 늘어나면 무작정 병렬화하지 말고 작업 큐와 동시 실행 제한을 추가합니다.
물리 장치나 개인 파일 접근이 필수라면 원격 대여가 적합하지 않을 수 있으므로 로컬 또는 전용 장비를 검토합니다.

원격 환경을 선택하더라도 모델 API 자체를 로컬에서 실행한다는 뜻은 아닙니다. Agent 코드, 도구, 로그, 작업 파일을 분리된 개발 환경에서 실행한다는 의미입니다.

배포 전 검증 항목

한 번의 시연 성공으로 배포를 결정하면 안 됩니다. 실제 작업 묶음을 준비하고 다음 항목을 기록합니다.

[ ] 전체 작업 중 최종 성공한 비율을 확인합니다.
[ ] 도구 매개변수가 스키마와 일치하는지 검사합니다.
[ ] 권한 오류와 네트워크 오류가 올바르게 분류되는지 봅니다.
[ ] 중단 후 마지막 성공 단계에서 복구되는지 확인합니다.
[ ] 같은 입력을 반복했을 때 결과와 산출물이 허용 범위 안에서 일치하는지 봅니다.
[ ] 로그 크기, CPU 사용량, 메모리 사용량, API 요청 수를 기록합니다.
[ ] 실패한 작업이 무한 재시도로 빠지지 않는지 확인합니다.

공식 API 문서에는 도구 호출 요청에서 strict 모드를 사용할 수 있지만, 실행 뒤에도 애플리케이션 차원의 스키마 검증을 수행하라고 안내되어 있습니다. 모델의 형식 보장이 곧 실행 권한 보장은 아닙니다.

또한 모델 호환성도 고정하지 말고 배포 설정에 기록합니다. 공식 안내에는 기존 모델 이름의 사용 중단 일정이 표시되어 있으므로, 모델 이름을 코드 곳곳에 흩어 놓지 말고 환경 설정 한 곳에서 관리해야 합니다. 공식 모델 및 API 안내를 배포 전에 다시 확인합니다.

주의: 커뮤니티 구현의 설치 명령, 플러그인 수, 명령줄 기능은 해당 저장소의 릴리스에 종속됩니다. 공식 API가 지원한다고 확인된 기능과 같은 이름의 커뮤니티 기능을 섞어 문서화하지 않아야 합니다.

마지막 업데이트: 2026년 8월 17일. 공식 API 문서, 공개 저장소 목록, 커뮤니티 구현 README와 예제 코드를 기준으로 내용을 다시 확인했습니다.

DeepSeek Harness AI Agent를 짧은 실험으로만 사용할 때는 로컬 환경이 가장 단순합니다. 반대로 긴 코딩 작업에서는 개인 컴퓨터의 중단, 의존성 차이, 작업 파일 충돌, 키 노출이 반복해서 문제가 됩니다. 이때 ZekVPS의 원격 환경을 사용하면 작업 공간을 분리하고 필요할 때 다시 준비하는 운영 방식으로 옮기기 쉽습니다. 다만 장기간 고정 부하가 계속되거나 물리 장치 접근이 필요한 경우에는 직접 장비를 운영하는 편이 더 합리적일 수 있습니다. 최소 실행 고리를 통과한 뒤 지속 시간과 동시 작업 수를 측정하고, 그 결과에 따라 ZekVPS의 원격 개발 환경을 검토하는 순서가 안전합니다.