멀티 에이전트 아키텍처
AI SDK의 subagent, tool delegation, 역할 분리를 활용한 멀티 에이전트 패턴을 정리합니다.
복잡한 작업을 단일 프롬프트로 해결하려 하면 맥락 오염, 도구 남용, 추론 품질 저하가 동시에 나타납니다. 멀티 에이전트는 이 문제를 역할 분리와 위임 구조로 풀되, 과설계에 빠지지 않는 것이 핵심입니다.
언제 멀티 에이전트가 필요한가
| 조건 | 멀티 에이전트 | 단일 에이전트 |
|---|---|---|
| 도구가 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
멀티 에이전트는 도구가 많거나, 단계별 권한/모델이 달라야 할 때만 도입합니다. AI SDK의 tool 구조로 subagent를 배치하고, 장기 실행은 Workflow step으로 분리합니다. 에이전트별 도구 권한을 분리해 공격면 확대를 방지합니다.
실무 체크리스트
- 단일 에이전트로 충분한 작업을 멀티 에이전트로 과설계하지 않았는가
- 에이전트별 도구 권한이 분리돼 있는가
- delegation depth에 제한이 있는가
- 에이전트별 모델 tier가 역할에 맞게 배정돼 있는가
- subagent 결과의 품질을 독립적으로 평가할 수 있는가