Claude Code 에이전트를 병렬로 실행하기

세 가지 모두 응답하면, 오케스트레이터는 변환 엔진이 필요한 것만 전달합니다:

convert /path/to/input.mp4 to H264/AAC target-resolution 1280x720

핵심 제약 사항은 다음 에이전트에 필요한 것만 전달하는 것입니다. 초기에는 형식 분석기의 전체 메타데이터 JSON을 변환 엔진으로 전달했습니다. 그랬더니 엔진이 읽을 필요도 없는 필드를 기반으로 결정을 내리기 시작하더군요. 이제 오케스트레이터는 각 병렬 응답에서 관련 키만 추출하고 병합한 뒤 하위로 전달합니다.

CLAUDE.md 정의

각 에이전트는 좁은 범위의 CLAUDE.md를 가집니다. "하지 말아야 할 것(What You Do Not Do)" 블록은 선택 사항이 아닙니다. 이것이 없으면 에이전트는 사용자가 원한다고 생각하는 것을 멋대로 채워 넣습니다.

오케스트레이터 (핵심 라인):

당신은 조정자입니다. 코드를 작성하지 마십시오. ffmpeg를 실행하지 마십시오.
Fan out to <Format Analyst>, <Engine Check>, and <Metadata Prep> in parallel.
Wait for all three. Then call u/conversion-engine with merged output.
One retry maximum on FAIL. Log the reason. Return the error to a human.

형식 분석기 (전체 출력 계약):

Return ONLY this JSON:
{
"codec_video": "H.264" | "HEVC" | "VP9" | "AV1" | "unknown",
"codec_audio": "AAC" | "AC3" | "MP3" | "unknown",
"resolution": { "width": number, "height": number },
"bitrate_kbps": number | null,
"duration_seconds": number | null,
"meets_spec": boolean,
"mismatch_reason": string | null
}
Run: ffprobe -v quiet -print_format json -show_streams [filepath]
Do not convert. Do not suggest fixes. Return the JSON and stop.

다이어그램이 보여주지 않는 세 가지 문제

컨텍스트 비대화. 오케스트레이터는 긴 배치 세션 동안 모든 병렬 에이전트로부터 도구 응답을 누적하고 있었습니다. 열 번째 비디오쯤 되면 더 이상 필요 없는 9개의 출력값을 가지고 있었고, 그 죽은 무게가 현재 비디오에 대한 결정에 영향을 미치고 있었습니다.

Harbor는 오케스트레이터와 도구 사이에서 실행 계층으로 자리 잡습니다. 각 에이전트는 도구 호출을 요청하고, Harbor는 해당 에이전트가 실행할 수 있는 범위를 지정하며, 샌드박스에서 실행하고, 결과를 공유 작업 공간에 씁니다. 오케스트레이터는 컨텍스트 창에 도구 출력을 보관하지 않습니다. Harbor가 보관하죠. 파일, 아티팩트, 추적은 전체 배치 실행 동안 그곳에 유지됩니다. 형식 분석기는 보행 엔진 엔드포인트를 실수로 건드릴 수 없고, 엔진 체크 에이전트는 디스크에 쓸 수 없습니다. Harbor가 각 에이전트에게 허용된 범위만 부여하기 때문입니다.

재시도 지속성. Validator가 FAIL을 반환하고 재시도를 트리거했을 때, 오케스트레이터는 첫 번째 시도가 왜 실패했는지에 대한 지속적인 기억이 없었습니다. Temporal은 단계 간 워크플로우 상태를 저장하므로, 실패한 변환은 전체 병렬 팬아웃을 처음부터 다시 실행하는 대신 멈춘 지점에서 정확히 다시 시작합니다.

실행 가시성. 병렬 실행 전반의 에이전트별 비용은 불투명했습니다. Agno의 내장 런타임은 별도의 관찰 가능성 스택 없이도 에이전트별 실행 지표를 표면화합니다. 이는 50개 이상의 비디오 배치를 처리할 때 어떤 에이전트가 토큰을 태우고 있는지 알아야 하므로 중요합니다.

이 파이프라인은 3주 동안 안정적으로 유지되고 있습니다.