Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 01. 18:57

내가 AI 에이전트를 역할(Role) 기반으로 조직화하는 것을 그만둔 이유 (그리고 대신 문서 교환 센터를 구축한 이유)

요약

기존 역할(Role) 중심의 멀티 에이전트 프레임워크가 가진 한계를 지적하며, 서비스 경계와 문서 교환을 중심으로 하는 AgentNexus를 제안합니다. 서비스 간 변경 사항을 명확히 전달하기 위해 차이점(diff)과 전체 컨텍스트를 동시에 제공하는 프로토콜을 핵심으로 합니다.

핵심 포인트

  • 역할 기반 조직화는 복잡한 멀티 서비스 환경에서 서비스 경계 관리에 한계가 있음
  • AgentNexus는 서비스를 일급 시민으로 취급하여 문서 네임스페이스로 관리함
  • MCP 서버를 통해 여러 에이전트가 동시 연결 가능한 구조 제공
  • Diff-Aware 프로토콜로 변경 사항과 전체 컨텍스트를 동시에 전달하여 정확도 향상

소프트웨어 개발을 위한 대부분의 멀티 에이전트 프레임워크(multi-agent frameworks)는 에이전트를 역할(roles) 중심으로 조직합니다. 즉, 제품 관리자(product manager) 에이전트, 개발자(developer) 에이전트, 테스터(tester) 에이전트와 같은 방식입니다. ChatDev와 MetaGPT가 이러한 접근 방식을 개척했으며, 이는 단일 구조(monolithic) 작업에는 효과적으로 작동합니다.

하지만 저는 독립적으로 배포된 여러 서비스가 존재하는 실제 시스템에 이 방식을 적용하려 했을 때 한계에 부딪혔습니다.

역할 기반 조정(Role-Based Coordination)의 문제점

백엔드 검색 서비스와 프론트엔드 관리 콘솔이 있다고 가정해 봅시다. 백엔드 팀이 새로운 API 엔드포인트(endpoint)를 구현하면, 프론트엔드는 이에 맞춰 적응해야 합니다.

역할 기반 프레임워크에서는 이를 위한 자연스러운 메커니즘이 없습니다. 두 에이전트 모두 동일한 시뮬레이션 조직 내의 "개발자"일 뿐입니다. 서비스 경계(service boundaries)에 대한 개념도, 버전 관리된 계약(versioned contracts)도 없으며, "백엔드가 변경되었으니 프론트엔드는 정확히 무엇이 바뀌었는지 알아야 한다"라고 말할 방법도 없습니다.

멀티 서비스 개발에서의 조정 문제는 _"어떤 역할이 이 작업을 처리해야 하는가"_가 아니라, _"어떤 서비스가 이 변경 사항을 알아야 하며, 정확히 무엇이 변경되었는가"_입니다.

이러한 관점의 전환은 저로 하여금 다른 것을 만들게 했습니다.

AgentNexus: 서비스 입도(Service Granularity)에서의 에이전트 조정

AgentNexus는 각 서비스를 일급 시민(first-class citizen)으로 취급하는 문서 교환 센터입니다. 역할 대신 **서비스 경계(service boundaries)**를 조정의 기본 단위(coordination primitive)로 사용합니다.

작동 방식은 다음과 같습니다:

  • 각 서비스는 자체적인 문서 네임스페이스(namespace)를 가진 **하위 프로젝트(sub-project)**로 등록됩니다.
  • 서비스는 버전 관리된 Markdown 문서를 게시합니다: 요구사항(requirements), 설계 사양(design specs), API 문서(API docs), 설정(config)

전체 시스템은 스트리밍 가능한 HTTP(streamable-HTTP) 모드로 실행되는 MCP (Model Context Protocol) 서버로 노출되므로, 여러 에이전트가 서로 다른 머신에서 동시에 연결될 수 있습니다.

차이점 인식 업데이트 프로토콜 (The Diff-Aware Update Protocol)

이 부분은 제가 가장 자랑스럽게 생각하는 부분입니다. 에이전트가 get_my_updates_with_context를 호출하면 다음과 같은 값을 반환받습니다:

