본문으로 바로가기
리옵트 핸드북
리옵트 핸드북
Vercel 엔터프라이즈 AI 플랫폼

플랫폼 기초

플랫폼 아키텍처AI SDK 런타임AI Gateway 제어면

실행 런타임

Workflow 장기 실행Sandbox 실행 격리MCP 데이터 계층Queues & 비동기 작업 관리

프롬프트 & 품질

프롬프트 엔지니어링 & 가드레일RAG & 검색 증강 생성관측성·평가

운영 체계

보안·거버넌스비용·안정성배포 전략 & AI CI/CD

실전 시나리오

고객지원 에이전트 아키텍처내부 리서치 에이전트 아키텍처승인형 백오피스 자동화코딩 오케스트레이션

오케스트레이션 패턴

그래프 중심 오케스트레이션실무 오케스트레이션 플레이북멀티 에이전트 아키텍처

부록

마이그레이션 가이드레퍼런스검증 리포트업데이트 내역
핸드북›Vercel 엔터프라이즈 AI›멀티 에이전트 아키텍처
한국어English

멀티 에이전트 아키텍처

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 payloaddurable, 감사 가능직렬화 제약장기 실행
Shared memory (DB/KV)유연동시성 관리 필요대량 데이터
Artifact (파일/URL)크기 제한 없음읽기 비용리포트/코드

모델 혼합 전략

에이전트마다 모델을 달리 쓰면 비용과 품질을 함께 잡습니다.

에이전트 역할권장 모델 tier이유
Router/Classifierfast tier빠른 판단, 낮은 비용
Researcherquality tier깊은 추론 필요
Writer/Summarizerquality tier출력 품질 중요
Executorfast tier구조화된 출력 위주
Validatorfast 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없음 (분류만)최소 권한
Researcherread-only resourcesMCP resources만 허용
Executormutating toolsapproval + sandbox
Communicator외부 발송 toolsapproval 필수

실무 해석

멀티 에이전트에서 가장 자주 나오는 실수가 모든 에이전트에 모든 도구를 쥐여 주는 겁니다. 역할별로 도구를 나눠 두지 않으면 단일 에이전트보다 공격면이 더 넓어집니다.

실패 모드와 대응

실패 모드대응
에이전트 간 루프max delegation depth 설정
Supervisor 토큰 폭발요약 후 전달, context 압축
Subagent 응답 품질 저하subagent별 eval + fallback
에이전트 간 모순된 결과validator agent 추가
전체 latency 과다병렬 실행 + timeout

운영 지표

지표목표 예시
Total agent calls per task예산 범위 내
Delegation depth3 이하
Subagent success rate95% 이상
End-to-end latencySLA 이내
Token cost per task단일 agent 대비 비교

ADR 스타일 결론

Decision

멀티 에이전트는 도구가 많거나 단계마다 권한/모델이 달라야 할 때만 도입합니다. subagent는 AI SDK의 tool 구조로 배치하고, 오래 도는 작업은 Workflow step으로 쪼갭니다. 에이전트별로 도구 권한을 갈라 두어 공격면이 넓어지는 것을 막습니다.

실무 체크리스트

  • 단일 에이전트로 끝낼 작업을 멀티 에이전트로 과설계하진 않았는가
  • 에이전트마다 도구 권한이 갈라져 있는가
  • delegation depth에 상한을 걸어 뒀는가
  • 에이전트별 모델 tier를 역할에 맞게 배정했는가
  • subagent 결과의 품질을 따로 떼어 평가할 수 있는가

관련 문서

  • Agents: Subagents
  • Agents: Loop Control
  • AI SDK Tools
  • Vercel Workflow

관련 문서

비용·안정성

비용, 지연시간, 에러 버짓을 함께 관리해 엔터프라이즈 AI 제품의 운영 연속성을 확보하는 방법을 정리합니다.

Cmd. /fast

Codex 명령어 마스터 · Fast mode를 켜고 끄거나 현재 상태를 확인하는 /fast 명령. 현재 모델의 서비스 tier를 바꾸며 reasoning effort는 /model에서 별도로 선택합니다.

Cmd. /fast

Claude Code 명령어 마스터 · Opus fast mode를 켜고 끄는 속도 우선 명령 (research preview)

Ch3. 에이전트 설계

OpenCode 고급 활용 · 역할 분리, 커스텀 에이전트 구성, 서브에이전트 활용

Ch5. 접근제어·비밀관리

AI 보안·컴플라이언스 운영 · 사람·서비스·에이전트 권한 분리와 비밀정보 생명주기 운영 표준

실무 오케스트레이션 플레이북

ticket triage, alert triage, approval queue, scheduled reporting 같은 실무 runbook형 오케스트레이션 예제를 정리합니다.

마이그레이션 가이드

LangChain, LangGraph, 커스텀 오케스트레이션에서 Vercel AI 스택으로 전환할 때의 개념 매핑과 전환 전략을 정리합니다.

On this page

언제 멀티 에이전트가 필요한가패턴 분류1. Supervisor 패턴2. Pipeline 패턴3. Delegation 패턴AI SDK에서의 구현Subagent as ToolWorkflow 기반 멀티 에이전트에이전트 간 상태 전달모델 혼합 전략보안 경계 분리실패 모드와 대응운영 지표ADR 스타일 결론실무 체크리스트관련 문서