프레임워크 없는 분산 Claude Code 에이전트 협업 시스템 구축

실용적 조언

에이전트 간 협업 시 코딩 전 API 규격을 먼저 정의하도록 시스템 프롬프트를 구성하라
분산 에이전트 통신을 위해 WebSocket과 MCP를 조합하여 경량 브로커를 구축하라

섹션별 상세

오케스트레이션 프레임워크나 워크플로우 엔진 없이 최소한의 도구만으로 에이전트 시스템을 구성했다. send_message와 list_participants라는 두 가지 도구와 에이전트별 시스템 프롬프트만 사용하여 복잡한 계층 구조를 배제했다. 약 190라인의 TypeScript 코드로 구현된 이 구조는 에이전트들이 중앙 통제 없이도 상호작용할 수 있는 환경을 제공한다. 이는 복잡한 프레임워크 없이도 에이전트 간의 직접적인 통신이 가능함을 의미한다.

에이전트들이 코드를 작성하기 전 스스로 API 규격(Contract)을 협상하는 자율적인 협업 패턴이 관찰됐다. 매니저 에이전트가 작업을 할당하면 개발자 에이전트들이 엔드포인트 형태, 응답 형식, CORS 헤더 등을 피어 투 피어(P2P) 방식으로 합의한 후 병렬로 개발을 진행했다. 이러한 사전 협의 과정은 인간 개발팀의 워크플로우를 모방하며, 에이전트들이 작업의 정합성을 스스로 확보하는 능력을 증명했다.

분산 환경 구축을 위해 WebSocket 브로커와 MCP(Model Context Protocol) 채널을 활용했다. WebSocket 브로커가 메시지를 중계하고 MCP 채널이 각 에이전트의 대화 흐름에 메시지를 인라인으로 주입하여 서로 다른 머신에 있는 에이전트들이 실시간으로 소통하게 한다. Docker 컨테이너 내에서 비루트(non-root) 사용자로 실행되어 보안성을 확보하면서도 확장 가능한 인프라를 구축했다.

용어 해설

모델 컨텍스트 프로토콜(MCP): — 에이전트가 외부 도구 및 데이터 소스와 통신하기 위한 표준 프로토콜로, 이 시스템에서는 분산된 에이전트들 사이에서 메시지를 전달하고 인라인으로 대화를 주입하는 채널로 활용된다.
오케스트레이션 프레임워크(Orchestration Framework): — 여러 AI 에이전트의 실행 순서, 데이터 흐름, 상태 관리를 제어하는 소프트웨어 계층이다. 본문에서는 이러한 무거운 프레임워크 없이 에이전트 간의 직접적인 통신만으로 자율 협업을 구현했다.
API 규약(API Contract): — 소프트웨어 컴포넌트 간의 데이터 교환 방식을 정의한 상호 합의이다. 에이전트들이 실제 코드를 작성하기 전 엔드포인트와 데이터 형식을 미리 협상함으로써 병렬 개발 시 발생할 수 있는 정합성 문제를 방지한다.
웹소켓 브로커(WebSocket Broker): — 실시간 양방향 통신을 지원하는 WebSocket 프로토콜을 사용하여 분산된 에이전트들 사이에서 메시지를 중계하는 서버이다. 이를 통해 서로 다른 머신에 있는 에이전트들이 지연 없이 실시간으로 소통할 수 있는 네트워크를 형성한다.

언급된 도구

Claude Code추천

자율 코딩 에이전트

MCP (Model Context Protocol)추천

에이전트 간 메시지 전달 및 도구 연결 채널

언급된 리소스

튜토리얼Distributed Claude Code Agents Across Machines