Hermes Kanban Swarm 입문: AI 에이전트를 병렬 실행·검증·통합하기

이 기사를 읽으면, Hermes Kanban Swarm를 통해 여러 AI 에이전트에게 조사·검증·통합을 분담시키는 기본 설계와 CLI 실행 예시를 알 수 있습니다.

Hermes Agent에는 delegate_task라는 간편한 서브 에이전트 호출 기능이 있습니다. 짧은 조사나 리뷰라면 그것으로 충분합니다.

하지만 업무 규모가 조금 커지면 곤란해집니다.

• 조사를 3가지 방향으로 나누고 싶다
• 구현, 리뷰, 기사 작성을 별도의 역할로 넘기고 싶다
• 도중에 멈추더라도 재개할 수 있게 하고 싶다
• 인간이 도중에 코멘트를 남겨 궤도를 수정하고 싶다
• 누가 무엇을 보고 무엇을 완료했는지 나중에 추적하고 싶다

이럴 때 사용하는 것이 Hermes의 Kanban입니다. 나아가 그 위에 「병렬 worker → verifier → synthesizer」라는 정형화된 작업 그래프를 만드는 것이 hermes kanban swarm입니다.

이 기사에서는 Hermes의 Kanban Swarm를 「무엇에 사용하는지」, 「어떻게 만드는지」, 「운용 시 어디에 주의해야 하는지」까지 직접 테스트해 볼 수 있는 형태로 정리합니다.

Kanban Swarm는 어떤 태스크 그래프(Task Graph)를 만드는가

hermes kanban swarm은 기존 Kanban DB에 다음과 같은 태스크 그래프를 생성합니다.

planning root (done)
├─ worker A
├─ worker B
...

실제 의존 관계로는, root 카드는 즉시 완료 처리되며 각 worker가 병렬로 ready 상태가 됩니다. worker가 모두 끝나면 verifier가 작동할 수 있게 되며, verifier를 통과한 후에 synthesizer가 마지막 결과물을 정리합니다.

기사 작성 시점에서 Swarm은 새로운 스케줄러(Scheduler)라기보다, 기존 Kanban 커널(Kernel)에 작은 태스크 그래프를 써넣는 헬퍼(Helper)에 가까운 위치에 있습니다. 공유 블랙보드(Shared Blackboard)도 특별한 서비스가 아니라, root 태스크에 대한 구조화된 JSON 코멘트입니다. 기존의 태스크, 코멘트, 이벤트, 대시보드, 디스패처(Dispatcher)에 실을 수 있으므로 도입 시에 익혀야 할 것이 적다는 것이 장점입니다.

delegate_task와 무엇이 다른가

대략 말하자면, delegate_task는 함수 호출이고, Kanban Swarm는 업무의 흐름입니다.

관점	delegate_task	Kanban Swarm
부모의 동작	자식 태스크의 완료를 기다림	작업 큐(Queue)에 흘려보내 진행함
...

짧은 조사라면 delegate_task가 더 빠릅니다. Swarm은 조금 무겁습니다. 그 대신, 긴 작업, 다수 인원·다수 AI의 인수인계, 사후 검증에 적합합니다.

시도하기 전에 확인할 것

이 기사의 커맨드를 시도하기 전에, 최소한 다음 사항을 확인합니다.

hermes --version
hermes kanban init
hermes gateway status
...

hermes kanban init은 Kanban DB의 초기화입니다. hermes kanban assignees나 hermes profile list에 나오지 않는 profile 이름은 worker나 verifier에 지정해도 작동하지 않습니다. 처음에는 기존의 profile 이름을 사용하여 작은 검증용 Swarm부터 시작하는 것이 안전합니다.

우선 help를 확인하기

가지고 있는 Hermes에서 다음을 실행합니다.

hermes kanban swarm --help

주요 인수는 이 정도입니다. 이 기사의 CLI 예시는 인간이나 cron이 Swarm을 만들기 위한 것입니다. 디스패처(Dispatcher)에서 기동된 worker는 통상적으로 hermes kanban CLI를 호출하는 것이 아니라, kanban_* 툴 콜(Tool calls)을 통해 보드(Board)를 읽고 씁니다.

hermes kanban swarm \
[--worker PROFILE:TITLE[:SKILL,SKILL]] \
--verifier VERIFIER \
...

최소한으로 필요한 것은 goal, 1개 이상의 worker, verifier, synthesizer입니다.

최소 구성으로 시도하기

갑자기 여러 profile이나 skill을 나누기 전에, 우선 현재 존재하는 profile 이름으로 교체한 최소 예제로 시도하는 것이 편합니다. 아래에서는 default

