DeepSeek Harness에서 설명하는 것과 같은 슈퍼 에이전트를 구축하려면 에이전트를 두 개 레이어로 나누어야 합니다. 사용자와 소통하며 작업을 디스패치하는 하나의 장기 실행 Router 세션과, 모든 도구를 갖추고 각각 단일 작업을 실행하는 여러 개의 격리된 Worker 세션입니다. 두 세션 모두 이벤트 Triggers(채팅, GitHub, CI)를 통해 입력을 받고, 후속 이벤트는 Thread별로 라우팅하며, 모든 상태를 점검하는 별도의 Watchdog을 추가합니다.
이 가이드는 DeepSeek Harness의 설계 에세이인 “Exploring Super-agent Design”의 내용을 단계별 구현 순서로 정리한 것입니다. 한 가지 주의할 점은, 해당 에세이는 정식 출시된 기능이 아닌 아키텍처를 다루고 있다는 점입니다. 에세이의 일부 내용은 dsh-superagent-prototype이라는 프로토타입 플러그인에 구현되어 있으며, 저자들은 이를 “공식 DeepSeek 제품이 아니다”라고 밝혔습니다. 아래 제시된 모든 코드 스케치는 이해를 돕기 위한 예시일 뿐 DeepSeek의 실제 코드가 아닙니다.
슈퍼 에이전트란 무엇인가?
슈퍼 에이전트는 다양한 채널(채팅, 풀 리퀘스트, CI)에서 이벤트를 수신하고, 격리된 세션에서 여러 작업을 병렬로 실행하며, 단일한 일관된 정체성을 유지한 채 사람에게 응답하는 상시 온라인(always-online) AI 팀원입니다.
문제는 에이전트 세션들이 서로 격리되어 있으며, “사람이 한 번에 집중해서 다룰 수 있는 활성 세션은 보통 3~5개에 불과하다”는 점입니다. 단일 작업의 성능은 모델 역량에 좌우되지만, 멀티태스킹은 사람의 주의 집중력(attention)에 의해 제한됩니다. 슈퍼 에이전트는 바로 이 두 번째 한계를 해결하는 것을 목표로 합니다.
슈퍼 에이전트에는 네 가지 특징이 있습니다.
- 연속성(Continuous): 메신저와 GitHub 전반에서 단 하나의 에이전트로 동작합니다. 채팅에서 플랜 A를 논의하다가 PR 댓글에서 플랜 B로 전환해도 이를 자연스럽게 파악하고 따라옵니다.
- 생산성(Productive): 여러 작업을 병렬로 실행하며, 이전 작업이 끝나기 전에도 다음 지시를 받아들입니다.
- 주도성(Proactive): 이벤트를 모니터링하다가 실제로 자신의 도움이 필요한 상황이 아니면 조용히 대기합니다.
- 지속성(Persistent): 항상 온라인 상태를 유지하며 장애 발생 시 스스로 복구합니다.
Harness 자체를 처음 접하신다면 DeepSeek Harness란 무엇인지와 Claude Code와의 비교 글부터 확인해 보세요.
슈퍼 에이전트 아키텍처: 5가지 핵심 모듈
에세이에서는 5가지 모듈을 제시합니다. 각 모듈의 역할과 구현 단계는 다음과 같습니다.
| 모듈 | 역할 | 구현 단계 |
|---|---|---|
| 2단계 계층 아키텍처 | Router가 디스패치하고, Worker가 실행 | 1 |
| 이벤트 기반 Triggers | 채팅, GitHub, CI 이벤트를 에이전트 입력으로 변환 | 2 |
| 전이중(Full-duplex), 멀티채널 | 비동기 도구, 채널 맞춤형 응답 | 4 |
| 연산, 상태, 환경 분리 | 상태 비저장 루프, DB 내 상태 저장, 머신 환경 보존 | 5 |
| Watchdog | 진행 상황과 오류를 점검하는 별도 세션 | 6 |
1단계: Router와 Worker 분리하기
Router는 하나의 장기 실행 세션입니다. 사람과의 모든 상호작용 및 작업 디스패치를 전담하며, 직접 작업을 실행하지는 않습니다. Bash 도구 없이도 동작 가능하며, 가볍고 저렴한 모델로도 충분합니다. 한 번의 Router 턴 동안 여러 Trigger가 도착하면 다음 호출 시 배치(batch)로 묶어 처리합니다. 즉, 긴 입력과 짧은 출력을 prefill 단계에서 병합합니다.
각 Worker는 작업당 하나씩 할당되는 독립된 격리 세션입니다. 모든 도구 권한과 활용 가능한 가장 강력한 모델을 부여받습니다. 사람과 직접 대화하지 않고 결과를 Router에 다시 보고합니다. Worker는 내부적으로 서브에이전트를 활용하거나 그 자체가 하나의 완전한 에이전트 팀으로 구성될 수도 있습니다.
이를 에이전트 팀과 혼동하지 마세요. 팀 리드는 밀접하게 결합된 하나의 작업을 여러 부분으로 분해하지만, Router는 서로 독립적인 작업들을 디스패치할 뿐입니다. 이 둘은 함께 조합하여 구성할 수도 있습니다.
# Illustrative sketch, not DeepSeek's code
class Router:
def on_events(self, batch): # triggers arriving mid-turn are batched
plan = self.llm_light.decide(batch) # dispatch, reply, or ignore
for task in plan.new_tasks:
Worker.spawn(task, model="strongest", tools="all", report_to=self)
for msg in plan.replies:
self.channels.send(msg) # only the Router speaks to humans
2단계: 이벤트를 Trigger로 변환하기
슈퍼 에이전트로 들어오는 모든 입력은 Trigger입니다. 채팅 메시지, GitHub 웹훅 이벤트, Slack Events API 페이로드, CI 콜백 등이 여기에 해당합니다. 하지만 이들 대부분은 모델에 도달할 필요가 없으므로, 에세이에서는 2단계 필터링 방식을 제안합니다.
- 코드 기반의 빠른 경로(Fast path): 소스, 그룹, 사용자 또는 봇 허용 목록(allowlist)을 기준으로 필터링합니다. 각 소스에는 “명시적 요청에만 응답”, “후보군”, “무시” 중 하나의 모드가 부여됩니다.
- LLM 기반의 정밀 경로(Slow path): 후보군으로 분류된 이벤트는 “이 채널에 누군가 버그를 보고하면 응답할 것”과 같이 프롬프트로 작성된 정책을 적용하는 모델로 전달됩니다.
이벤트 수신 엔드포인트는 즉시 응답을 반환하고 실제 처리는 나중에 수행해야 합니다. GitHub의 웹훅 모범 사례에서는 10초 이내에 2XX 응답을 보낼 것을 요구하지만, 모델 호출로는 이를 항상 보장하기 어렵습니다. 따라서 202 Accepted를 반환하고 Trigger를 큐에 넣은 뒤 Router가 이를 가져가 처리하도록 하세요. 이러한 계층에서의 재시도 및 멱등성 처리는 신뢰할 수 있는 웹훅 설계 가이드에서 자세히 다룹니다.
3단계: Thread 단위로 후속 이벤트 라우팅하기
Thread는 하나의 PR, 메신저 토픽, 이메일 스레드 등에서 연속적으로 발생하는 이벤트 흐름을 의미합니다. 특정 Thread의 첫 번째 이벤트에 의해 생성된 Worker는 해당 Thread를 구독합니다. 이후 발생하는 후속 이벤트는 Router 호출 없이 해당 Worker로 곧바로 전달(pass-through)됩니다.
이 매핑은 다대다(many-to-many) 관계입니다. 두 Worker가 동일한 PR을 다루는 경우 둘 다 해당 PR의 이벤트를 수신하며, 서로 직접 메시지를 주고받을 필요 없이 PR 자체를 통해 충돌을 해결할 수 있습니다.
이 단계를 건너뛰면 적지 않은 비용이 발생합니다. 에세이의 실험에 따르면 스루패스(pass-through)를 제거했을 때 Router가 내려야 하는 결정이 약 30% 증가했고 토큰 사용량도 약 37% 늘어났습니다.
4단계: 컨텍스트를 캐시로 취급하고 도구를 비동기화하기
Router가 모든 정보를 담아둘 수는 없으므로, 에세이에서는 컨텍스트를 캐시처럼 다룰 것을 제안합니다.
- 인라인(Inline): ID, 짧은 요약, 인접 메시지 등 필요할 가능성이 높은 정보만 포함합니다.
- 스필(Spill): 나머지 정보는 잘라내고(truncate), 에이전트가 찾아갈 수 있는 포인터만 남겨둡니다.
Trigger, Thread, Worker에 부여된 고유 식별자(Stable ID)는 저자들이 “회상 체인(Chain of Recall)”이라 부르는 참조 그래프를 형성합니다. 에이전트는 Trigger에서 Thread로, 다시 이를 처리한 Worker로 넘어가며 거대한 프롬프트 없이도 멀티홉(multi-hop) 회상을 수행할 수 있습니다.
다음으로 전이중(Full-duplex) 방식을 적용합니다. 블로킹 방식의 run() 도구 대신 비동기 방식의 start()와 stop()을 사용하세요. start()는 즉시 “Started”를 반환하고, 결과는 나중에 새로운 이벤트로 도착합니다. 덕분에 이전 작업이 실행 중이더라도 에이전트가 다음 지시를 바로 받아들일 수 있습니다. 에세이에 따르면 DeepSeek Harness에도 이 기능이 구현되어 있으나 기본적으로는 비활성화되어 있습니다.
마지막으로 응답을 채널 맞춤형(channel-aware)으로 구성하세요. 테스트된 규칙에 따르면 메신저 응답은 100단어 이내로 제한하고, GitHub, 이메일, 문서에는 구조화되고 밀도 높은 상세 보고서를 전달하도록 했습니다.
이는 투기적 실행(speculative execution)도 가능하게 합니다. 사용자 그룹 테스트에서는 “조용히 재현 및 수정(silently reproduce and fix)” 정책을 적용하여, 확실하게 검증된 간단한 수정 사항만 전달하고 그렇지 않은 경우에는 침묵을 유지하도록 했습니다.
5단계: 연산, 상태, 환경 분리하기
에이전트 루프는 상태를 저장하지 않는(stateless) 클라우드 컨테이너에서 실행하고, 세션 상태는 데이터베이스에 저장합니다. 작업 환경은 원래 위치에 그대로 유지됩니다. 즉, 각 머신은 경량 데몬을 실행하는데, 에세이에서는 이를 BYOM(Bring Your Own Machine)이라고 부릅니다. 루프가 다운되더라도 어디서나 재시작하여 상태를 다시 불러올 수 있으며, 저장소(repo)는 원래 머신에 안전하게 보존됩니다.
에세이에서는 Anthropic의 “Scaling Managed Agents: Decoupling the brain from the hands” 역시 자체 머신 대신 관리형 샌드박스를 대상으로 하지만 동일한 아이디어를 지향하고 있다고 언급합니다.
6단계: Watchdog 추가하기
Watchdog은 메인 시스템 외부에 스케줄링되어 주기적으로 실행되는 별도 세션입니다. API 오류를 처리하고 모델에 각 Worker가 정상적으로 진행 중인지 아니면 목표에서 벗어나고 있는지(drifting)를 질의합니다. 유지 관리자는 문제 발생 시 Watchdog에 직접 실패 원인을 물어볼 수도 있습니다. Router가 멈추더라도 모니터링 시스템까지 함께 중단되지 않도록 반드시 Router 프로세스 외부에 배치하세요.
실험 결과가 보여준 점
저자들은 약 20개의 작업 요청이 포함된 300여 개의 채팅 및 CI 메시지를 대상으로 타이머를 사용해 코딩 과정을 시뮬레이션하고, 각 환경 설정을 5회씩 실행했습니다. 저자들은 이 결과가 “참고용(indicative only)”일 뿐이라고 설명합니다.
| 구성 | p50 (분) | p95 (분) | 실행당 캐시 읽기 토큰 |
|---|---|---|---|
| 슈퍼 에이전트 | 12.4 | 15.7 | 23.2M |
| Thread 스루패스 미적용 | 12.6 | 15.5 | 31.8M |
| 단일 세션 + 서브에이전트 도구, 중립 프롬프트 | 20.4 | 29.5 | 6.1M |
| 단일 세션, 위임 우선 프롬프트 | 13.8 | 29.0 | 10.8M |
두 가지 주목할 만한 결과가 도출되었습니다. 중립적인 프롬프트를 사용할 경우 단일 세션은 5번의 실행 동안 작업을 전혀 위임하지 않았으며, 그 결과 p95 소요 시간이 슈퍼 에이전트의 거의 두 배에 달했습니다. 위임 우선(delegation-first) 프롬프트를 적용하면 중앙값(p50)은 개선되었지만 꼬리 지연 시간(p95)은 해결되지 않았습니다. 슈퍼 에이전트는 단일 세션보다 더 많은 토큰을 소모하므로, 토큰 비용을 지불하여 지연 시간 단축과 사람의 주의력 절약을 얻는 셈입니다.
두 번째 테스트에서는 Router 단독으로 부하를 주었습니다. 분당 Trigger 수가 1개에서 40개로 증가함에 따라 배치 크기는 1.0에서 2.8로 늘어났고, 요청당 처리 시간은 2.5초에서 3.9초로 증가한 반면 결정당 소요 시간은 6.4초에서 1.6초로 감소했습니다. 단일 Router가 이른 시점에 병목 현상을 일으키지 않도록 방지하는 핵심이 바로 이 배치 처리(batching)입니다.
Apidog CLI로 Trigger 수신 엔드포인트 테스트하기
모든 Trigger는 수신 엔드포인트에 도달하는 HTTP 요청으로 시작되므로, 이 엔드포인트야말로 가장 먼저 테스트해야 할 대상입니다. 엔드포인트가 PR 댓글을 누락하거나 각 이벤트마다 새로운 thread_id를 할당해 버리면 Thread 라우팅이 깨져 모든 후속 이벤트가 다시 Router를 거쳐야 합니다. 코딩 에이전트가 Apidog CLI를 사용해 해당 테스트를 직접 작성하고 실행하도록 해보세요.
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
그런 다음 에이전트에 아래 프롬프트를 전달합니다.
In Apidog project <id>, create POST /triggers/github for a GitHub
pull_request_review_comment webhook. Add a test case that sends two
comments on the same PR and asserts: status 202, a trigger_id in the
body, and the same thread_id both times. Run it against staging and
summarize any failures.
에이전트는 각 페이로드 스키마를 확인하고 JSON의 유효성을 검증한 뒤 엔드포인트와 테스트 케이스를 생성하여 실행합니다.
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <id> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <stagingEnvId> -r cli,json
동일한 apidog run 명령에 -r junit 옵션을 추가하면 파이프라인에 손쉽게 연동할 수 있습니다. 자세한 내용은 CI/CD 환경에서의 Apidog CLI 문서를 참고하세요. 사용 중인 에이전트가 DeepSeek Harness라면 이 설정 가이드를, Claude Code라면 이 문서를 확인해 보세요. Apidog 무료 플랜에서는 최대 4명의 사용자까지 지원합니다.
해결해야 할 과제
에세이에서는 아직 해결되지 않은 과제들도 제시합니다.
- Router의 확장성(Scaling) 및 부하 증가에 따른 Worker 토폴로지 선택 문제
- 회상 체인(Chain of Recall)을 넘어선 장기 기억(Long-term memory)
- 세션 없는 UX: 단일 채팅창 없이 에이전트를 제어하는 방법
- 컨텍스트 경계 및 에이전트 간 프로토콜: A2A가 유력한 후보 중 하나입니다.
- 보안: 클라우드 루프에 침투한 프롬프트 인젝션(Prompt Injection)은 연결된 모든 머신으로 확산될 수 있으며, 컨텍스트 내의 자격 증명(credentials)이 유출될 위험이 있습니다. 저자들은 에이전트가 자격 증명을 직접 보지 않고도 사용할 수 있는 방식을 지향합니다.
FAQ
슈퍼 에이전트는 바로 켜서 쓸 수 있는 DeepSeek Harness의 기능인가요? 아닙니다. 해당 에세이는 아키텍처를 설명하고 있습니다. 일부 기능은 dsh-superagent-prototype 플러그인에 존재하지만, 저자들은 이것이 공식 DeepSeek 제품이 아니라고 밝혔습니다. 전이중 도구는 구현되어 있으나 기본적으로 꺼져 있습니다.
Router에 더 가벼운 모델을 사용하는 이유는 무엇인가요? 디스패치와 사람과의 대화만 담당하며, 직접 작업을 실행하거나 Bash를 다룰 필요가 없기 때문입니다. 고난도 추론 작업은 가장 강력한 모델을 사용하는 Worker가 처리합니다.
슈퍼 에이전트와 에이전트 팀은 어떻게 다른가요? 팀 리드는 밀접하게 결합된 하나의 작업을 여러 부분으로 분해하지만, Router는 서로 독립적인 작업들을 디스패치합니다. 슈퍼 에이전트 내부의 각 Worker가 자체 에이전트 팀을 실행할 수도 있습니다.
스레드 패스스루(Thread pass-through)란 무엇인가요? PR, 메신저 토픽 또는 이메일 체인의 후속 이벤트가 해당 Thread를 담당하는 Worker로 바로 전달되어, skipp... [truncated 795 chars]