그래프 중심 오케스트레이션
LangGraph 스타일의 graph/state-machine 사고방식을 Vercel의 code-first orchestration으로 매핑하는 방법을 정리합니다.
LangGraph 경험이 있는 팀은 보통 node, edge, state, reducer, checkpoint 관점으로 에이전트를 설계합니다.
Vercel 스택은 같은 문제를 풀 수 있지만, 접근 방식은 다릅니다. graph DSL보다 code-first orchestration에 가깝습니다.
언제 이 패턴을 쓰는가
| 조건 | 적합도 | 이유 |
|---|---|---|
| LangGraph 경험자가 Vercel로 이전함 | 높음 | 개념 매핑이 필요 |
| 노드/엣지 시각화가 핵심 요구임 | 중간 | 직접 모델링 필요 |
| TypeScript async/await 중심으로 구현하고 싶음 | 높음 | Workflow와 AI SDK가 잘 맞음 |
개념 매핑
| LangGraph 개념 | Vercel 대응 |
|---|---|
| node | Workflow step, AI SDK tool, subagent |
| edge | 코드 분기, tool choice, event resume |
| state | workflow payload + app state store |
| reducer | 사용자 정의 merge/update 함수 |
| checkpoint | Workflow persistence |
| human-in-the-loop | defineHook / approval hook |
구조
설계 규칙
| 항목 | Vercel에서의 구현 원칙 |
|---|---|
| state shape | app이 명시적으로 정의 |
| reducer | 코드로 직접 구현 |
| loop control | AI SDK manual loop 또는 Workflow loop |
| branch selection | model output + deterministic guard |
| resume | Workflow event |
최소 구현 스켈레톤
import { generateText, type ModelMessage } from 'ai'
const messages: ModelMessage[] = [{ role: 'user', content: 'Resolve this task' }]
let state = { step: 0, status: 'running' as const }
while (state.step < 10 && state.status === 'running') {
const result = await generateText({
model: 'anthropic/claude-sonnet-4.6',
messages,
tools: {
searchDocs,
requestApproval,
},
})
messages.push(...result.response.messages)
state = reduceState(state, result)
if (result.text) break
}한계와 강점
| 항목 | LangGraph 쪽이 강한 점 | Vercel 쪽이 강한 점 |
|---|---|---|
| graph 표현력 | graph-native DSL | async/await 중심 구현 단순성 |
| 상태 시각화 | 구조적으로 명확 | trace와 로그 관측성 강점 |
| durable execution | 프레임워크 선택에 따라 다름 | Workflow가 기본 제공 |
| runtime 통합 | 별도 조합 필요 | Gateway, Workflow, Sandbox 통합 용이 |
실무 해석
Vercel은 LangGraph처럼 graph DSL을 제공하지 않습니다. 대신 manual loop, subagents, Workflow steps, event resume를 조합해 같은 수준의 오케스트레이션을 구현하는 방식에 가깝습니다.
실패 모드와 fallback
| 실패 모드 | 대응 |
|---|---|
| branch 폭주 | max step 제한 |
| state merge 오류 | typed state + reducer 테스트 |
| tool recursion | deterministic stop condition |
| approval deadlock | timeout + cancel |
운영 지표
| 지표 | 목표 예시 |
|---|---|
| average steps per task | 예산 범위 내 |
| branch distribution | 특정 branch 쏠림 감지 |
| event resume success | 99% 이상 |
| loop abort rate | 5% 이하 |
ADR 스타일 결론
Decision
graph 중심 사고방식은 유지하되, 구현은 graph DSL이 아니라 AI SDK loop + Workflow persistence + explicit state reducer 구조로 가져갑니다. 그래프는 개념 모델이고, 실행은 code-first runtime이
담당합니다.
실무 체크리스트
- state shape가 명시적으로 타입 정의되어 있는가
- branch 분기가 model 출력만이 아니라 guard 조건을 갖는가
- max step과 timeout이 설정돼 있는가
- approval/event resume가 deadlock 없이 종료되는가