라는 profile이 있다는 전제하에 작성되었습니다. 없다면 자신의 환경에 있는 profile 이름으로 교체해 주세요.

hermes kanban swarm "테스트용으로 두 가지 관점에서 조사하여 정리하기" \
--worker 'default:관점A를 조사하여 요점을 남김' \
--worker 'default:관점B를 조사하여 요점을 남김' \
...

--tenant sandbox

는 검증용 네임스페이스 (namespace)입니다. 필수 사항은 아니지만, 정기적인 운영이나 여러 프로젝트를 다룰 경우 나중에 필터링하기 쉬워집니다.

--json

을 붙이면 대체로 다음과 같은 ID가 반환됩니다. 실제 ID는 환경마다 다릅니다.

{
"root_id": "task_...",
"worker_ids": ["task_...", "task_..."],
...

이 root_id나 worker_ids를 사용하여 나중에 상태를 추적합니다.

예시 1: 조사 기사를 Swarm으로 만들기

예를 들어, Hermes Agent의 주간 캐치업 (catch-up) 기사를 만든다면 다음과 같이 나눌 수 있습니다.

hermes kanban swarm "Hermes Agent의 이번 주 변경 사항을 조사하여 Zenn 기사 초안 만들기" \
--worker 'researcher:공식 GitHub와 Docs의 변경점 및 근거 URL을 남김' \
--worker 'researcher:주변 OSS와 플러그인 후보를 조사함' \
...

--worker는 반복해서 지정할 수 있습니다. 인자 전체를 따옴표 (quote)로 감싸는 것이 안전합니다. TITLE에 반각 콜론 :을 넣으면 구분자로 해석되므로, 제목 내부에서는 피해야 합니다. 형식은 다음과 같습니다.

PROFILE:TITLE[:SKILL,SKILL]

PROFILE: 해당 태스크를 담당할 Hermes profile 이름 -
TITLE: Kanban 상의 태스크 이름. worker의 본문에도 사용됩니다 -
SKILL,SKILL: 해당 worker에게 부여할 skill 이름. 생략 가능합니다

여기서 사용된 profile 이름이나 skill 이름은 필자 환경의 예시입니다. 직접 실행할 때는 hermes profile list나 hermes skills list로 존재를 확인한 후, 자신의 profile 이름으로 교체해 주세요.

--idempotency-key는 매우 중요합니다. cron이나 스크립트를 통해 동일한 Swarm 생성을 재실행했을 때, 동일한 root가 중복 생성되는 것을 방지하기 쉬워집니다. 주간 기사나 정기적인 운영 시에는 넣어두는 것이 안전합니다. 기존에 아카이브(archived)되지 않은 root가 있는 경우 이를 재사용하므로, 다른 용도로 동일한 key를 재사용하지 않도록 주의하십시오.

예시 2: 구현 태스크 분해하기

애플리케이션 구현에도 사용할 수 있습니다.

hermes kanban swarm "고객 문의 폼을 구현하여 PR 만들기" \
--worker 'backend:API와 DB 저장 로직을 구현함' \
--worker 'frontend:폼 UI와 유효성 검사(validation)를 구현함' \
...

이 형태라면 backend와 frontend가 먼저 동작하며, QA도 병렬로 관점을 제시할 수 있습니다. 모든 worker가 종료된 후, reviewer가 결과물을 확인하고, integrator가 PR(Pull Request)로 정리하는 흐름입니다.

단, 구현 계열에서 사용할 경우 워크스페이스 (workspace) 설계가 중요합니다. Kanban에는 scratch, dir:<path>, worktree 등의 워크스페이스 개념이 있습니다. 반면, 현재의 hermes kanban swarm CLI는 --workspace를 직접 노출하고 있지 않습니다. 결과물을 확실히 남겨야 하는 코드 변경의 경우, 일반적인 Kanban 태스크에서 worktree 또는 dir:<absolute path>를 사용하거나, Swarm 생성 측의 워크스페이스 지정 지원 여부를 확인하십시오. 처음에는 기사나 조사 메모와 같이 최종 출력이 코멘트나 요약(summary)으로 남는 용도부터 시도하는 것이 안전합니다.

Kanban Swarm의 생성 결과 확인하기

--json을 붙이면 root, workers, verifier, synthesizer의 ID가 반환됩니다. ID를 얻었다면 Kanban의 일반 명령어로 추적할 수 있습니다.

hermes kanban show <root_id>
hermes kanban show <worker_id>
hermes kanban list --status ready

worker 측에는 본문에 Swarm protocol (Swarm 프로토콜)이 추가됩니다. 거기에는 root의 공유 블랙보드 (blackboard), 형제·부모 태스크의 handoff (핸드오프)를 읽는 것, 완료 메타데이터 (metadata)에 기계 판독 가능한 사실을 두는 것, root에 구조화된 코멘트를 남기는 것이 기술됩니다.

즉, Swarm은 "만들고 끝"이 아닙니다. 각 worker가 Kanban의 코멘트나 완료 메타데이터를 사용하여, 나중에 verifier (검증기)와 synthesizer (합성기)가 읽을 수 있는 형태로 정보를 남기는 것이 전제입니다.

dispatcher가 작동하고 있는지 확인하기

Swarm은 태스크 그래프 (task graph)를 만들 뿐입니다. 실제로 worker를 기동하는 것은 Kanban dispatcher (디스패처)입니다.

Hermes 설정에서 dispatcher는 gateway (게이트웨이) 내에서 작동하는 구성이 기본입니다. 만약 태스크가 ready 상태인 채로 진행되지 않는다면, 다음을 확인합니다.

hermes gateway status
hermes kanban assignees
hermes kanban list --status ready
...

profile (프로필) 이름의 오류, workspace (워크스페이스) 문제, 연속적인 spawn (스폰) 실패 등이 있으면, 설정된 failure limit (실패 제한)에 도달한 후 dispatcher가 태스크를 auto-block (자동 차단)할 수 있습니다. 멈췄다면, 우선 hermes kanban show <task_id>로 코멘트와 이벤트를 확인하십시오. profile 이름의 실수라면 올바른 profile 이름으로 다시 만드는 것이 빠릅니다. 검증용 Swarm을 정리하고 싶다면, 불필요한 task id를 확인한 후 hermes kanban archive <task_id>로 archive (아카이브)할 수 있습니다.

verifier로 AI 에이전트 출력 검증하기

Swarm에서 가장 효과적인 것은 verifier입니다.

병렬 worker는 빠르지만, 출력의 입도 (granularity)가 맞지 않을 수 있습니다. 조사 태스크라면 URL만 붙여넣는 worker가 있는가 하면, 추측을 써버리는 worker도 있습니다. 구현 태스크라면 한쪽 worker가 전제 조건을 깨뜨리는 경우도 있습니다.

verifier는 모든 worker의 handoff와 blackboard 업데이트를 읽습니다. 충분한 증거가 있는 경우에만 태스크를 complete (완료)하며, 그때의 메타데이터 관례로서 {"gate": "pass"}와 같은 정보를 남깁니다. 부족함이 있다면 구체적으로 block (차단)합니다.

이를 중간에 배치함으로써, "병렬로 빠르게 만들었지만 마지막에 대충 섞어버리는" 사고를 줄이기 쉬워집니다.

synthesizer는 마지막 편집자

synthesizer는 verified (검증된) 출력만을 사용하여 최종 결과물을 만들도록 지시받는 역할입니다.

기사라면 본문화, 구현이라면 PR (Pull Request) 통합, 조사라면 의사결정 메모화, 영업이라면 제안서화. 여기서 중요한 것은 synthesizer에게 모든 것을 재조사하게 하지 않는 것입니다. worker와 verifier가 남긴 재료를 사용하고, 부족한 부분만을 명시합니다.

저의 운용 방식에서는 synthesizer에게 다음 사항을 반드시 요구하고 싶습니다.

• 무엇을 채택했는가
• 무엇을 버렸는가
• 어떤 정보가 미확인 상태인가
• 인간이 확인해야 할 판단 지점은 무엇인가
• 다음에 움직인다면 어떤 태스크인가

Swarm은 마법 같은 완전 자동화가 아닙니다. 마지막 정리 방식을 대충 하면, 그저 병렬 메모 제조기가 될 뿐입니다.

어떤 상황에서 사용하는가

기사 작성, 개발, 조사, 운영 개선이 동시에 진행되는 팀에서는 Swarm과 궁합이 좋습니다.

예를 들어 다음과 같은 업무에 적합합니다.

• AI 도구의 주간 캐치업 (catch-up) 기사
• OSS (오픈 소스 소프트웨어) 비교 및 채택 판단
• 고객 대상 PoC (개념 증명)의 요건 정리, 구현, 리뷰
• 기존 앱의 품질 개선 스프린트 (sprint)
• 영업 자료의 조사, 구성, 리뷰, 초안 작성
• 여러 SNS용 소재 분해 및 최종 통합

반대로, 10분 안에 끝나는 단발성 질문에는 적합하지 않습니다. Swarm을 만드는 것만으로도 약간의 부하가 있으므로, 짧은 업무까지 전부 Swarm화하면 운용이 번잡해집니다.

저는 다음과 같이 구분해서 사용합니다.

짧은 조사 · 즉석 리뷰: delegate_task
수 시간 ~ 수일간의 작업 · 인간 리뷰 포함: Kanban
병렬 조사 + 검증 + 통합 필요: Kanban Swarm
...

운용 시 주의할 점

profile 이름은 미리 정돈하기

--worker,
--verifier

、--synthesizer

에는 profile 이름을 전달합니다. 존재하지 않는 profile을 지정하면 worker 기동 시 문제가 발생합니다.

처음에는 적은 수의 profile로 시도하는 것이 좋습니다.

researcher
reviewer
writer
...

이름을 늘리는 것은 간단하지만, 역할이 모호한 profile을 늘리면 나중에 누가 무엇을 담당하는지 알 수 없게 됩니다.

--idempotency-key 사용하기

cron이나 CI에서 Swarm을 생성한다면, 동일한 작업이 중복되지 않도록 key를 넣습니다.

--idempotency-key hermes-weekly-zenn-20260525

일간·주간 단위라면 날짜를 포함합니다. 고정된 운영 방식이라면 프로젝트 ID나 issue 번호를 포함합니다. 이 부분을 소홀히 하면 동일한 Swarm이 여러 개 생성되어 나중에 정리하기 어려워집니다.

worker에게 기대하는 출력을 구체화하기

TITLE만으로 worker에게 던지면 출력이 얕아지기 쉽습니다. 현재의 CLI 형식에서는 worker 본문도 title 기반이므로, 타이틀에 결과물을 포함하면 안정적입니다.

나쁜 예:

--worker 'researcher:조사하기'

좋은 예:

--worker 'researcher:공식 Docs와 GitHub Releases를 확인하고, 변경점·근거 URL·미확인 사항을 불렛 포인트로 남길 것'

너무 긴 title은 읽기 어렵지만, "무엇을 남길 것인가"까지는 포함하는 것이 좋습니다.

무엇이든 Swarm으로 만들지 않기

Swarm은 "팀 작업"에 적합합니다. 작은 작업을 Swarm으로 만들면 관리 비용이 더 높아집니다.

망설여진다면 우선 다음과 같이 판단합니다.

• 단 하나의 답변만 필요하다면: delegate_task
• 상태를 남기고 싶다면: Kanban
• 병렬로 나누고 마지막에 검증과 통합이 필요하다면: Swarm

복사 붙여넣기용 치트 시트

용도 구분:
- 단발성 조사: delegate_task
- 상태 관리 필요: Kanban
...

요약

Hermes의 Kanban Swarm은 AI 에이전트를 늘리기 위한 화려한 연출이 아닙니다. 업무를 나누고, 남기고, 검증하고, 통합하기 위한 내실 있는 메커니즘입니다.

화려하지 않은 만큼, 실제 운영에 적용하기 쉽다는 것이 장점입니다.

AI 에이전트 운영에서 정말로 곤란한 점은 "얼마나 똑똑한가"보다 "중간 과정이 남지 않는다", "누가 무엇을 확인했는지 모른다", "마지막에 무질서하게 섞인다"와 같은 문제들입니다. Swarm은 이러한 과제에 대한 하나의 선택지가 될 수 있습니다.

우선은 기사 작성이나 조사와 같이 리스크가 낮은 업무에서 시도해 보는 것을 추천합니다. hermes kanban swarm은 실제로 Kanban DB에 태스크를 생성하므로, 처음에는 검증용 profile이나 tenant에서 구동하는 것이 안심할 수 있습니다. worker를 2개만 만들고, 이 글의 CLI 예시를 자신의 profile 이름으로 바꾸어 시도해 보세요. 잘 돌아간다면 주간 조사, 기사 작성, 개발 리뷰, 영업 자료 제작 등으로 확장해 나가는 것이 좋습니다.

AI를 한 명의 만능 어시스턴트로 사용하는 단계에서, 역할을 가진 작은 팀으로서 운영하는 단계로. Hermes의 Swarm은 그 전환을 위한 적절한 발판이 되어줄 것입니다.

참고 링크

• Hermes Agent GitHub: https://github.com/NousResearch/hermes-agent
• Hermes Agent docs: https://hermes-agent.nousresearch.com/docs/
• Kanban feature docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban
• Swarm 구현: hermes_cli/kanban_swarm.py
• Swarm CLI 정의: hermes_cli/kanban.py

Discussion