그래프 중심 오케스트레이션
LangGraph 스타일의 graph/state-machine 사고방식을 Vercel의 code-first orchestration으로 매핑하는 방법을 정리합니다.
핵심 요약
- LangGraph의 graph DSL 대신 Vercel은
AI SDK loop + Workflow persistence + explicit state reducer로 같은 오케스트레이션을 code-first로 구현합니다. - node는 Workflow step/tool/subagent, edge는 코드 분기/tool choice/event resume, checkpoint는 Workflow persistence로 매핑됩니다.
- state shape는 앱이 명시적으로 타입 정의하고 reducer는 코드로 직접 구현합니다.
- branch 분기는 model 출력만이 아니라 deterministic guard 조건을 함께 둡니다.
- branch 폭주·tool recursion·approval deadlock에는 max step·deterministic stop·timeout으로 대응합니다.
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 없이 종료되는가