Agent-harness-kit: MCP 기반 멀티 에이전트 워크플로우 오케스트레이션 프레임워크

TL;DR Highlight

여러 AI 에이전트가 서로 역할을 나눠 협업할 수 있도록 조율하는 scaffolding 도구로, Vite처럼 설정 없이 빠르게 멀티 에이전트 파이프라인을 구성할 수 있다.

Who Should Read

Claude Code, OpenCode 같은 AI 코딩 에이전트를 여러 개 조합해서 복잡한 작업을 자동화하고 싶은 개발자, 또는 멀티 에이전트 워크플로우를 직접 구축하다가 에이전트 간 통신과 상태 관리에서 막힌 백엔드/풀스택 개발자.

Core Mechanics

agent-harness-kit(AHK)는 Vite에서 영감을 받은 AI 에이전트 오케스트레이션 scaffolding 도구로, 복잡한 설정 없이 멀티 에이전트 워크플로우를 빠르게 구성하는 것을 목표로 한다.
MCP(Model Context Protocol, AI 에이전트가 외부 도구·서비스와 표준화된 방식으로 통신하는 프로토콜)를 기반으로 하며, 특정 AI 제공사에 종속되지 않는 provider-agnostic 설계를 지향한다.
현재 Claude Code와 OpenCode를 예시로 지원하며, lead 에이전트가 여러 sub-에이전트에게 작업을 위임하고 결과를 수집하는 '리드-서브 에이전트' 구조로 동작한다.
각 에이전트 간 handoff(작업 인계)는 typed state(타입이 명시된 상태값)로 이루어진다. 이 덕분에 에이전트가 반쯤 완료된 상태('draft_verified_awaiting_review' 같은 중간 상태)를 넘기는 문제를 방지할 수 있다.
기본적인 build → review 같은 선형 파이프라인 외에, 더 복잡한 조건 분기 워크플로우(예: 리뷰 결과에 따라 X를 수행하거나 end-to-end 테스트에서 build로 롤백)를 정의할 수 있는지는 아직 문서화가 부족한 상태다.
sub-에이전트가 작업 완료를 증명하는 방식이 명확하지 않다는 지적이 있다. lead 에이전트가 output을 읽어서 판단하면 사실상 lead가 모든 에이전트의 암묵적 reviewer가 되므로, 별도 review 단계의 필요성이 모호해진다.
Node.js 의존성을 가진다. 이에 대해 Node 인프라를 꺼리는 개발자로부터 부정적인 반응이 있었다.
문서가 AI를 매일 다루는 전문가 위주로 작성돼 있어, 처음 접하는 사람은 이 도구가 무엇을 해결하는지 파악하기 어렵다는 피드백이 나왔다.

Evidence

워크플로우 복잡도에 대한 의문이 제기됐다. 단순한 선형 파이프라인이 아니라 '리뷰 결과 각각에 대해 X를 실행'하거나 'end-to-end 테스트 실패 시 build 단계로 롤백'하는 복잡한 분기 로직을 정의할 수 있는지, 그리고 에이전트 없이 실행되는 중간 스텝을 지원하는지에 대한 질문이 올라왔지만 명확한 답변은 없었다.
실제 유사 시스템을 운영한 경험자가 'typed handoff가 핵심 primitive'라고 강하게 동의했다. 에이전트 상태를 'posted'처럼 명확한 터미널 상태로만 종료하고, 'blocked_quota'나 'skipped_anti_bunching' 같은 실패 상태도 명시적으로 정의하지 않으면 메인 프로그램이 무한 재시도하며 비용을 다 써버리는 문제를 직접 겪었다는 경험담을 공유했다.
lead 에이전트가 sub-에이전트 output을 읽는 구조가 사실상 LLM judge(LLM이 다른 LLM의 결과를 평가하는 방식)라는 지적이 있었다. post-condition 체크가 있는지, raw output이 아닌 typed state로 추론하는지 여부가 설계상 중요하다는 의견이 나왔다.
자동 git worktree 생성과 샌드박싱 기능이 없냐는 제안이 있었다. 댓글 작성자는 유사한 도구를 직접 만들었는데, git worktree로 에이전트별 격리 공간을 만들고 bubblewrap으로 파일시스템 수준 샌드박싱을 적용한다고 소개했다.
'provider-agnostic이라고 하는데 실제로는 Claude Code와 OpenCode만 예시로 있다'는 의구심이 제기됐고, RooCode 같은 기존 에이전트 오케스트레이션 도구와 차별점이 무엇인지에 대한 질문도 올라왔으나 충분한 답변은 없었다.

How to Apply

Claude Code나 OpenCode를 사용해 코드 작성 → 리뷰 → 테스트 단계를 자동화하고 싶다면, AHK의 lead-sub 에이전트 구조를 활용해 각 단계를 별도 sub-에이전트로 분리하고, typed handoff로 단계 간 상태를 명시적으로 전달하는 파이프라인을 구성할 수 있다.
멀티 에이전트 시스템에서 에이전트가 중간 상태로 멈추거나 무한 재시도가 발생하는 문제를 겪고 있다면, 모든 에이전트 실행 결과를 'success', 'blocked_quota', 'skipped_anti_bunching' 등의 명시적 터미널 상태로만 종료하도록 설계해서 상위 오케스트레이터가 정확히 다음 행동을 결정할 수 있게 만들어야 한다.
이 도구를 평가 중이라면, 문서가 AI 전문가 위주로 작성돼 있으므로 GitHub 저장소와 함께 ahk.cardor.dev의 예시 코드를 직접 보면서 'lead 에이전트가 typed state를 어떻게 받아서 다음 sub-에이전트에게 넘기는지' 흐름을 먼저 파악하는 것이 빠르다.
Node.js 환경을 꺼린다면 nix shell로 격리된 환경에서 먼저 테스트해볼 수 있다. 댓글 사용자들이 openspec, oh-my-codex 등 Node 기반 도구를 nix shell로 시도한 경험을 공유했다.

Terminology

MCPModel Context Protocol의 약자로, AI 에이전트가 외부 도구·데이터·서비스와 표준화된 방식으로 통신할 수 있게 해주는 프로토콜. USB 규격처럼 에이전트와 도구 사이의 공통 연결 규격이라고 보면 된다.

scaffolding새 프로젝트를 시작할 때 기본 폴더 구조, 설정 파일, 보일러플레이트 코드를 자동으로 생성해주는 도구나 방식. Vite나 create-react-app이 대표적인 예시.

typed handoff에이전트 간 작업을 인계할 때 타입이 명시된 구조체(예: TypeScript 인터페이스)로 상태를 넘기는 방식. 자유형식 텍스트 대신 스키마를 강제해서 모호한 중간 상태를 방지한다.

LLM judgeLLM(대형 언어 모델)이 다른 LLM의 출력 결과를 평가하는 패턴. 사람 대신 AI가 AI 결과물의 품질을 채점하는 방식으로, 오류가 전파될 위험이 있다.

git worktree하나의 git 저장소에서 여러 브랜치를 동시에 별도 디렉토리로 체크아웃할 수 있는 기능. 에이전트별로 독립된 작업 공간을 격리하는 데 활용할 수 있다.

provider-agnostic특정 AI 서비스 제공사(OpenAI, Anthropic 등)에 종속되지 않고, 어떤 제공사든 교체해서 사용할 수 있는 설계 방식.