{
  "update_id": "...",
  "doc_id": "backend-service/api",
...

에이전트는 무엇이 변경되었는지 (대상 수정 작업을 수행하기 위해)와 전체 현재 상태 (정확한 컨텍스트를 유지하기 위해)를 모두 받습니다. 차이점(diff)만 제공하면 컨텍스트를 놓칠 위험이 있고, 전체 문서만 제공하면 코드에서 무엇을 변경해야 하는지 식별하기 어렵습니다.

구체적인 예시

백엔드에서 새로운 엔드포인트(endpoint)를 구현할 때의 엔드 투 엔드(end-to-end) 흐름은 다음과 같습니다:

  1. 백엔드 에이전트가 push_document를 통해 search-service/api를 업데이트합니다.
  2. AgentNexus가 차이점(diff)을 계산하고 search-admin-frontend를 위한 알림을 생성합니다.
  3. 프론트엔드 에이전트가 get_my_updates_with_context를 호출하여 새로운 엔드포인트를 보여주는 차이점(diff)을 수신합니다.
  4. 프론트엔드 에이전트가 모의 구현(mock implementation)을 제거하고 실제 엔드포인트를 통합합니다.
  5. 프론트엔드 에이전트가 자신의 requirement 문서를 업데이트하여 "백엔드 미구현" 주석을 제거합니다.
  6. 프론트엔드 에이전트가 ack_update를 호출하여 알림을 읽음 상태로 표시합니다.

초기 구독 설정 외에는 인간의 조정이 전혀 필요하지 않습니다.

일급 엔티티로서의 라이프사이클 단계 (Lifecycle Stage as a First-Class Entity)

역할 기반(role-playing) 프레임워크에서 저를 괴롭혔던 한 가지가 더 있는데, 바로 서비스가 개발 라이프사이클(development lifecycle) 중 _어느 단계에 있는지_에 대한 개념이 없다는 점이었습니다.

AgentNexus는 각 서비스의 단계를 명시적으로 추적합니다: design → development → testing → deployment → upgrade. 단계 전환(Stage transitions)은 다음과 같은 실제 작업(operations)을 수반합니다:

  • 발행된 모든 문서의 불변(immutable) 마일스톤 스냅샷 생성
  • 서비스 간 알림(cross-service notifications) 생성
  • 영향을 받는 서비스들에 대한 단계 전환 작업(stage-switch tasks) 생성

서비스가 개발(development)에서 테스트(testing) 단계로 전환되는 것은 의미 있는 이벤트입니다. 이는 단순히 "스크럼 마스터(scrum master)" 역할을 수행하는 에이전트에게 전달되는 프롬프트 지시 사항이 아닙니다.

내가 구축한 것

구현체는 FastMCP, SQLAlchemy/SQLite, 그리고 watchdog을 사용한 Python 기반입니다. http://0.0.0.0:10086/mcp에서 지속적인 MCP 서버로 실행됩니다.

주요 MCP 도구:

  • push_document / patch_document — 전체 또는 증분 업데이트(incremental updates)를 게시합니다.

  • get_my_updates_with_context — 차이점(diff)과 전체 콘텐츠를 포함한 업데이트 확인을 한 번의 호출로 수행합니다.

  • get_my_tasks — 문서 변경으로 인해 생성된 대기 중인 작업(pending tasks)을 검색합니다.

  • generate_steering_file — IDE 에이전트 지침 파일(instruction files)을 자동으로 생성합니다.

patch_document 도구는 특별히 언급할 가치가 있습니다. 업데이트할 때마다 전체 문서 콘텐츠를 보내는 대신, 에이전트는 통합 차이점 패치(unified diff patch)를 보낼 수 있습니다. 이를 통해 문서가 커질 때 Kiro나 Cursor와 같은 IDE에서 도구 호출 페이로드 크기 제한(tool-call payload size limits)에 걸리는 문제를 방지할 수 있습니다.

250개의 테스트(단위 테스트(unit test) + Hypothesis를 사용한 속성 기반 테스트(property-based test))를 완료했습니다. 이 시스템은 한 달 이상 프로덕션 환경에서 두 개의 서비스를 조정하며 실행되고 있습니다.

역할 중심 프레임워크와의 비교

차원ChatDev / MetaGPTAgentNexus
조정 단위 (Coordination unit)에이전트 역할 (Agent role)서비스 (서브 프로젝트)
.........

사용해 보기

git clone https://github.com/dugubuyan/agent-nexus
pip install -e ".[dev]"
python -m alembic upgrade head
...

모든 MCP 클라이언트에서 연결하세요:

{
  "mcpServers": {
    "doc-exchange": {
...

관련 연구 논문은 Zenodo에 있습니다: doi.org/10.5281/zenodo.19692217

LLM 에이전트를 사용하여 멀티 서비스 시스템을 구축하면서 조정(coordination) 문제에 직면해 있다면, 여러분이 무엇을 만들고 있는지 꼭 듣고 싶습니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0