Agent-Harness-Kit으로 AI 에이전트 워크플로우 확장
단일 프롬프트 AI 어시스턴트에서 멀티 에이전트 시스템으로의 전환은 오늘날 소프트웨어 엔지니어링에서 가장 중요한 변화 중 하나입니다. 단일 에이전트가 함수 작성이나 버그 설명을 할 수 있지만, 복잡한 저장소 전체 변경은 조정된 노력이 필요합니다—전문 엔지니어링 팀을 모방한 작업 분담이 필요합니다. 그러나 이러한 조정을 위한 인프라—상태 관리, 권한 경계, 인계 프로토콜—를 설정하는 것은 종종 번거로운 수동 작업입니다.
여기에 **agent-harness-kit (ahk)**가 등장합니다. 이 도구는 AI 에이전트 오케스트레이션의 "Vite"가 되도록 설계되었습니다. 표준화된 스캐폴딩 프로세스를 제공함으로써, 개발자가 단일 에이전트들의 모음을 일관된 시스템으로 변환하는 멀티 에이전트 하네스를 빠르게 배포할 수 있게 합니다.
협업 아키텍처
핵심적으로, agent-harness-kit는 에이전트가 정의된 환경 내에서 작동하도록 하는 구조적 지원인 "harness"에 초점을 맞춥니다. 단일 단일체 에이전트에 의존하는 대신, 이 키트는 네 가지 특화된 역할을 기반으로 시스템을 스캐폴딩하며, 각 역할은 명시적인 권한 경계를 가집니다:
- Lead Orchestrator: 프로젝트 매니저. 작업을 선택하고 다른 에이전트를 조정합니다.
- Explorer (Read-Only): 연구원. 저장소를 이해하고 코드를 수정하기 전에 의존성을 매핑합니다.
- Builder (Write: src/): 구현자.
src/와tests/디렉터리만 쓰도록 제한됩니다. - Reviewer (Gatekeeper): 검증자. 테스트를 통과하지 않은 작업이 완료된 것으로 표시되지 않도록 보장합니다.
이러한 관심사 분리는 에이전트가 버그를 수정하려다 새로운 버그를 도입하고, 목표에 대한 고수준 관점 없이 그 새로운 버그를 또다시 수정하려는 "hallucination loop"를 방지합니다.
주요 기술 기능
agent-harness-kit는 단순 프롬프트를 넘어서는 여러 인프라 기본 요소들을 구현합니다:
SQLite를 단일 진실 원천으로 사용
LLM의 휘발성 컨텍스트 윈도우에 의존하는 대신, 시스템은 상태 유지를 위해 SQLite 데이터베이스를 사용합니다. 이는 에이전트 활동, 작업 상태, 조정 규칙이 저장되는 영구 메모리 레이어를 제공하여, 시스템이 실패에서 복구하고 서로 다른 에이전트 턴 간에 일관된 히스토리를 유지할 수 있게 합니다.
Model Context Protocol (MCP) 통합
키트는 내장된 MCP 서버를 포함하고 있어, 에이전트가 외부 도구 및 데이터 소스와 표준화된 방식으로 상호작용할 수 있게 합니다. 이를 통해 시스템은 공급자에 구애받지 않으며, Claude Code와 OpenCode와 같은 도구를 지원하고, MCP를 사용할 수 없는 환경에서는 Markdown 대체 방식을 제공합니다.
자동 스캐폴딩
배포는 간단한 CLI 명령(npx @cardor/agent-harness-kit init)을 통해 처리되며, 필요한 인프라를 생성합니다: 역할 정의를 위한 AGENTS.md, 타입이 지정된 구성 파일, SQLite 데이터베이스, 그리고 시스템 모니터링을 위한 health.sh 스크립트.
비판적 관점 및 엔지니어링 과제
스캐폴딩 접근 방식이 유망하지만, 커뮤니티는 에이전트 워크플로우의 장기적인 실현 가능성에 대해 여러 기술적 고려사항을 제기했습니다.
"LLM Judge" 문제
주요 비판 중 하나는 검증 프로세스와 관련됩니다. Lead 에이전트가 단순히 서브 에이전트의 출력을 읽어 작업이 완료되었는지 판단한다면, Lead는 암묵적인 리뷰어가 됩니다. 커뮤니티 멤버들이 지적했듯이, 이는 시스템이 typed state(하드 데이터)와 raw output(자연어) 중 어느 쪽을 기반으로 추론해야 하는지에 대한 질문을 제기합니다. 진정으로 견고한 시스템을 위해서는 LLM 승인에만 의존하지 않고 사후 조건을 프로그래밍 방식으로 확인해야 합니다.
상태 전이 및 오류 처리
에이전트 간 "handoff"를 관리하는 것은 악명 높은 고통 포인트입니다. 흔한 실패 모드는 "endless retry loop"이며, 에이전트가 실패했지만 구체적인 오류를 보고하지 않아 스케줄러가 무한히 재시도하게 됩니다.
"가장 까다로운 부분은 중단은 되었지만 뭔가가 깨지지는 않은 상황을 다루는 것이었습니다... 'blocked_quota'나 'blocked_no_credentials'와 같이 '이 일이 발생했으며 우리가 원한 것이 아니다'라고 말할 방법이 필요합니다."
효과적인 오케스트레이션은 에이전트가 절대 "half-states"를 작성하지 않고, 모든 실행이 문서화된 최종 상태로 종료되도록 하는 규율을 필요로 합니다.
샌드박싱 및 격리
에이전트가 로컬 환경에서 치명적인 실패를 일으키는 것을 방지하기 위해 자동 워크트리 생성 및 샌드박싱을 통합하는 것이 강력히 권장됩니다. git worktrees와 Bubblewrap 같은 도구를 사용하면 에이전트의 환경을 격리시켜, 에이전트 실험이 주요 개발 브랜치를 오염시키지 않도록 할 수 있습니다.
로드맵 및 향후 방향
프로젝트는 현재 로컬 파일 시스템을 넘어선 통합 기능을 확장하고 있습니다. Jira, Linear, and GitHub Issues에 대한 어댑터가 계획되어 있어, 에이전트 하네스가 프로젝트 관리 소프트웨어와 직접 연결되는 시스템으로 이동할 것을 시사합니다. 이를 통해 에이전트는 백로그에서 직접 작업을 가져오고 티켓에 업데이트를 푸시할 수 있게 됩니다.
"harness"를 표준화함으로써, agent-harness-kit는 멀티 에이전트 시스템에 대한 진입 장벽을 낮추고, AI 에이전트가 확장 가능하고 규율 있는 엔지니어링 팀으로 기능하는 세상에 산업을 한 걸음 더 다가가게 합니다.
SUMMARY: agent-harness-kit가 SQLite 상태와 MCP 도구를 활용하여 멀티 에이전트 오케스트레이션을 위한 표준화된 스캐폴딩을 제공하고, 단일 AI 에이전트를 넘어서는 방법을 탐구합니다.
TITLE: Agent-Harness-Kit으로 AI 에이전트 워크플로우 확장