Agent-harness-kit scaffolding for multi-agent workflows (MCP, provider-agnostic)

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

Related Papers

• Show HN: ctx – Search the coding agent history already on your machine

  Claude Code, Cursor, Codex 등 코딩 에이전트가 이전 세션의 논의·결정·실패 시도를 잊지 않도록 SQLite로 인덱싱해 재사용할 수 있게 해주는 오픈소스 CLI 도구다.

• Micro-Agent: Beat Frontier Models with Collaboration Inside Model API

  vLLM 팀이 단일 모델 API 호출 뒤에서 여러 모델이 협업하는 'Micro-Agent' 개념을 공개했습니다. 별도의 에이전트 코드 없이 라우터 레이어에서 모델 조합을 실행해 GPT-4급 결과를 더 저렴하게 낼 수 있다는 아이디어입니다.

• Ornith-1.0: self-improving open-source models for agentic coding

  Gemma 4와 Qwen 3.5를 기반으로 파인튜닝한 코딩 특화 오픈소스 모델로, RL(강화학습)을 통해 스캐폴드(에이전트 실행 구조)까지 함께 최적화하는 방식을 주장하지만, 커뮤니티에서는 벤치마크 과최적화에 불과하다는 의심을 받고 있다.

• Entity Binding Failures in Tool-Augmented Agents

  AI 에이전트가 올바른 도구를 선택해도 잘못된 대상에 실행하는 'Entity Binding 실패' 문제를 정의하고, 이를 막는 실행 정책을 평가한 논문.

• Herdr: Agent multiplexer that lives in your terminal

  여러 AI 코딩 에이전트(Claude, Codex 등)를 하나의 터미널에서 동시에 실행·관리할 수 있는 Rust 기반 오픈소스 툴로, tmux처럼 세션이 유지되고 SSH로 원격 접속도 가능해 멀티 에이전트 워크플로우를 크게 단순화해준다.

• Ornith-1.0: Self-scaffolding LLMs for agentic coding

  모델이 문제 풀이 전략(scaffold)을 직접 생성하고 개선하는 자기강화 학습 프레임워크를 적용한 오픈소스 코딩 특화 LLM으로, 9B 소형 모델부터 397B 대형 모델까지 라인업을 갖추고 SWE-Bench 등 주요 벤치마크에서 Claude Opus 4.7을 능가하는 성능을 보여줬다.

Related Resources

• agent-harness-kit 공식 사이트
• aweb - 에이전트 간 통신 레이어 (댓글에서 언급된 보완 프로젝트)