MadoHub로 멀티 에이전트 워크플로 만들기

단일 AI 에이전트를 돌리는 것은 쉽습니다. 서로의 출력에 의존하는 다섯 개의 에이전트를 돌리는 순간 일이 흥미로워지고, 대부분의 도구가 약해지는 지점이 나타납니다.

이 글은 타일 배치부터 라우팅 규칙 설정까지, MadoHub에서 멀티 에이전트 워크플로를 만드는 방법을 설명합니다.

출력부터 시작하세요

캔버스에 타일을 놓기 전에 최종 출력이 무엇인지 먼저 정하세요. 결과에서 거꾸로 생각하면 어떤 중간 단계가 필요한지 강제로 고민하게 됩니다.

예를 들어 테스트가 포함되고 문서화된 API 엔드포인트를 만들고 싶다고 해봅시다. 최종 출력은 구현, 테스트, 문서를 포함한 pull request입니다. 거꾸로 보면:

• PR composer 에이전트가 최종 출력을 묶습니다
• test writer 에이전트가 테스트 파일을 만듭니다
• docs writer 에이전트가 API 문서를 생성합니다
• code generator 에이전트가 구현을 작성합니다
• spec parser 에이전트가 자연어 설명에서 요구사항을 추출합니다

캔버스에 타일 배치하기

각 에이전트는 타일이 됩니다. MadoHub에서 타일은 독립적인 실행 환경이며, 각자 자신의 문맥, 모델 설정, 시스템 프롬프트를 가집니다.

spec parser를 캔버스 왼쪽에, PR composer를 오른쪽에 배치하세요. 중간 에이전트들은 대략 실행 순서에 맞춰 그 사이에 둡니다. 이 좌→우 레이아웃은 데이터가 시스템을 따라 흐르는 방식과 닮아 있습니다.

연결 정의하기

Connection은 타일 사이의 방향성 있는 간선입니다. spec parser의 output port에서 code generator의 input port로 연결을 그리면, MadoHub에게 파싱된 명세를 코드 생성 프롬프트에 넣으라고 지시하는 것입니다.

타일은 여러 입력을 받을 수 있습니다. test writer는 파싱된 명세와 생성된 코드를 둘 다 받아, 명세에 맞고 실제 구현을 호출하는 테스트를 작성할 수 있습니다.

라우팅 전략

상류 출력이 나타나는 순간 모든 연결이 발화해야 하는 것은 아닙니다. MadoHub의 각 연결에는 trigger가 있습니다.

• on-complete: 상류 에이전트의 세션이 완료된 것으로 감지되면 발화
• on-idle: 상류 에이전트의 터미널이 idle 상태가 되면 발화
• on-keyword: 상류 출력에 설정된 키워드가 나타나면 발화
• always: 완료 신호 없이, 새로운 출력 청크가 생길 때마다 발화

내부적으로 on-complete와 on-idle은 동일한 방식으로 처리됩니다——둘 다 트리거 신호가 발생한 후 짧은 idle 타이머(약 8초)를 기다렸다가 라우팅합니다. 두 개의 독립된 전략이라기보다는, 시작 이유만 다른 동일한 일시 정지라고 생각하면 됩니다.

각 연결에는 transform도 있어서 실제로 downstream에 전달되는 내용을 결정합니다: raw(가장 최근 몇 줄을 그대로), summary(AI가 생성한 요약), full-output(더 넓은 최근 구간), prompt-wrap({output}, {round} 같은 변수를 사용하는 사용자 정의 템플릿), ai-routing(API key 설정이 필요한, AI가 생성하는 맥락 인지 프롬프트).

우리의 API 워크플로에서는 spec parser에서 code generator로 가는 연결을 on-complete 트리거에 full-output transform으로 설정하고, code generator에서 test writer와 docs writer로 가는 연결을 모두 on-complete 트리거에 raw transform으로 설정할 수 있습니다——code generator의 세션이 완료로 보고되는 즉시 두 downstream 에이전트가 같은 최근 출력을 바탕으로 시작합니다.

실패 다루기

에이전트는 실패합니다. 모델은 환각을 일으킵니다. 출력이 항상 기대와 일치하지는 않습니다. 견고한 멀티 에이전트 워크플로에는 라우팅된 루프가 끝없이 돌지 않도록 막는 가드레일이 필요합니다.

MadoHub의 루프 방지는 출력 검증이 아니라 라운드 수를 기준으로 동작합니다: 라우팅되는 각 연결에는 maxRounds 상한(기본값 5, 1~20 사이로 설정 가능)과 라운드 사이의 cooldown(기본값 3초, 최대 30초까지 설정 가능)이 있어서, downstream 에이전트가 실제로 응답할 수 있는 속도보다 빠르게 재트리거되지 않도록 합니다. stopKeyword도 설정할 수 있는데——대소문자를 구분하지 않는 임의의 부분 문자열, 예를 들어 "LGTM"——에이전트의 출력에 이 키워드가 포함되는 순간 루프가 멈춥니다.

MadoHub에 내장된 Peer review flow가 정확히 이렇게 동작합니다: Claude Code author와 Codex reviewer가 루프로 연결되어 있고 stopKeyword는 "LGTM"으로 설정되어 있습니다——reviewer는 그렇게 말할 때까지 계속 피드백을 보내고, 그 지점에서 루프가 멈춥니다. 내장된 Pipeline flow는 더 단순합니다: 첫 번째 에이전트의 full-output이 완료 시 두 번째 에이전트로 전달되는 2단계 핸드오프입니다. 내장된 Watcher flow는 처음부터 끝까지 키워드로 트리거되며, ai-routing transform을 사용해 일치한 문구를 맥락 인지 후속 프롬프트로 변환합니다.

반복이 핵심입니다

캔버스 기반 멀티 에이전트 워크플로의 진짜 장점은 반복 속도입니다. security reviewer를 code generator와 PR composer 사이에 새로 추가하는 일은 몇 초면 됩니다. 타일 하나 놓고, 연결 두 개를 그리고, 워크플로를 업데이트하면 끝입니다.

파이프라인을 코드로 정의하는 시스템에서 이걸 해보세요. 설정 파일을 수정하고, 프로세스를 재시작하고, 스키마가 여전히 유효하길 바래야 합니다. 캔버스에서는 피드백 루프가 즉각적입니다.