멀티 에이전트 아키텍처
AI SDK의 subagent, tool delegation, 역할 분리를 활용한 멀티 에이전트 패턴을 정리합니다.
핵심 요약
- 멀티 에이전트는 도구가 10개 이상이거나 단계마다 권한·모델이 달라야 할 때만 쓰세요. 도구 3개 이하 단순 작업이라면 과설계입니다.
- 패턴은 Supervisor·Pipeline·Delegation 세 가지인데, AI SDK에서는 subagent를 tool로 배치하는 방식이 가장 손에 익습니다.
- 모델 tier는 역할별로 섞습니다. Router/Classifier에는 fast tier, Researcher/Writer에는 quality tier를 배정하세요.
- 에이전트마다 도구 권한을 나눠 두지 않으면 단일 에이전트보다 공격면이 오히려 넓어집니다.
- delegation depth는 3 이하로 막고, supervisor 토큰이 폭발하면 요약 후 전달과 context 압축으로 대응합니다.
복잡한 작업을 프롬프트 하나로 끝내려 하면 맥락 오염, 도구 남용, 추론 품질 저하가 한꺼번에 터집니다. 멀티 에이전트는 이를 역할 분리와 위임 구조로 풀어내되, 과설계로 빠지지 않는 선을 지키는 게 관건입니다.
언제 멀티 에이전트가 필요한가
| 조건 | 멀티 에이전트 | 단일 에이전트 |
|---|---|---|
| 도구가 10개 이상으로 증가 | 권장 | 도구 오남용 |
| 작업 단계의 프롬프트/모델 요구사항이 다름 | 권장 | 타협 필요 |
| 서로 다른 보안 권한이 필요한 단계가 있음 | 권장 | 권한 과잉 |
| 전체 작업이 단순하고 도구가 3개 이하 | 과설계 | 충분 |
| 에이전트 간 통신 비용이 작업 이득보다 큼 | 과설계 | 더 효율적 |
패턴 분류
1. Supervisor 패턴
supervisor 하나가 작업을 나눠 주고 돌아온 결과를 종합합니다.
| 장점 | 단점 |
|---|---|
| 작업 분배 로직이 명확 | supervisor가 병목 |
| 결과 종합이 일관됨 | supervisor 프롬프트 복잡도 |
| 에이전트 간 격리가 자연 | 통신 비용 (토큰) |
2. Pipeline 패턴
에이전트가 순차적으로 작업을 넘깁니다.
| 장점 | 단점 |
|---|---|
| 흐름이 예측 가능 | 한 단계 실패가 전체 차단 |
| 각 단계 평가가 독립적 | 유연한 분기가 어려움 |
3. Delegation 패턴
에이전트가 특정 tool로 다른 에이전트를 불러냅니다.
AI SDK에서의 구현
Subagent as Tool
AI SDK의 tool 구조 안에 subagent를 끼워 넣는 게 가장 자연스러운 패턴입니다.
import { generateText, tool } from 'ai'
import { z } from 'zod'
const researchAgent = tool({
description: '주어진 주제에 대해 깊이 있는 조사를 수행합니다.',
inputSchema: z.object({
topic: z.string(),
depth: z.enum(['brief', 'detailed']),
}),
execute: async ({ topic, depth }) => {
const result = await generateText({
model: 'anthropic/claude-sonnet-4.6',
system: '당신은 리서치 전문가입니다. 제공된 도구로 조사하고 요약합니다.',
prompt: `${topic}에 대해 ${depth === 'detailed' ? '상세히' : '간략히'} 조사하세요.`,
tools: { searchDocs, searchWeb },
})
return result.text
},
})
const supervisorResult = await generateText({
model: 'openai/gpt-5.4',
system: '당신은 작업 관리자입니다. 필요한 조사를 위임하고 최종 결과를 종합합니다.',
prompt: userQuery,
tools: { researchAgent, analyzeData, writeSummary },
})Workflow 기반 멀티 에이전트
오래 돌아야 하는 멀티 에이전트는 Workflow step으로 쪼갭니다.
import { generateText } from 'ai'
export async function multiAgentWorkflow(task: string) {
'use workflow'
const plan = await planningStep(task)
const research = await researchStep(plan.text)
return synthesisStep(research.text)
}
async function planningStep(task: string) {
'use step'
return generateText({
model: 'anthropic/claude-sonnet-4.6',
system: 'You are a planning agent.',
prompt: `Break down this task: ${task}`,
})
}
async function researchStep(plan: string) {
'use step'
return generateText({
model: 'anthropic/claude-sonnet-4.6',
system: 'You are a research agent.',
prompt: plan,
tools: { searchDocs },
})
}
async function synthesisStep(research: string) {
'use step'
return generateText({
model: 'openai/gpt-5.4',
system: 'You are a synthesis agent.',
prompt: `Based on this research, produce the final output: ${research}`,
})
}에이전트 간 상태 전달
| 방법 | 장점 | 단점 | 적합한 상황 |
|---|---|---|---|
| Return value | 단순하고 명시적 | 크기 제한 | tool 결과 전달 |
| Workflow payload | durable, 감사 가능 | 직렬화 제약 | 장기 실행 |
| Shared memory (DB/KV) | 유연 | 동시성 관리 필요 | 대량 데이터 |
| Artifact (파일/URL) | 크기 제한 없음 | 읽기 비용 | 리포트/코드 |
모델 혼합 전략
에이전트마다 모델을 달리 쓰면 비용과 품질을 함께 잡습니다.
| 에이전트 역할 | 권장 모델 tier | 이유 |
|---|---|---|
| Router/Classifier | fast tier | 빠른 판단, 낮은 비용 |
| Researcher | quality tier | 깊은 추론 필요 |
| Writer/Summarizer | quality tier | 출력 품질 중요 |
| Executor | fast tier | 구조화된 출력 위주 |
| Validator | fast tier | 체크리스트 기반 검증 |
const classifierAgent = {
model: 'openai/gpt-5-mini', // fast tier
}
const researchAgent = {
model: 'anthropic/claude-sonnet-4.6', // quality tier
}
const validatorAgent = {
model: 'openai/gpt-5-mini', // fast tier
}보안 경계 분리
| 에이전트 | 도구 권한 | 보안 정책 |
|---|---|---|
| Router | 없음 (분류만) | 최소 권한 |
| Researcher | read-only resources | MCP resources만 허용 |
| Executor | mutating tools | approval + sandbox |
| Communicator | 외부 발송 tools | approval 필수 |
실무 해석
멀티 에이전트에서 가장 자주 나오는 실수가 모든 에이전트에 모든 도구를 쥐여 주는 겁니다. 역할별로 도구를 나눠 두지 않으면 단일 에이전트보다 공격면이 더 넓어집니다.
실패 모드와 대응
| 실패 모드 | 대응 |
|---|---|
| 에이전트 간 루프 | max delegation depth 설정 |
| Supervisor 토큰 폭발 | 요약 후 전달, context 압축 |
| Subagent 응답 품질 저하 | subagent별 eval + fallback |
| 에이전트 간 모순된 결과 | validator agent 추가 |
| 전체 latency 과다 | 병렬 실행 + timeout |
운영 지표
| 지표 | 목표 예시 |
|---|---|
| Total agent calls per task | 예산 범위 내 |
| Delegation depth | 3 이하 |
| Subagent success rate | 95% 이상 |
| End-to-end latency | SLA 이내 |
| Token cost per task | 단일 agent 대비 비교 |
ADR 스타일 결론
Decision
멀티 에이전트는 도구가 많거나 단계마다 권한/모델이 달라야 할 때만 도입합니다. subagent는 AI SDK의 tool 구조로 배치하고, 오래 도는 작업은 Workflow step으로 쪼갭니다. 에이전트별로 도구 권한을 갈라 두어 공격면이 넓어지는 것을 막습니다.
실무 체크리스트
- 단일 에이전트로 끝낼 작업을 멀티 에이전트로 과설계하진 않았는가
- 에이전트마다 도구 권한이 갈라져 있는가
- delegation depth에 상한을 걸어 뒀는가
- 에이전트별 모델 tier를 역할에 맞게 배정했는가
- subagent 결과의 품질을 따로 떼어 평가할 수 있는가